How the tool works

1. Creation of templates from a text editor
2. Creation of your printing model
3. Creation of your dataset in JSON format
4. The printing

The operation of Axelor Template is relatively simple, both in its technical operation and in its handling on the user side. Axelor Template searches for all {…} markers in the template and replaces these markers with the corresponding dynamic data.

Several syntaxes allow many operations to be performed, including:

Replacing a field with dynamic data
Data formatting
Repetition of a portion of a document (a table line or anything else)
Conditional display of data

Now let’s discover the complete process.

1. Creation of templates from a text editor

The model allows you to create the document of your choice using the functionalities of Word, for example. Template creation is therefore accessible to everyone because it does not require any technical skills. We can then insert dynamic information inside using a specific syntax.

The dynamic information must be in this format: {d.parameterName}.

Here is the list of document extensions available for your templates and the associated output formats:

Axelor Template supports a diversity of formats, such as DOCX, PPTX or HTML to name but a few. Once the template is completed and saved in the desired format, you can add your template to Axelor Template from the menu Template > Template print models.

2. Creation of your printing model

To create your template print model, click on the + button (at the top left on the grid view).

The form view allows you to link the settings, therefore the JSON data and the model. Here is the template creation interface:

Name: The name of the print model.
Template: This is where you upload your template file.
Rendering conversion format: This is the target extension for the documents generated with this template. The available output formats are directly filtered according to the template file extension.
Template setting: This corresponds to the name of the linked template setting.
Application condition: This field allows you to show/hide the template print model only on some records, according to a groovy condition.
Attach the generated file to the record: This allows you to attach the printed document directly to the business object corresponding to the MetaModel defined in the settings.
Print title: The name of the printed document.
Mention in the title of document: This parameter allows you to complete the name of the printed document with a dynamic variable. For example, if you want to enter the invoice ID in the printed document.

To use the print template created, it is necessary to click on the “Upload” button in the toolbar. A unique ID is generated for your print template.

To modify the model, change the template file and other relevant fields. Then, click on the 'Upload' button in the toolbar.

3. Creation of your dataset in JSON format

Datasets in JSON format are used to populate the templates. These are the data that will replace the {} tags in your template. The datasets are generated from Axelor models, but it is also possible to add your own tags to the JSON.

The creation of these datasets is done from the menu Template > Template settings.

It is necessary to create a setting for each business object used (Company, Address, City, etc).

This is where we ask our template to replace the tags with JSON variables. This data is entered in the template setting.

To create your template setting, click on the + button (at the top left on the grid view).

Here is the user interface for creating your template setting:

Name: Name of the template setting.
Model: This is the object in Axelor that we wish to target to retrieve its attributes, which will be used in our template print model.
Is default?: Allows defining our template setting as a reference.

The template setting lines represent the structure of our JSON. The list of template setting lines should ideally contain only the fields which are really used in the template. There are several ways to fill this list.

Option 1. Manually

To add a line manually, click on '+ New'. A pop-up opens:

Name in template: Attribute name in JSON.
Field: Simple or pointed database field, this is the value linked to the attribute. To fill in this field, you must respect the groovy syntax.
Template setting to use: In the case of relational fields, you must define a setting for the corresponding object and enter it there.
Selection to use: In the case of selection type fields, you must enter the name of the selection associated with the field in the domain definition.

Option 2. Fill lines

By clicking on Fill lines, all the fields are automatically added by taking the attributes of the MetaModel selected before. You must then delete those which are not used.

We discourage the use of this option because it loads all the fields instead of only the necessary ones. This can have significant impacts on performance and disk space usage. We recommend using the Automatic configuration option.

Option 3. Automatic configuration

This option allows the automatic generation of template setting configuration based on the provided document.

Let’s see how we can automatically configure the template setting for the sample template below:

Open your template setting. Fill the Name and the Model.
Click on Automatic configuration.
In the popup view, upload the template file.
Click on OK. And voilà, the setting is generated!

Option 4. Query line template

Query line templates allow retrieving custom data from objects that are not directly related.

Example

Use case: Fetch objects displayed by an action-view inside a panel-dashlet.

Models structure

BudgetDistribution (invoiceLine: InvoiceLine)
InvoiceLine (invoice: Invoice)
Invoice (id: Long)

XML configuration

<panel-dashlet name="budgetDistributionPanel" action="action.invoice.view.list.budget.distributions"/>

<action-view name="action.invoice.view.list.budget.distributions" model="com.axelor.apps.account.db.BudgetDistribution" title="Budget distributions">
    <view type="form" name="budget-distribution-form"/>
    <view type="grid" name="budget-distribution-grid"/>
    <domain>self.invoiceLine.invoice = :invoiceId</domain>
    <context name="invoiceId" expr="eval: id"/>
</action-view>

In this scenario, to display the list of BudgetDistribution entries in the Invoice form, you need to configure the query line to traverse the indirect relationship chain accordingly.

The query line configuration

Query line config

In the displayed form, you can select the action action.invoice.view.list.budget.distributions, then click on Parse action button to fill all the field automatically.

Name in template: The attribute name to use in the generated JSON. If the configuration is generated from an action-view, this field is automatically computed from its name, but it should be adjusted to match the structure expected in the document.
Query filter: The domain expression used to filter the target objects based on specific criteria.
Template setting to use: Refers to the unrelated object to retrieve. The generated JSON will include only the fields defined in the selected template setting.
Parameters: If the query filter uses dynamic parameters, they should be defined in this section.

_BudgetDistribution

We expect only the amount to be included in the generated JSON. Let’s configure the setting in consequence.

Distribution

Generated payload during print

The generated JSON contains the list of BudgetDistributions, only the amount is included.

Generated payload

4. The printing

To print your document, go to the view of the selected template and click on the button Print Template.

This button is available if and only if there is a template print model compatible with your business object. This implies its template setting relies on the same MetaModel as your business object.