Document templates

In the previous guides you have learned the syntax of the Ultradox template language. Now it is time to learn how to leverage the template language in your documents to produce personalized emails, contracts, reports, websites and more.

When using the Ultradox template language in templates created with Google Docs, LibreOffice or Word you will get some additional magic like auto-expanding tables and lists and image manipulation capabilities.

Create a blank Ultradox flow and add the Google Docs to PDF building block.

Click on given file to open the file picker. Pick an existing document or create a blank new document.

You can use the same template syntax to insert data from a variable into your document

Hello ${name}

Switch back to the Ultradox editor and wait for a while or click on the reload icon in the building block to scan the template and track down all the variables in your document.

To test your template you'll have to enter a value for your name variable. The easiest way to assign a value to the variable is to add a form.

Clicking on the keyboard icon in the input parameter section of your building block will create a form with an input field for each of the detected variables.

To test your template you can enter data into the form and click on the Save button.

To generate and preview the document click on the preview icon either in the Ultradox Template Editor or in the building block generating the PDF document.

The generated PDF document will open in a new browser window.

Auto-expand tables and lists

When working with document templates you create nicely formatted tables and lists from your data by simply creating a table or list with a single row and inserting a variable representing multiple items.

Ultradox will then take the given row as a blueprint and creates a row for each item in your variable.

As we have seen in the previous sections, variables may contain a list of values.

If you are for example loading a worksheet from your Google Sheet that consists of two columns called name and email you will find variables for each column looking like this:

row[].name

row[].email

The square brackets indicate that the variable row contains multiple items with two named values each, name and email. These variables are suitable for being used in tables and lists.

An icon on the right of the variable indicates whether a variable can be used in a table or list or not: Three tiny lines indicate that this variable contains multiple values, one line indicates that this variable represents a single value.

If you use these variables in lists or tables in your template, just insert them into the list or table. Ultradox will then auto-expand the table or list to create a row for each item in your list.

When inserting list variables into tables or lists, use square brackets instead of curly braces. Start the tag with $[ followed by the variable name and close the tag with ].

Lists

Let us now create a list from the rows in your worksheet.

Simply create a list in your Google Document by clicking on one of the list types.

Insert the variable that contains multiple values into the list like this:

1. $[mysheet[].name]

Please note that Ultradox will only create rows and list items if you use square brackets instead of curly braces!

A preview of the document may look like this:

1. Daniel Florey
2. Oliver Zeigermann
3. Esther Cornils

The generated document will contain a list containing the values from the name column in your sheet.

That was easy, right?

Tables

In the same way you can create dynamic tables.

Insert a table with two rows and two columns into your template. Insert the column headers into the first row and the variables into the second row so that our table looks like this:

Name	Email
$[mysheet[].name]	$[mysheet.email]

Note that you can use all the formatting capabilities of Google Docs like table background color, font sizes etc.

Generate the document from your template and you will get a nicely formatted table:

Name	Email
Daniel Florey	[email protected]
Oliver Zeigermann	[email protected]
Esther Cornils	[email protected]

Note that processing of elements can be in any order. So processing of an early element may not start because of an error in a later element.

But that is not all!

You can quite easily create different row styles for even and odd rows.

Just add another row to your table in the template containing the same variables.

Add a different background color or any other formatting to the new row so that your table may look like this:

Name	Email
$[mysheet[].name]	$[mysheet.email]
$[mysheet[].name]	$[mysheet.email]

In this example the second row now has a different background color.

The generated document will now use the different row styles as a blueprint for the alternating rows in the generated table:

Name	Email
Daniel Florey	[email protected]
Oliver Zeigermann	[email protected]
Esther Cornils	[email protected]

Advances techniques

Displaying multi-level data

Author	Books
$[authors[].name]	${foreach row.books book}${book.title} ${end}

In this example the second cell contains a list of books for the author in the first cell of the row..

Generate the document from your template and you will get a nicely formatted table:

Author	Books
Arnon Grunberg	Mit Haut und Haaren Tirza
Fjodor Michailowitsch Dostojewski	Schuld und Sühne Die Brüder Karamasow

Using conditions in auto-generated tables and lists

As you have learned in the previous sections you can generate tables and lists from structured data and you can use conditions in your templates.

With Ultradox you can combine these techniques to achieve great results.

You can use if statements in a cell to apply conditional formatting or display different content based on a condition.

If you have a variable called highlightPrices you may want to use this variable to toggle if prices should be rendered in bold in your table:

