# Formatting Your Data
Here is a list of available modifiers/helpers. These modifiers/helpers are added along with the tokens(merge field).
| Modifier/Helper | Description | Example |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Uppercase | Convert all characters to uppercase | **{{upper FieldName}}** |
| Lowercase | Convert all characters to lowercase | **{{lower FieldName}}** |
| Capitalize |
Capitalize the first letter
Camel Cased Sentence
|
{{capitalize FieldName}}
{{capitalize FieldName format="words"}}
|
| Abbreviation | Convert text to abbreviation (First letter of each word in caps) | **{{abbreviate FieldName "."}}** |
| Pad | Appends or prepends a single character repeatedly to fill input to given width. |
{{pad number 9}}
{{pad number 5 pad\_with='\*' style='suffix'}}
|
| Concat | Appends text. | **{{concat string1 string2}}** |
| Format Date | Change the format of date, datetime |
|
| Format Number | Change the format of a number (thousands and decimals) |
{{format\_number number decimal\_separator="."}} {{format\_number number thousand\_separator=","}} {{format\_number number precision="2"}} {{format\_number number thousand\_separator="," decimal\_separator="." precision="3"}}
|
| Format Phone |
Change the format of your phone number. It can also be used to format a number
| **{{format\_phone landline "(%3) %3-%4"}}** |
| Number to words | Converts the input number in to words. | **{{number\_to*****\_*****words input}}** |
| Number to Ordinal | Converts the input number to its ordinal form, in words. | **{{number\_to\_ordinal input}}** |
| Join | Joins the input array of strings with given separator (defaults to `,`) |
{{join items ", "}}
{{join FieldName ", " lookup="object.name"}}
|
| Replace | Replaces the match string from input with given replace string | **{{replace str1 str2}}{{replace FieldName (regex "\[0-9]" "g") "\*"}}** |
| Regex | Return a RegExp class instance with given pattern and flags | **{{replace FieldName (regex "(0-9)" "g") "\*"}}** |
| Split | Splits input with given separator (defaults to `,`) | **{{#each (split Fieldname ", ")}} ... {{/each}}** |
| Strip | Strips the input of given match characters (defaults to white space) from given position (`left` or `right` or `both`) |
{{strip FieldName}}
{{strip FieldName "\*" side="left"}}
|
| Sort | Sorts input in the given order (`asc` , `desc`) |
{{# list (sort FieldName lookup="price" order="asc")}} ... {{/list}}
|
| Insert Link | Inserts a URL or Hyperlink in the document | **{{insert\_link url text="clickable display text"}}** |
| Url Encode | Replaces special characters inside a URL with encoded text. | **{{url\_encode URL is\_url=true\|false}}** |
| Url Decode | Decodes encoded URLs into pre-encoded forms. | **{{url\_decode URL is\_url=true\|false}}** |
| Rand | Returns a random value between the specified minimum and maximum values. | **{{rand min max}}** |
| As Number | Converts any given input to a valid number. | **{{as\_number FieldName}}** |
| As String | Converts any given input to a valid string. | **{{as\_string FieldName}}** |
| As Boolean | Converts any given input to True or False. | **{{as\_boolean FieldName}}** |
## **Format Date/Time**
To print date and time in desired format in the document, use this formatter. Format, Locale, and Offset can be adjusted.
#### Syntax
```
{{format_date token_name format="format" input_format="input format" locale="language_code" offset="add/subtract time"}}
```
* **format** - defines output format of the date/time
* **input\_format** - defines the input format of your date string (this must be used for consistent date interpretation if your input format is different from ISO format)
* **language** - output language for date/time. See supported languages below.
* **offset** - add/subtract offset to a given date. This can be used to calculate due dates, valid-until, etc. See offset examples below.
#### Examples:
### Parsing dates accurately with Input Format
If the date values you pass to your date fields are in a specific format (for example, `DD/MM/YYYY`), you can use the `input_format` parameter to specify the format of your input dates.
Example - Syntax:
```
{{format_date due_date input_format='DD/MM/YYYY' format=”dddd, DD MMMM YYYY”}}
```
Input data:
```
due_date = '31/12/2025'
```
Output:
```
Tuesday, 08 April 2025
```
If input\_format is not used, the due\_date value will be treated as an invalid date and the input date will be printed as-is on the document.
### Add/Subtract Time - Manipulate a date and/or time by adding/subtracting time
To adjust a date/time by a specific amount, you need to supply `<+/-> ` as the value for offset. Unit can be "years", "months", "weeks", "days", "hours", "minutes", or "seconds". Here are some examples:
* `+1hours`
* `-3days`
* `+5years+2months-3minutes`
* `+8h`
| Example | Input | Output |
| -------------------------------------------------------------------------- | :--------: | :---------------: |
| `{{format_date _date format="MMMM DD YYYY" locale="en" offset="+1years"}}` | 2019-08-20 | August 20 2020 |
| `{{format_date _date format="MMMM DD, YYYY" offset="+6months"}}` | 2019-08-20 | February 20, 2020 |
| `{{format_date _date offset="+1years"}}` | 2019-08-20 | 08-20-2020 |
## Format Number
This helper can be used to change the format of a number, including its thousands with separators, decimal with separators and precision.
#### Syntax
```
{{format_number number output_format="in" thousand_separator="thousand_sep" decimal_separator="decimal_sep" precision="number_of_decimal_places"}}
```
* **output\_format** (optional) - desired format of the number. Supported formats:
* **default** - millions, billions.
* **in** - lakh, crore.
* **thousand\_separator** (optional, default: `,` comma) - the character the should be used to separate thousands position.
* **decimal\_separator** (optional, default: `.`period) - the character that should be used to separate decimals.
* **precision** (optional, default: not-set) - number of decimal places required.
{{format_number number output_format="in" thousand_separator="," decimal_separator="." precision="2"}}
87904.987
87,904.99
## Abbreviation
The **`abbreviate`** formatter allows you to automatically generate abbreviations by extracting the first letter of each word in a given text field and capitalizing it. This is useful for standardizing text and ensuring consistency in documents.
#### **Syntax:**
```
{{abbreviate token separator}}
```
* `token`: The field from which the abbreviation will be generated.
* `separator` (optional): A character or string to place between the extracted letters. If omitted, the abbreviation will be formed without separators.
#### Example Usage:
| Input Text | Syntax | Output |
| ----------------------- | --------------------------------- | ------ |
| United Nations | `{{abbreviate Organization}}` | UN |
| Central Processing Unit | `{{abbreviate partName "-"}}` | C-P-U |
| John Doe | `{{abbreviate customerName "."}}` | J.D |
## Format Phone
The **`format_phone`** formatter allows you to format phone numbers according to a specified pattern, ensuring consistency and readability in your documents.
**Syntax:**
```
{{format_phone landline format}}
```
* `landline`: The field containing the phone number.
* `format`: The desired format for the output. Ex: `(%3) %3-%4`
Input
Syntax
Output
landline=1234567890
{{format_phone landline "(%3) %3-%4"}}
(123) 456-7890
landline=9876543210
{{format_phone landline "+1-%3-%3-%4"}}
+1-987-654-3210
id_number=123456789012
{{format_phone id_number "%4-%4-%4"}}
1234-5678-9012
## Number to words
The **Number to Words** helper in Docupilot allows you to convert numeric input into words. This functionality supports customizable output formats, including options for language and currency.
#### Syntax
```
{{number_to_words input output_format="in" suffix=" " decimal_suffix=" " language=" "}}
```
* `input`: The numeric value to be converted.
* `output_format` (optional): Defines the format (default: `us`).
* `suffix` (optional): Adds a suffix for currency or other units (e.g., `dollars`, `kg`).
* `decimal_suffix` (optional): Defines a suffix for decimal parts if applicable (e.g., `cents`, `paise`).
* `language` (optional): Specifies the language for the output text. Learn more about available languages [here](#language).
| Example | Input | Output |
| ---------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------- |
| `{{number_to_words number}}` | 123456 | one hundred and twenty-three thousand four hundred and fifty-six |
| `{{capitalize (number_to_words amount suffix="dollars" decimal_suffix="cents")}}` | 800.658 | Eight hundred dollars six hundred and fifty-eight cents |
| `{{number_to_words currency output_format="in" suffix="rupees" decimal_suffix="paise"}}` | 9893.567 | nine thousand eight hundred and ninety-three rupees five hundred and sixty-seven paise |
| `{{number_to_words price output_format="in" suffix="rupees"}}` | 7000000 | seventy lakh rupees |
| `{{number_to words price suffix="dollars"}}` | 7000000 | seven million dollars |
| `{{number_to_words input language="fr"}}` | 8795 | huit mille sept cent quatre-vingt-quinze |
| `{{number_to_words price suffix="Euros" decimal_suffix="Cents" language="de"}}` | 8790.345 | achttausendsiebenhundertneunzig Euros dreihundertfünfundvierzig Cents |
{% hint style="info" %}
Note:
* The output is always in **words**.
* Decimals will be converted separately using the `decimal_suffix`.
* Use `capitalize` if the first letter needs to be uppercase.
{% endhint %}
## Number to Ordinal
The `number_to_ordinal` formatter converts a numeric input into its ordinal form, expressed in words. This is useful for formatting numbers in legal, financial, or formal documents.
#### Syntax
```
{{number_to_ordinal number}}
```
* `number`: The numeric value to be converted into an ordinal.
#### Example Usage
#### Basic Conversion
```
{{number_to_ordinal number}}
```
**Input:**
```
number = 800
```
**Output:**
```
eight hundredth
```
#### Capitalizing Ordinal Output
```
{{capitalize (number_to_ordinal number1)}}
```
**Input:**
```
number1 = 582
```
**Output:**
```
Five hundred and eighty-second
```
#### Handling Decimal Values
```
{{number_to_ordinal number}}
```
**Input:**
```
number = 789.325
```
**Output:**
```
seven hundred and eighty-ninth
```
{% hint style="info" %}
Note:
* The output is always in **words**.
* Decimals are ignored when determining the ordinal form.
* Use `capitalize` if the first letter needs to be uppercase.
{% endhint %}
## Join
The **Join** helper in Docupilot allows you to combine an array of strings or extract and join a specific property from a list of objects into a single string, using a specified separator. If no separator is provided, a comma (`,`) is used by default.
#### Syntax
```
{{join content separator lookup="lookup_key"}}
```
* `content`: The array of strings to join.
* `separator` (optional): The character or string to separate values (default: `,`).
* `lookup` (optional): The key to extract values from objects in an array.
#### Example Usage
#### Joining a Simple List with a Comma
```
{{join SampleName ","}}
```
**Input:**
```json
[
"John",
"Mary",
"Paul"
]
```
**Output:**
```
John,Mary,Paul
```
#### Joining Object Values Using a Lookup Key
```
{{join employees lookup="Name.Firstname"}}
```
**Input:**
```json
[
{"Name": {"Firstname": "Peter", "Lastname": "Parker"}},
{"Name": {"Firstname": "Tony", "Lastname": "Stark"}},
{"Name": {"Firstname": "Steve", "Lastname": "Rogers"}}
]
```
**Output:**
```
Peter,Tony,Steve
```
{% hint style="info" %}
Note:
* If `lookup` is provided, the helper will extract the specified key from each object before joining.
* The separator can be any character (e.g., `|`, `;`, `-`).
{% endhint %}
## Replace
The **`replace`** formatter allows you to replace specific text or patterns within a string using either direct text matching or regular expressions (regex). This is useful for modifying content dynamically in templates.
#### Syntax
```
{{replace input match_str replace_str}}
```
* `input`: The text to be processed.
* `match_str`: The text or regex pattern to match.
* `replace_str`: The replacement string.
#### Example Usage
**Replacing a Specific Word**
```
{{replace text find replace}}
```
**Input:**
```
text = "Mary Ross"
find = "Ross"
replace = "Jane"
```
**Output:**
```
Mary Jane
```
**Replacing Characters Using Regex**
```
{{replace input (regex "[a]" "g") "e"}}
```
**Input:**
```
input = "Ragax"
```
**Output:**
```
Regex
```
**Using Regex with Replace**
Regex can be used to match multiple occurrences dynamically:
```
{{replace text (regex "[0-9]+" "g") "#"}}
```
**Input:**
```
text = "ID12345XYZ678"
```
**Output:**
```
ID#XYZ#
```
{% hint style="info" %}
Note:
* `match_str` can be either a direct text match or a regex pattern.
* Regex patterns must be enclosed within `(regex "pattern" "flags")`.
* the `g` (global) flag ensures multiple occurrences are replaced.
{% endhint %}
## Regex
The **Regex** helper in Docupilot allows you to apply regular expressions to manipulate text dynamically in your templates. It is useful for pattern matching, replacing, or extracting specific content from text fields.
#### Syntax
```
{{regex pattern flags}}
```
* `pattern`: The regular expression pattern to apply.
* `flags` (optional): Regex flags for customization (default: no flags set).
* Commonly used flags:
* `g` (global) - Applies the regex to all matches.
* `i` (case insensitive) - Ignores case differences.
* `m` (multi-line) - Allows multi-line matching.
#### Example Usage
#### Replacing Lowercase Letters with Asterisks
```
{{replace text (regex "[a-z]" "g") "*"}}
```
**Input:**
```
text = "MaryJane123"
```
**Output:**
```
M***J***123
```
**Replacing Numbers with a Symbol**
```
{{replace text (regex "[0-9]+" "g") "$"}}
```
**Input:**
```
text = "1239HomeAlone42"
```
**Output:**
```
$HomeAlone$
```
#### Extracting Only Numbers
```
{{replace text (regex "[0-9]+" "g") "*"}}
```
**Input:**
```
text = "My number is 456 and my ID is 7890."
```
**Output:**
```
My number is *** and my ID is ****.
```
{% hint style="info" %}
**Note**
* **Regex must be used with a helper like `replace`, `match`, or `test`.**
* Ensure that the regex pattern is correctly formatted.
* Flags modify how the pattern behaves (e.g., `g` for multiple matches).
{% endhint %}
## Strip
The **Strip** helper in Docupilot allows you to remove specific characters from the beginning, end, or both sides of a given input. By default, it removes whitespace.
#### Syntax
```
{{strip input match_str side="left"}}
```
* `input`: The string from which characters will be removed.
* `match_str` (optional): The characters to be stripped (default: whitespace).
* `side` (optional): Determines where to remove characters from. Options:
* `left`: Removes from the beginning.
* `right`: Removes from the end.
* `both` (default): Removes from both sides.
#### Example Usage
#### Removing Whitespace (Default Behavior)
```
{{strip text}}
```
**Input:**
```
text = " Hello World "
```
**Output:**
```
Hello World
```
#### Removing Specific Characters
```
{{strip text "-"}}
```
**Input:**
```
text = "---Hello---"
```
**Output:**
```
Hello
```
#### Stripping Characters from the Left Side
```
{{strip text "0" side="left"}}
```
**Input:**
```
000123450
```
**Output:**
```
123450
```
#### Stripping Characters from the Right Side
```
{{strip "text" "%" side="right"}}
```
**Input:**
```
text = "12345%%%"
```
**Output:**
```
12345
```
{% hint style="info" %}
Note:
* If `side` is omitted, the default behavior removes characters from both sides.
* `match_str` can be any character or set of characters.
* If `match_str` is not specified, only whitespace is removed.
{% endhint %}
## Split
The **`split`** formatter allows you to break a string into an array based on a specified separator. This is useful for handling lists or structured text in templates.
**Syntax:**
```
{{split input separator}}
```
* `input`: The string to be split.
* `separator` (optional): The delimiter used for splitting. This can be a text character or a **regular expression** (Regex). If omitted, the default separator is `,` (comma).
#### Example Usage
#### Splitting by Default Separator (Comma)
```
{{#each (split items)}}
{{this}}
{{/each}}
```
**Input:**
```
items = "apple,banana,cherry"
```
**Output:**
```
apple
banana
cherry
```
#### Splitting by Custom Separator
```
{{#each (split people "|")}}
{{this}}
{{/each}}
```
**Input:**
```
people = "John|Doe|Smith"
```
**Output:**
```
John
Doe
Smith
```
#### Splitting Using Regex:
```
{{#each (split text (regex "\d+" "g"))}}
{{this}}
{{/each}}
```
**Input:**
```
text = John1Doe2Cleveland
```
**Output:**
```
John
Doe
Cleveland
```
{% hint style="info" %}
Note:
* **Split is a nested formatter**, meaning it must be used within other formatters like `each` or `list`.
* When splitting on spaces, use `" "` as the separator.
* *See* [*Regex*](#regex) *for more information on how to use Regular Expressions.*
{% endhint %}
## Sort
The **Sort** helper in Docupilot allows you to arrange data in ascending (`asc`) or descending (`desc`) order based on a specified key. This is useful for organizing lists dynamically in templates.
**Syntax**
```
{{sort content order=order lookup="lookup_key"}}
```
* `content`: The array or list to be sorted.
* `order`: The sorting order (`asc` for ascending, `desc` for descending).
* `lookup` (optional): The key used for sorting within objects.
#### **Example Usage:**
**Sorting Numbers:**
```
{{#each (sort cost order="desc")}}
{{this}}
{{/each}}
```
**Input:** `[100, 50, 200]`
**Output:**
```
200
100
50
```
**Sorting Objects by a Key:**
```
{{#each (sort items lookup="price" order="asc")}}
{{name}} is available at {{price}} per {{unit}}.
{{/each}}
```
**Input:**
```
[
{"name": "Apple", "price": 3, "unit": "kg"},
{"name": "Banana", "price": 1, "unit": "kg"},
{"name": "Cherry", "price": 2, "unit": "kg"}
]
```
**Output:**
```
Banana is available at 1 per kg.
Cherry is available at 2 per kg.
Apple is available at 3 per kg.
```
{% hint style="info" %}
Note:
* **Sort is a nested formatter**, meaning it must be used within other formatters like `each` or `list`.
* The **lookup key** is required when sorting objects.
* Sorting is case-sensitive; ensure consistent casing in text-based sorting.
{% endhint %}
## Filter
The `filter` helper can be used to refine lists by applying specific conditions, effectively narrowing down the data to what's most relevant. The syntax for the `filter` helper is `{{filter items condition}}`, where `items` is the list to be filtered and `condition` is the criteria applied to each item. Conditions can range from straightforward comparisons, like `(department == "Sales")`, to more complex expressions like `((LeadScore > 60 and LeadScore <= 80) and LeadRole == "vp" and LeadIndustry == "Healthcare")`. Here are a few examples showcasing the versatility of the `filter` helper:
1. Print a list of employees from Sales department and their salaries:
```
{{#each (filter Employees (Department == "Sales"))}}
{{FirstName}} | {{LastName}} | {{Salary}}
{{/each}}
```
2. Filter can be combined with sort to handle more advanced use-cases: For example, to print list of products in inventory that are priced higher than or equal to 50$ in descending order of price:
```
{{#each (sort (filter InventoryItems (Price >= 50)) order="desc" lookup="Price")}}
{{ProductName}} | {{Cateogory}} | {{Price}} | {{Margin}}
{{/each}}
```
3. Filtering a list of events to include only those happening in December
```
Following is the event catalog for December:
{{#each (filter Events (Month == "December"))}}
{{EventName}} takes place on {{EventScheduleDate}} at {{EventScheduleTime}}
{{/each}}
```
4. Above example can be modified further to make the month dynamic too, but we need to use Look-backs to achieve the same:
```
Following is the event catalog for {{DesiredMonth}}:
{{#each (filter Events (Month == ../DesiredMonth))}}
{{EventName}} takes place on {{EventScheduleDate}} at {{EventScheduleTime}}
{{/each}}
```
5. Filtering a collection of books to display only those published after the year 2000
```
{{#each (filter Books (PublishedYear > 2000))}}
{{BookName}} | {{Author}} | {{PublishedYear}}
{{/each}}
```
6. Filter a dataset to exclude items marked as inactive
```
{{#each (filter dataSet (status != "inactive"))}}
{{property1}} - {{property2}}
{{/each}}
```
7. Filter Leads that are VPs in Healthcare with lead score greater than 80
```
{{#each (filter Leads (LeadScore > 80 and (lower LeadRole) == "vp" and LeadIndustry == "Healthcare"))}}
{{LeadName}} | {{LeadEmail}} | {{LeadScore}}
{{/each}}
```
8. Print Leads that are from Healthcare or Pharma industry with lead score higher than 80 but lower than 95, in descending order of lead score.
```
{{#each (sort (filter Leads ((LeadIndustry == "Healthcare" or LeadIndustry == "Pharma") and (LeadScore > 80 and LeadScore < 95))) order="desc" lookup="LeadScore")}}
{{LeadName}} | {{LeadEmail}} | {{LeadScore}}
{{/each}}
```
These examples demonstrate the `filter` helper's capability to perform both simple and complex data filtering within a template, making it an essential tool for crafting dynamic content.
Example Template using Filter helper
Example Output using Filter helper
{% hint style="info" %}
Note:
* **Filter is a nested formatter**, meaning it must be used within other formatters like `each` or `list`.
* The **condition** is required when filtering a list of items.
{% endhint %}
## Set and Get
**`{{set ...}}`** and **`{{get ...}}`** can be used to store values and access them later in your template. This is useful when you want to assign calculated values, reuse data, or simplify complex logic.
Syntax:
```
{{set "variable_name" "value"}}
{{get "variable_name"}}
```
* **set** stores a value to a variable name.
* **get** retrieves the stored value for later use.
**Example 1:**
Template:
```
{{set "name" "New York"}}
Welcome to the city {{get "name"}}
```
Output:
```
Welcome to the city New York
```
**Example 2:**
Template:
```
{{set "total" (calc "Price * Qty")}}
Total Amount: {{get "total"}}
```
Input:
```
Price = 100; Qty = 5
```
Output:
```
Total Amount: 500
```
**Example 3:**
Template:
```
{{set "discountPercentage" 20}}
{{#each items}}
{{#if (amount > 500)}}{{set "discountPercentage" 50}}{{/if}}
{{name}} @ {{amount}}
{{/each}}
Discount percentage to be applied = {{get "discountPercentage"}}%
```
Input1:
Output2:
```
ServiceMini @ 20
ServiceMega @ 550
Discount percentage to be applied = 50%
```
{% hint style="warning" %}
**`set`** and **`get`** are recommended over the older **`var`** for better clarity and future compatibility. **`var`** is in now legacy and should be avoided in all new templates.
{% endhint %}
## Var (legacy)
The `var` is a powerful tool designed for both storing and retrieving data within templates, enabling dynamic variable use. This functionality allows users to assign values to tokens directly within their documents through a simple syntax: `{{var "token" value}}`. For instance, assigning a numerical value or even transferring values between tokens is effortlessly done using `{{var "cost" 500}}` or `{{var "amount" MRP}}`, respectively. Retrieving the stored data is just as straightforward; by calling `{{var "token"}}`, the value assigned to the specified token is seamlessly inserted into the document.
#### Storing Data
Syntax: `{{var "token" value}}`
| Example | Output |
| ---------------------- | ------------------------------------------------------------ |
| `{{var "cost" 500}}` | Here the token cost is assigned a value of 500. |
| `{{var "price" 7599}}` | Here the token price is assigned a value of 7599. |
| `{{var "amount" MRP}}` | Here the value in token MRP is assigned to the token amount. |
#### Retrieving Data
Syntax: `{{var "token"}}`
| Example | Output |
| ----------------- | ------ |
| `{{var "cost"}}` | 500 |
| `{{var "price"}}` | 7599 |
## Pad helper
Pad helper fills up the input to the desired width by adding a single character repeatedly either at the beginning or at the end.
Syntax: `{{pad number output_width pad_with='character' style='prefix|suffix'}}`
Example 1:\
`{{pad number 7}}`
| Input | Output |
| ----- | ------- |
| 123 | 0000123 |
Example 2:\
`{{pad number 9 pad_with='#' style='suffix'}}`
| Input | Output |
| ------ | --------- |
| 123456 | 123456### |
## Aggregate
Aggregate functionality helps to accumulate data from a collection of items to return a single result (like adding numbers in a list). It is useful in scenarios like invoice processing, where it can compute totals such as the total number of items sold, invoice sub total, grand total, factoring in discounts, etc.
Example: Consider a case where you want to generate an invoice which can auto-calculate quantity sold, sub total and grand total. Assuming `InvoiceLineItems` is the field which contains all line items where each line item contains properties: `name`, `qty` , `unit_price` and `discount`.
To calculate the total number of items sold as part of this invoice, we need to add `qty` from each line item. It can be done using:
`{{aggregate InvoiceLineItems formula="qty" operation="add"}}`
To compute the invoice total before applying any discounts, we need to add the result of `qty * unit_price` from each line item. This can be achieved using:
`{{aggregate InvoiceLineItems formula="qty * unit_price" operation="add"}}`
To compute discounted invoice total where discounts are applicable as percentage for each line item separately, we need to add the result of `qty * unit_price * (1 - discountPercentage / 100)` for each line item.
`{{aggregate InvoiceLineItems formula="qty * unit_price * (1 - discountPercentage / 100)" operation="add"}}`
*Note that each operator inside formula should have a leading and trailing space to work accurately. For example "qty\*unit\_price" will not work, only "qty \* unit\_price" will. This limitation may be addressed in one of our future updates.*
Sample Invoice using aggregate helper - Input
Sample Invoice using aggregate helper - Output
## Concat
Syntax : `{{concat string1 string2 ....}}`
Example:\
`{{insert_image (concat "https:" url) 300 300}}`
Input:\
`//raw.githubusercontent.com/tiholic/exif-orientation-examples/master/Portrait_0.jpg`
Output:
## Group By
Group by helper groups the data with the value of lookup key as grouping criteria.
Syntax: `{{group_by ListName lookup="lookup_key"}}`
`Key` and `items` can be accessed from inside the iterator(`#each` or `#list`). `Key` contains value of `"lookup_key"` for the current record, `items` contain the records which are present under current group.
**Example 1:**
In this example:
* `employees` is the list being grouped.
* `lookup="Department"` groups the list based on the `Department` field.
* `{{key}}` holds the current group value (i.e., department name).
* `items` contains all employees in that department.
* The inner loop ( `{{#each items}}...{{/each}}` ) displays each employee’s ID, name, and designation under their respective department.
{% hint style="info" %}
In case if you are using this inside a table, ensure to merge all cells in the rows with opening or closing of each.
{% endhint %}
**Sample Input:**
| Emp\_ID | Employee\_Name | Designation | Department |
| ------- | -------------- | ----------- | ---------- |
| E001 | Alice | Analyst | Sales |
| E002 | Bob | Manager | HR |
| E003 | Charlie | Associate | HR |
| E004 | John | Executive | Sales |
**Sample Output :**
This will generate output grouped by department, with employee details listed under each.
**Example 2:**
```handlebars
{{#each (group_by employees lookup="role.code")}}
Number of employees in role {{key}}: {{items.length}} and they are {{join items ", " lookup="name.first"}}
{{/each}}
```
Input: *(JSON)*
```json
{
"employees": [
{ "role": {"code": "TL"}, "name": {"first": "Dave" } },
{ "role": {"code": "TL"}, "name": {"first": "Chris"} },
{ "role": {"code": "PM"}, "name": {"first": "Matt" } },
{ "role": {"code": "TL"}, "name": {"first": "Emma" } },
{ "role": {"code": "PM"}, "name": {"first": "Jenn" } }
]
}
```
Output :
```
Number of employees in role TL: 3 and they are Dave, Chris, Emma
Number of employees in role PM: 2 and they are Matt, Jenn
```
In the above example,
* **"TL"** and "**PM"** are the group **`keys`**.
* `items` corresponding to the key "**TL"** are :
* `{ "role": { "code": "TL" }, "name": { "first": "Emma" } }`
* `{ "role": { "code": "TL" }, "name": { "first": "Chris" } }`
* `{ "role":{ "code": "TL" }, "name": { "first": "Dave" } }`
* `items` corresponding to the key "**PM"** are:
* `{ "role": { "code": "PM" }, "name": { "first": "Jenn" } }`
* `{ "role": { "code": "PM" }, "name": { "first": "Matt" } }`
**Example 3:**
```handlebars
{{#each (group_by places)}}
Number of branches in {{key}}: {{items.length}}
{{/each}}
```
Input: *(JSON)*
```json
{
"places": [
"New York",
"Las Vegas",
"Chicago",
"New York",
"Las Vegas",
"New York"
]
}
```
Output:
```
Number of branches in New York: 3
Number of branches in Las Vegas: 2
Number of branches in Chicago: 1
```
In the above example,
* **"New York"**, "**Las Vegas"** and "**Chicago"** are the group `keys`.
* Number of `items` corresponding to the key "**New York"** are 3.
* Number of `items` corresponding to the key "**Las Vegas"** are 3.
* Number of `items` corresponding to the key "**Chicago"** is 1.
## Inserting a link
To insert a dynamic URL into your document.
Format: **`{{insert_link url text=text}}`**
#### Hyperlink style customization in Word documents
Inserted hyperlinks follow the source style in Builder templates. In case of Word Document templates, style customization can be done by opening **Format > Styles > Search and select "Hyperlink" >** click **Modify > Update to desired style** and click **Ok**
## URL encode
URL encode helper replaces special characters inside a URL with encoded text.
Syntax : `{{url_encode URL is_url=true|false}}`
**Example1:**
Syntax in Template
```handlebars
{{url_encode url is_url=true}}
```
Input sent to the template (JSON):
```json
{
"url": "https://dummyimage.com/600x400/000/fff&text=hello world"
}
```
Generated Output:
```
https://dummyimage.com/600x400/000/fff&text=hello%20world
```
**Example2:**
Syntax in Template
```handlebars
https://example.com?open={{url_encode url_part is_url=false}}
```
Input sent to the template (JSON):
```json
{
"url_part": "https://dummyimage.com/600x400/000/fff&text=hello world"
}
```
Generated Output:
```
https://example.com?open=https%3A%2F%2Fdummyimage.com%2F600x400%2F000%2Ffff%26text%3Dhello%20world
```
## URL decode
URL decode helper decodes encoded URLs into pre-encoded forms.
Syntax : `{{url_decode URL is_url=true|false}}`
**Example1:**
Syntax in Template
```handlebars
{{url_decode url is_url=true}}
```
Input sent to the template (JSON):
```json
{
"url": "https://dummyimage.com/600x400/000/fff&text=hello%20world"
}
```
Generated Output:
```
https://dummyimage.com/600x400/000/fff&text=hello world
```
**Example2:**
Syntax in Template
```handlebars
{{url_decode url is_url=false}}
```
Input sent to the template (JSON):
```json
{
"url": "https%3A%2F%2Fdummyimage.com%2F600x400%2F000%2Ffff%26text%3Dhello%20world"
}
```
Generated Output:
```
https://dummyimage.com/600x400/000/fff&text=hello world
```
{% hint style="warning" %}
Encoding or decoding a URL depends on the value of the parameter 'is\_url'. If the value is true, only the query parameter part of the complete URL is encoded/decoded else, the whole of the URL is encoded/decoded.\
The Default value of is\_url is set as false.
{% endhint %}
## Rand
Rand will return a random value between the min and max values passed.
Syntax: `{{rand min max}}`
| Example | Input | Output |
| ------------------------ | ------------------------- | -------------------------------------------------------------------- |
| {{rand min max}} |
min: 2 max: 500
|
could be any random number between 2 and 500 Ex: 436.89318
|
| {{round (rand min max)}} |
min: 2 max: 500
|
could be any random integer value
ex: 437
|
{% hint style="info" %}
**rand** returns a decimal value between the given min and max. Use **round** along with **rand** to get an integer value.
{% endhint %}
## As Number
As Number converts any given input to a valid number.
Syntax: `{{as_number FieldName}}`
| Example | Input | Output |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | ------------------------------ |
| {{as\_number value}} | value: "**23.000**"(string) | **23**(numerical value) |
|
{{#if (as\_number input\_value) "<=" 100}} Value is less than 100. {{else}} Value is greater than 100. {{/if}}
| input\_value: "**98.767**"(string) | **Value is less than 100.** |
|
{{#if (as\_number input\_value) "<=" 100}} Value is less than 100. {{else}} Value is greater than 100. {{/if}}
| input\_value: "**101.9876**"(string) | **Value is greater than 100.** |
## As String
As String converts any given input to a valid string.
Syntax: `{{as_string FieldName}}`
