Skip to main content

Engines

In the reportgen API, an engine is used to process HTML templates with dynamic data, generating a PDF file. Engines allow you to combine a static HTML layout with your custom data, making it easy to create personalized documents such as invoices, reports, and more.

The reportgen API supports four different engines:

  • GoTempl: A Go-based templating engine.
  • EJS: A popular templating language for embedding JavaScript in HTML.
  • Handlebars: A logic-less templating language that focuses on simplicity.
  • Raw: Direct HTML to PDF conversion without any templating.

Below, you'll find detailed explanations of each engine and examples of how to use them.

If you intend or are using Javascript as your language, we suggest you stick with either EJS or Handlebars templating engines

1. GoTempl​

GoTempl is a Go-based templating engine. It uses a simple syntax to substitute dynamic data into your HTML.

Example​

HTML Template (GoTempl):

<html>
  <body>
    <h1>Hello {{.Name}}!</h1>
    <p>Your order total is: {{.Total}}</p>
  </body>
</html>

Payload:

{
  "html_template": "<html><body><h1>Hello {{.Name}}!</h1><p>Your order total is: {{.Total}}</p></body></html>",
  "data": {
    "Name": "Alice",
    "Total": 150
  },
  "engine": "gotempl"
}

In this example, {{.Name}} and {{.Total}} are placeholders replaced by the provided data.

2. EJS​

EJS (Embedded JavaScript) is a flexible templating engine that allows you to embed JavaScript code within your HTML templates.

Example​

HTML Template (EJS):

<html>
  <body>
    <h1>Hello <%= Name %>!</h1>
    <p>Your order total is: <%= Total %></p>
  </body>
</html>

Payload:

{
  "html_template": "<html><body><h1>Hello <%= Name %>!</h1><p>Your order total is: <%= Total %></p></body></html>",
  "data": {
    "Name": "Bob",
    "Total": 200
  },
  "engine": "ejs"
}

With EJS, you use <%= %> to output variables dynamically into the HTML template.

3. Handlebars​

Handlebars is a logic-less templating engine designed for simplicity and readability. It uses double curly braces to denote variables.

Example​

HTML Template (Handlebars):

<html>
  <body>
    <h1>Hello {{Name}}!</h1>
    <p>Your order total is: {{Total}}</p>
  </body>
</html>

Payload:

{
  "html_template": "<html><body><h1>Hello {{Name}}!</h1><p>Your order total is: {{Total}}</p></body></html>",
  "data": {
    "Name": "Charlie",
    "Total": 250
  },
  "engine": "handlebars"
}

Handlebars templates are very straightforward, using {{variable}} for outputting dynamic data.

4. Raw HTML to PDF​

The Raw option allows you to generate a PDF directly from your HTML without using any templating engine. This is useful when your HTML does not need to be dynamically modified and is already complete.

Example​

HTML Template (Raw):

<html>
  <body>
    <h1>Welcome to reportgen!</h1>
    <p>This is a static PDF document.</p>
  </body>
</html>

Payload:

{
  "html_template": "<html><body><h1>Welcome to reportgen!</h1><p>This is a static PDF document.</p></body></html>",
  "engine": "raw"
}

With Raw, no dynamic substitution occurs. The provided HTML is converted directly to a PDF.

Choosing the Right Engine​

  • GoTempl: Ideal for Go-based environments or when working closely with Go code.
  • EJS: Great for JavaScript developers familiar with embedding logic in HTML.
  • Handlebars: Use it when you need a simple, clean template without much logic.
  • Raw: Perfect when you don’t need any templating and have pre-built HTML ready for PDF conversion.

Each engine serves a different purpose, giving you flexibility based on your project needs.