Introduction to template syntax

Docmosis template tutorials are a series of short lessons explaining key features when creating templates.

These tutorials are designed as an entry point for learning the essential template features.

This video provides an overview of basic Docmosis template syntax.

Mastering the basics

If you are just starting out, we recommend completing these top ten tutorials in the order listed below.

Each lesson builds on the previous one, providing a structured approach to learning the basics of template creation.

Transcript

This video gives an introduction to the Docmosis templating syntax. When we were designing Docmosis, we wanted to be able to generate documents from templates and be able to create those templates using Microsoft Word or Libre Office Writer. These editors have evolved over decades to become the class-leading software for creating business documents. In this video, we will be using Microsoft Word and this template to explore the templating syntax.

Creating fields (00:34)

As you can see, Docmosis fields are plain text and created just by typing. This field is created by typing less-than, less-than, greater-than, greater-than and the name of the data item in the middle.

During the document generation process, Docmosis will replace the fields in the template with the data, to generate the final document. There's no difference between this version of Word and the version that you might have. There are no special plugins needed to create templates. This means anyone on your team, whether they're technical or non-technical, can create and edit templates.

Using Docmosis, you can conditionally include and remove content, format dates and numbers, dynamically insert images, and loop over repeating data and insert the data into a table.

We'll be covering all of these features in this video. To see Docmosis in action, we will be using our cloud product.

Once you have created a cloud account, you can immediately start experimenting with templates. Let's upload the example-template to the cloud. From the render page, we can simulate merging data with the template to generate a document.

Each of the Docmosis products can generate sample JSON or XML data based on the fields in the template.

Let's generate some sample J-SON data. J-SON is constructed of simple key and value pairs. Docmosis has found the first name and last name fields and created some sample values. In this demonstration, we'll be using some data we've pre-prepared.

With our data in place, we will select the PDF output format. Clicking the render button sends the data to the service, which merges the data with the template. You can see the fields have been replaced with the data.

Let's make some simple edits to the template by applying formatting to these fields, like color and bold, font size and alignment.

We should firstly save those changes. Upload the template, then regenerate the PDF.

You can see that the formatting of the fields flows through to the generated document. Let's return to the template and explore some of the other Docmosis syntax.

Optionally removing paragraphs (03:18)

You can see that some fields have two characters followed by a colon or an underscore. In this case, the characters O and P creates an optional paragraph.

If there is data for this field, the paragraph will appear in the generated document. However, if there's no data, the paragraph will be removed.

When editing templates, it's good practice to turn on the hidden characters. This allows you to see the structure of the template with dots for spaces, arrows for tabs, and these symbols to see the beginning and end of paragraphs.

In this case, depending on the value for Address Line 2, all of the content from the last paragraph-marker up to the next one will be removed.

Let's see that in action. If we save these changes and upload the template, you can see that Address Line 2 currently has no data.

When we generate the document, the city and state will appear immediately underneath the first address line. If there is data for Address Line 2, then space will be made to include that line. This is one way to conditionally include and remove content from a document.

Conditionally removing content (04:35)

Further down the template, you'll see there is a field using the characters CS and an underscore to create a conditional section.

The CS is the start and the ES is the end of the conditional section. All of the content between the CS and the ES will be included or removed based on the value of Require Supporting Docs.

In the data, Require Supporting Docs is set to true. When the document is generated, the text is included in the generated document.

Let's change the data to false. When the document is generated, the text will be removed. If we switch between the first document and the second one, you can see the content being included and removed from the document.

The conditional section is one of the most powerful features in templating. It can be used to remove parts of a sentence, entire paragraphs, multiple pages, images, tables, and so on.

The conditional section really is the workhorse of document generation.

Let's turn off the hidden characters. Further down this template, we'll find another conditional section.

The conditional section starts here and ends here, which means all of this content will be added or removed from the final document.

In this case, the curly braces are used to invoke the Docmosis expression processing. Inside curly braces, you can perform calculations or logic and call more than 40 different functions.

In this conditional section, the value of offerExpiryDate is being compared to null to determine whether or not this content should be included. Let's focus on the words "Your application" in the generated document.

We will now delete the offerExpiryDate so that it's no longer present in the data and then regenerate the document.

You can see that the entire line is removed from the document. Let's reinstate that value in the data and have a closer look at the offerExpiryDate.

The data is set to zero-seven, sixteen, twenty-twenty. This is used to indicate the 16th day of July 2020.

Data formatting (06:42)

In the template, inside this conditional section, there is another field that uses offerExpiryDate. The curly braces invoke Docmosis' expression processing.

The date formatting function will read the offerExpiryDate and display it formatted differently in the document.

Docmosis uses this string with month, day, and year to decode the incoming data. This second string controls how the date will be displayed in the generated document.

That's why, in the document, you can see Thursday, the 16th of July 2020. Of course, we provide extensive documentation on all of the different characters you can use to create formatting strings.

While having this sort of power in the template is handy, it's not essential that you use this function.

If we return to the data, there is another date, the letter date. This has already been formatted and is ready to use in the generated document.

In this case, the template just has a simple field to display the date, and the date will appear exactly as it is in the data.

One of the advantages of using Word as the editor is that Word has many clever features for designing professional business documents. Let's turn on the hidden characters again.

Using "Keep with next" to prevent paragraph splitting (8:20)

You can see these paragraphs have squares at the start. This indicates that a custom setting has been applied to this paragraph.

If we place the cursor in the paragraph and open the paragraph properties, you can see that the Keep With Next option has been set. This means that this paragraph will be attached to the next one.

This paragraph also has the setting, as does this one. All three paragraphs are effectively attached to this final paragraph.