Description	Price
$[items.description]	${if highlightPrices}$[items.price]${else}$[items.price]${end}

If you want to apply formatting or content based on the value of a column in the current row, you can access the column using the row prefix.

Example: If you have a column in your table called specialOffer you can access it in an if statement using row.specialOffer as variable name:

Description	Price
$[items.description]	${if row.specialOffer}Special Offer: $[items.price]${else}$[items.price]${end}

Please note that the if statement only supports very simple syntax.

If you need to do more complex conditions, use the Calculate building block which will help you to create a new column on the fly based on more complex expressions.

Format rows based on conditions

If you use the if tag at the beginning of the first cell and use the matching end at the end of the last cell in the row, the complete row will only appear the condition is met. This is great if you for example want to use a different background color for the row:

Description	Price
${if row.specialOffer}$[items.description]	$[items.price]${end}

In this example the row gets highlighted with a green background based on the value of the specialOffer column. If no if statement is matching, the default formatting will be applied.

Description	Price
${if row.specialOffer}$[items.description]	$[items.price]${end}
$[items.description]	$[items.price]

As a final example let's use a complex table with two different conditions and automatic formatting for even and odd rows for all row not matching any of the conditions.

To apply a different formatting for even and odd rows we can simply create two rows without any conditions (in our example row 3 and 4) and apply the desired formatting for even (row 3) and odd (row 4) rows.

At the bottom of the table we'll append some rows displaying the subtotal, vat and totals as this is a pretty common use case.

Note that the variables for subtotal, vat and total and used with curly braces instead if square brackets as they just contain a single value and should not be expanded into multiple rows.

As shown in this example you can also use conditions in rows that are not going to be expanded.

Description	Price
${if row.specialOffer}$[items.description]	$[items.price]${end}
${if row.outOfStock}$[items.description]	$[items.price]${end}
$[items.description]	$[items.price]
$[items.description]	$[items.price]
${if vat}Subtotal	${subtotal}${end}
${if vat}VAT	${vat}${end}
Total	${total}

Formatting images

Ultradox allows you to generate and embed images on the fly into your documents.

You can insert charts, contact photos, maps or any other image that is available on the net.

Let us getting started by inserting an image by URL. This will allow you to embed different images into your documents by simply passing the URL of the image as a parameter. Insert a new variable into your document and use the image renderer to tell Ultradox to treat the content of your variable as an image URL:

${logo;image}

After reloading the template the new variable will show up as an input parameter. For testing purposes you can create a test form by clicking on the keyboard icon in the input parameter section.

In the form, enter the URL of an image into the form field for the ${logo} variable.

Let us pick an image from the internet and enter the URL:

https://www.Ultradox.com/logo.png

Click on the preview button to view the generated document: Just as expected the image shows up in the generated document. You can adjust the size of the image by passing the desired width and height:

${logo;image(width=2cm;height=2cm)}

Change your template and either click again on the preview button or simply reload the generated document. Your changes will be reflected immediately.

Expert tip: If you want to trigger the generation from your own application or website you can simply add a parameter called logo to the URL and override the specified image URL that we have entered into the form field.

Check out the renderer reference for a full description of the formatting capabilities of the image renderer.

${logo;image(width=2cm;height=2cm)}

{
"logo" : "https://www.Ultradox.com/logo.png"
}

Formatting maps

Wouldn't it be nice to render postal address as a map?

With Ultradox you can do just that - and it is quite simple. To render the address as a map, just type

${address;map(width=10cm;height=5cm;res=1000x500)}

The generated map has a width of 10 cm and a height of 5 cm. Please note that the resolution should also reflect this ratio as your map will look distorted otherwise.

Check out the renderer reference for a full description of the formatting capabilities of the map renderer.

<p>Hey ${name}!</p>
<p>Pick up your order here:</p>
${address;map(width=200px;height=100px;res=400x200)}

{
"name" : "Larry",
"address" : "1600 Amphitheatre Parkway,Mountain View,CA 94043"
}

Learn more

The following guides will cover the aspects of the templating language.

Internationalization | Renderer Reference | Template errors

Questions and Feedback

If you have any comments on this page, feel free to add suggestions right to the Google document that we are using to create this site.

If you are not yet member of the Ultradox community on Google+, please join now to get updates from our end or to provide feedback, bug reports or discuss with other users.

Last Updated: 1/3/20

Guides / Templates / Document templates