Images in html templates

When adding images to your html based pdf templates, there are a few things to be aware of. If you are used to editing html for the web, very much is the same, but we just wanted to share some pros and cons of the options available that could help you make your templates more flexible.

Absolute Url

If you have an image that is available online, you can always create a regular img-tag in your html template that sets an absolute url as the src-attribute.

Example using the PdfBroker.io logo from our website.

<img src="https://www.pdfbroker.io/assets/img/logo/pdfbroker_logo.svg" />

Pros

• The simplest way to add an image to a template. No coding required.
• Smallest request payload to the PdfBroker.io api since the image is downloaded as part of the pdf generation.

Cons

• You have a dependency to an external resource that you don't know if it is available at the time of generating the pdf.
• With external dependency, it is harder to predict the time it takes to generate a pdf.
• Static resource. Requires coding that parses your html template to change image on individual requests.

Data Uri

Using a data uri you inline the actual image file as base64 encoded string directly in the src-attribute. That makes sure it is always part of the request, and can be processed by the api without external dependencies.

Example using the PdfBroker.io logo in data uri format.

<img src="data:image/svg+xml;base64,PHN2ZyBpZD0iTGF... Content removed for readability" />

Pros

• The full image is embedded in the request. No external dependency that may be unavailble.

Cons

• Request payload is a bit larger since the full image is part of the request body
• Same as with the absolute url, it is a static resource. Requires coding that parses your html template to change image on individual requests.
• Template gets a bit hard to edit with a texteditor since it contains long base64-encoded strings.

Images in the Resource object

When you add resources to your request to the api, and provide the template markup in the htmlBase64String-property, the api will resolve the files at the time of pdf generation. This means that you can enter a static src-attribute in your template, provide a resource entry in the request, but exchange the data, perhaps an image uploaded by your users.

Example using the PdfBroker.io logo and providing the image file in the resource object of the api request.

<img src="pdfbroker_logo.svg" />

Example JSON request when adding the image as a resource

{
    "url": null,
    "htmlBase64String": "PCFET0NUWVBFIGh0bWw.... Content removed for readability.",
    "wkHtmlToPdfArguments": null,
    "resources": {
        "pdfbroker_logo.svg": "PHN2ZyBpZD0iTGFnZXJfMS.... Content removed for readability"
    }
}

Pros

• The full image is embedded in the request. No external dependency that may be unavailble.
• Full flexibility in changing the image on every request without changing the template
• The template is remains easy to edit in texteditor since you only need to set resource name as src-attribute

Cons

• Request payload is a bit larger since the full image is part of the request body
• Harder to manually preview template with browser or WYSIWYG-editor since no image files are available without copying template and image files to temporary folder, but if you use the PdfBroker Template Tool the functionality to preview template is available in the Html template editor.

Note about SVG-files

For svg-files to render in wkhtmltopdf, they must have both width and height set, either with attributes on the img-tag or with css-styling.

Images in CSS

When referencing images in your css using a url value, e.g. background-image: url('https://www.pdfbroker.io/assets/img/logo/pdfbroker_logo.svg'), the path cannot be a relative path in our api. This means you cannot provide images in the resource object of the request that should be used in css-styling. Images in css must be either absolute url, or an inline data uri to be resolved properly.

Only options for background images

body {
    background-image: url('https://www.pdfbroker.io/assets/img/logo/pdfbroker_logo.svg');

    background-image: url('data:image/svg+xml;base64,PHN2ZyBpZD0iTGF... Content removed for readability');
}