MS Word template

MS Word template is a file in the .docx format containing placeholders that will be replaced with new data. Word templates (except the text values) can render images and tables content.

Table of contents:


Placeholders


Placeholders are used when you need to populate the .docx file with data. Each placeholder starts and ends with the opening { and closing } brace correspondingly and refer data field by field id or a System name. For example:

{2500000024117643203}

It also is possible to refer to subfields of any level by adding corresponding id(s)/System name(s) separated by a dot. For example:

{customer.order.item.quantity}
The exact formatting (font style, size, color, etc.) you have applied to the placeholder in the template will be used in the resulting text.

Tables
Inside the Word document tables, only the first placeholder will be rendered. If you insert a placeholder inside the table, that includes a collection field, the table will be extended to include all the data from the provided collection.

Images
An image inside the word template is just a field that can be passed using placeholders. For example, to get an Avatar field with photo system name, you should write placeholder as:

{photo}
The size of an image will be equal to the default image size. If you place the placeholder inside the table cell, the image will not exceed the cell size.


Formatters


A custom Formatter is a unique identification that changes the way how the text should look. For instance, "John" can be printed in the uppercase "JOHN", lowercase john, bold John, or italic John. To format a placeholder in the desired format, we use ? parameter to separate the data type system name (or an ID) from the formatter. After the ? character, you should specify a formatter ID in the form formatterId=something. For example, to convert a text to an uppercase:

{field138?formatterId=140737488357569}
You can find the list of available formatters and set default formatters for each primitive data type on the Builder Formatters page.

Note: You do not have to specify custom formatter with each field. Set default formatters correctly and use custom formatters only when a particular field should be rendered differently. When using custom formatter, please pay attention to the syntax which is case sensitive and does not allow for spaces and other non-printable characters to be inserted before of after the "=" sign.



Languages and translations


Codejig supports template generation in different languages. By default, the text will be rendered in the language currently used by the user on a website.
Using the native Java code, you can select a language that will be used for the template generation:

Binary generateDocViewWithTemplateAndLanguage(AbstractEntity item,
				   Binary template,
				   EntityType type,
				   String filename,
				   Map  map,
				   String languageTag
			       );

or
Binary generateDocViewWithLanguage(AbstractEntity item,
				   Binary template,
				   EntityType type,
				   String filename,
				   String languageTag
			       );


You can also specify the language directly in the template placeholders.
To extend a placeholder with a custom language, you should use parameter lang alongside the language tag. Example: {field137?lang=en}. The list of supported language tags can be found here. If you're going to use custom formatter and custom language, you need to write them separating by & character.
Example: {field137?formatterId=151&lang=en} or {field137?lang=en&formatterId=151}.

Codejig supports older versions of formatters (for ex. {field137?138}) and you don`t need to rewrite them in your templates. However, if you want to set a language parameter to a field, you should rewrite its formatter in a new way.


Template examples


You can find the list of free Word templates here. The list of templates includes:

  • Invoice Base
  • Invoice Default
  • Invoice Contrast
  • CV maker
Feel free to download and explore them. Note that some tricks were made to create a document layout. For example, with no cell borders, a table can become invisible. Or additional blank rows/columns can be added to create a margin.
You can see how the "Base.docx" document looked during the development stage in the picture below.

Code examples


To generate a Word template, Java native code is used. A .docx Document is saved in a Binary data type. ViewBasedExportService is required to perform an export.

To import the ViewBasedExportService use:

import com.codejig.builder.infrastructure.ViewBasedExportService;

To create a ViewBasedExportService object:

ViewBasedExportService exportService = (ViewBasedExportService) 
applicationContext.getBean("viewBasedExportService");

In the example below, the generateDocViewWithTemplate function of an exportService object was used. It has the following parameters:

  • AbstractEntity item: codejig data type.
  • Binary template: file in a .docx format.
  • EntityType type: null.
  • String filename: name of the resulting file.
  • Map map: null.
  • Return type: Binary


generateDocViewWithTemplateAndLanguage function also belongs to the ViewBasedExportService class. It has additional String languageTag parameter, where languageTag is a language code.

generateDocViewWithLanguage is the same as generateDocViewWithTemplateAndLanguage, but it doesn't have Map map parameter.

These three functions of a ViewBasedExportService can be used to generate a Word document from a template.


More information
CODE
Переклад даних
Language codes
System names