Templates

The PDF generator uses templates as a set of essential parts to generate a PDF.

The template consists of the following properties.

property	type	required	description
code	string	Y	a unique reference written in lowercase + underscores
XML config	xml string	Y	A configuration file that is used to dynamically manage data for the PDF generation
assets	zip file	Y	A set of html of html.twig files, icons, images and fonts files that will render your result.
locales	list, multiselect	Y	The selected locales you will render, 1 locale per file.
attribute_to_save_to	list, single select	N	If you wish you can save the generated PDF as a file onto this attribute
required_attributes	list, multiselect	N	a set of required attributes that need a value in order to render

XML config

The XML configuration specifies what information of the product data that you wish to feed as data.

It also specifies what dynamic blocks should be rendered in combination with its' configuration.

You can find more information about these blocks here.

Here is a basic example, we don’t specify much, just the title of the page that will be placed inside the header.

We also specify a link to the assets collection

<body link='template.html.twig'>
 
    <title>My Title</title>
 
</body>

Let’s continue the configuration file and add a dynamic block.

We are adding a paragraph block with a label and some content.

<body link='template.html.twig'>
 
    <title>My Title</title>
 
   <blocks>
        <paragraph label="{{ trans('advantages') }}">
            {{ normalize('advantages') }}
        </paragraph>
   </blocks>
 
</body>

Let’s add some more blocks to the blocks node.

Here we added a table to render, we render the SKU, color and size as columns.

And in order for our table to render successfully, we provide a source that is coming from our product associations called pack.

Find more about product sources here.

<body link='template.html.twig'>
 
   <title>My Title</title>
 
 
   <sources>
      <source code='associations:pack'>
           <family code='smartphones' />
       </source>
   </sources>
 
   <blocks>
        <paragraph label="{{ trans('advantages') }}">
            {{ normalize('advantages') }}
        </paragraph>
        <table
            label="{{ trans('table.variants') }}"
            source="associations:pack"
            column="sku,color,size">
        </table>
   </blocks>
 
</body>

Assets Collection

Every template needs an asset collection. An asset collection allows you to determine the layout of your pdf. For more info check the ‘assets’ tab.

Template Context

The template will have to provide some context to the render engine in order to render the correct Data Set.

You can overrule these values if needed.

More information about context overruling inside functions can be found here

{
        "locale": "en_US",
        "scope": "ecommerce"
        ...
}

Dynamic Content

So rendering static content should not be that hard, you can use most of HTML / CSS tricks in your sleeve to create the perfect design.

In order to make dynamic content possible we need a dynamic language called twig.

Twig is an easy syntax to learn but hard to master, so we limit our usage of twig syntax only to places where it counts.

We separate our dynamic in two distinct ways.

Dynamic Functions and Dynamic Blocks.


Dynamic Functions	Functions that will render the correct value based on it’s context.
Dynamic Blocks	Blocks that will render values into a reusable structure like a table, section based on its' input data.