The result is that Word keeps the signature block together. So, even though there is room here for the words "Yours sincerely", we don't want those to appear separately from the signature, the name, or the person's position.

We can see the effect of this Keep With Next setting just by editing the template. If this content is removed, there is sufficient space to include all four lines at the bottom of the first page.

This really is the power of using Microsoft Word as the template-editor. Designing a good template is a combination of using these clever features in Word or LibreOffice and the fields of Docmosis to create a template that behaves in a predictable manner.

You can see in the generated document when the conditional section removes content, there's enough room for the signature block to fit on the first page. You can also see a signature image is being injected into the generated document.

Image replacement (9:51)

Let's look closer at image insertion. Firstly, this is not an e-Signature process. This signature is just a picture that has been inserted into the document. It could just as easily be a logo, a product image, or something else. In the template, you will see Docmosis has a placeholder image. In this case, we're using a bright orange bordered image to make it obvious it is an image placeholder. However, the image used as the placeholder is not important. It could be any image.

The advantage of using an image in the template is that you can use Word's features like In Line With Text, In Front Of Text, or Behind Text to control the position of this image.

To specify the data item that provides the data for this image, Docmosis relies on Word's bookmarking feature. In this template, there is a bookmark with the characters I, M, G, and an underscore, and then repSignature. repSignature is the data item Docmosis will be looking for.

If your template or document already makes use of Microsoft Word bookmarks, they will still continue to function. Image data can be provided in three different ways. In this example, we're using an image that has been uploaded to the cloud service.

The repSignature data contains a reference to that uploaded image. Images that are going to be used more than once can be uploaded to the service and referenced directly in the data.

However, images can also be provided as a URL or as Base64-encoded data. Let's return to the template and change the size and aspect ratio and position of the placeholder image.

We save that change, upload the template, then regenerate the document. You can see that the image is now much larger and positioned differently to how it was before.

Let's change the data to use an image from a URL. Here's an image from our website. Let's copy that URL in the data.

The prefix user image says that the image will be available locally. If we want to use a URL, we should change the prefix to image URL, and then provide the URL of the image.

Let's regenerate the document, and we'll see the new image now appears in the generated document. In this case, the aspect ratio of the placeholder image doesn't match the inserted image.

We can control that behavior using the bookmark in the template.

As we mentioned, a bookmark is used to designate that this image is one that is scheduled for replacement.

If we open the bookmarks, click on repSignature, and go-to, we can see that the bookmark is currently applied to this image. Let's delete this bookmark. Select the image and reapply the bookmark. This time, we will use image fit as the prefix.

We will save that change and upload the new template to the service.

Now when we generate the document, the image fit instruction ensures that the aspect ratio of the inserted image is maintained.

We can see that the image in the generated document now fits neatly within the area of the placeholder image.

Controlling aspect ratio of the document (13:33)

Let's look at some of the other features we are using to control the layout of this generated document.

If we zoom out on this document, you can see that it consists of two portrait pages, followed by two landscape pages. Let's return to the template and have a look at the features in Word, that we're using to create that layout.

If we turn on the hidden characters, we can see at the end of the signature block, there is a section break, next page.

The section break in Microsoft Word creates the first section of the document.

The section includes the associated headers and footers and has its own page size and orientation settings.

Following the section break, a new section starts, which can have headers and footers, page-orientation, and page size that are different from the first section.

When these clever features in Microsoft Word are used in the template, Docmosis honors these settings, and they flow through to the generated document.

Let's return to the body of the document and have a look at this final page.

Repeating over array data (14:45)

For the remainder of this video, we're going to focus on generating this table.

Let's start with the generated document to see the result and work backwards.

In the generated document, you'll see that the table has a header row. The data is repeated with a gray row, followed by a white row, and then alternating row colors.

There is numbering on the left-hand side. The table has so much data that it expands to reach the bottom of the page. There is then room for the footer, room for the header, and the table runs over to the next page.

The header row is repeated, and the table continues. Let's look at all the features that are controlling this behavior. Firstly, Microsoft Word has table properties that allow a row to be repeated as a header row at the top of each page.

This has been applied to row one in the table. This means that even in the template, if extra rows are added to the table, as the table reaches the bottom of the page, the header row will appear at the top of the next page.

This row can be edited, but this row cannot because its contents are being controlled by row one. The next row in this table has a field with the characters R, r, and an underscore.

This tells Docmosis to find a group of payments and use that as the data for the repeating rows. The last field is the end of the repeating rows.

Between these two fields is a single row. However, it could be multiple rows or even nested tables within tables. Now let's have a look at the structure of the data.

Towards the end of the data, our payments are present as an array. You can see there are open and closing balances, and each object is repeated.

These are the objects that will be stamped out into rows in the table. Also, if you look closely at the first row, you will notice that there is data for amount, open, interest, principal, closing, and a date.

But there is no, number one, in this data. In the generated document, there is a number one appearing at the start of the row. The number one is coming from this special field in the template.

You'll notice that the first field at the start of this row begins with a dollar sign. This indicates that this field should be interpreted as a Docmosis variable. Inside repeating structures, Docmosis creates these convenient built-in variables. You can also create your own custom variables.

Next steps (17:35)

Now that we have worked through this template together, you should have a basic understanding of the Docmosis template syntax.

To continue your learning, we recommend heading over to the Docmosis resources website. In the template tutorials, you will find a series of short lessons, each explaining how to use a specific template feature.

The articles include a downloadable zip with a working template and matching data. There is also a handy preview image of the template and the generated document.

Each article has a detailed description of the feature and step-by-step examples of how to use it. As well as the template tutorials, be sure to download the template guide, which is the complete reference guide covering all available templating features.

Thank you for watching and for considering Docmosis for your document generation needs.

Next: Creating template fields »