Version: 10.0

HTML as a template

In addition to converting existing standard HTML documents with the "Converter" web service and converting URLs with the "URLConverter" web service, webPDF can also use HTML documents that define a template used as a basis for new PDF documents.

webPDF uses the FreeMarker template engine to convert an HTML document into a template. In addition to HTML syntax and CSS styling, you can use macros defined by the [FreeMarker Template Language] (https://freemarker.apache.org/docs/ref.html) to create dynamic documents.

These HTML templates can then be used as a basis and dynamically filled with content (variables) to create new PDF documents. In this context, both the template and the variables are dynamically passed in the parameters when the web service is called.

tip

An example of template use via the portal can be found here.

When designing such HTML document templates, you can use all HTML and CSS syntax (in addition to the template engine). The HTML document (HTML template) you create will then be converted to a PDF document with the "Converter" web service and the Chromium engine.

tip

For more information on the FreeMarker template engine, please visit https://freemarker.apache.org/docs/index.html

Template execution

When you call the Converter web service, you pass the defined HTML template as the source file (the document to be converted). with the parameters for the "Converter" web service and set the useAsTemplate attribute to true in the html section.

POST /converter/{documentId}

In the parameters for the "Converter" web service, set the useAsTemplate attribute in the html section to true. This causes the HTML code to be treated as a template and processed by the template engine before the actual display as HTML and CSS begins.

{
  "converter": {
    "html": {
      "adjustFonts": false,
      "baseURL": "",
      "downloadImages": false,
      "templateData": {
        "source": "value",
        "uri": "",
        "value": ""
      },
      "useAsTemplate": false,
      "useBackground": true
    }
  }
}

Before the actual conversion, the appropriate variables are replaced and macros are executed. This may result in modified HTML/CSS code. The HTML document is then converted to PDF using the Chromium engine.

Variables need to be passed in <templateData>, in the parameters, as a "Base64-encoded" JSON object.

{
  "page1": "Text for page 1",
  "page2": "Text for page 2",
  "page3": "Text for page 3",
  "image": {
    "name": "Warning!",
    "data": "data:image/png;base64,iVBORw0KGgoAAAAN...SUhEUgAABJwAAAMRCAIAAAAmxTsD"
  }
}

The JSON object will then be converted to FreeMarker variables during the conversion. These variables will have ${custom. ...} as a prefix, and can be used this way in the HTML document.

<html>
<head>
    <meta http-equiv="content-type" content="text/html;charset=UTF-8"/>
    <style type="text/css" media="print">
        div.page {
            page-break-after: always;
            page-break-inside: avoid;
        }
        </style>
</head>
<body>
<div class="page">
    <h1>This is Page 1</h1>
    <i>${custom.page1?upper_case}</i>
    <br>
    ${custom.image.name}<img src="${custom.image.data}" width="100" height="100"/>
</div>
<div class="page">
    <h1>This is Page 2</h1>
    <b>${custom.page2}</b>
</div>
<div class="page">
    <h1>This is Page 3</h1>
    <u>${custom.page3}</u>
</div>
</body>
</html>

You can use this method to define complex HTML documents with macros and variables and create new PDF documents that are generated dynamically during conversion.

Template execution​

Template execution