Text Templates

Text templates allow you to dynamically generate text by inserting data directly into a predefined template. These templates use placeholders enclosed in curly brackets to specify where and how data should be inserted. This feature is particularly useful for creating personalized reports, emails, or any document that requires variable data inputs.

Understanding Placeholders

Placeholders in text templates are defined using curly brackets {} and include data pointers optionally followed by a colon : and formatting instructions. These placeholders are designed to be intuitive, allowing you to easily specify the data you want to include in your text. Formatting instructions can be chained by adding additional colon sepearators. Null values can be formatted by adding the empty text at the end using the pipe | as a separator.

A placeholder generally looks like this: {path.to.value:format-instruction1;format-option1:format-instruction2;format-option2|empty-text}.

Examples:

• {$data.order.purchaseDate:date} - Formats order purchase date as a short date.
• {$data.order.purchaseDate:datetime;YYYYMMMMdd} - Formats order purchase date as a date with long month names.
• {$data.item.weight:number;2:suffix; kg} - Formats item's weight as a number with two decimals and adds the suffix kg.
• {$data.order.price:n;0;8|Market} - Formats order price as a number with minimum zero decimals and maximum of 8 decimals. If the value is null price will be shown as Market.

For the list of all available formats check the Text Formats page.

Accessing Data

• $data: This keyword allows you to access data retrieved from your data sources, such as databases or JSON files.
• $dict: Use this to retrieve values from dictionaries predefined in your report setup.
• $params: This accesses report parameters that can be dynamically passed by the user or external system when generating the report.

Example Usage

Consider a scenario where you need to generate a thank-you note for a customer who recently made a purchase. The template might look like this:

Dear {$data.order.customerName},

Thank you for your purchase of {$data.order.productName} on {$data.order.purchaseDate:date}. The total amount charged was {$data.order.amount:currency;USD;2}.

Best regards,
{$data.order.sellerName}

Given the following JSON data:

{
  "order": {
    "customerName": "John Doe",
    "productName": "Wireless Keyboard",
    "purchaseDate": "April 10, 2024",
    "amount": 45.0,
    "sellerName": "Tech Gadgets Inc."
  }
}

The resulting text from the template would be:

Dear John Doe,

Thank you for your purchase of Wireless Keyboard on 04/10/2024. The total amount charged was $45.00.

Best regards,
Tech Gadgets Inc.

This example demonstrates how text templates can be used to create personalized and contextually relevant documents effortlessly. By utilizing placeholders and formatting options, you can ensure that your reports are both professional and informative.