Template Helpers

What are Helpers

Helpers are convenient functions designed to help you personalize your template or format data retrieved from individual Bookmarks.

When added to the editor, the bookmarks have the following format:

{{#HelperName … }}             

Using Helpers in Word Templates

Template Helpers are not supported in MS Word templates. To achieve similar formatting or conditional logic in Word templates, you can use built-in Microsoft Word Field Codes.

Learn more: Word Template Helpers with Word Field Codes

Access Helpers

The helpers can be accessed from the bookmarks panel located next to the template content editor. You can access this panel when creating or editing a template.

For details about creating or editing templates, see this article: Templates: Managing Templates.

Helper Types

When using quotes within helpers, ensure that you use straight quotes (" ") that are plain vertical marks, instead of smart quotes (“ ”) that are plain vertical marks.

General Utilities

1. Current Date/Time {{#now ["Date/Time format"]}}

   • You can add the current date/time generating the result through this helper. Noted, double quotes must be added.

   • If you don’t provide format, it follows the default format set in eBECAS/EDMISS.

   • For more details of formatting, visit here.

   • Example
     {{#now "dd MMMM yyyy"}} → 13 July 2023
     {{#now "MM/dd/yyyy"}} → 13/07/2023
     

2. Yes/No {{#yesno ReplaceWithFieldApiName}}

   • Fields of type checkbox return the values as True or False. Using this helper you can convert these values into more friendly values: Yes and No.

   • If the value is True, it will be converted to Yes.

   • If the value is False, it will be converted to No.

   • If the value is not True/False but another type of data value such as simple text or number, it will be converted to No for output.

   • Example
     {{students-os_student}}, {{#yesno students-os_student}} → True, Yes
     {{students-online_student}}, {{#yesno online_student}} → False, No
     {{students-first_name}}, {{#yesno students-first_name}} → Ryan, No
     {{students-age}}, {{#yesno students-age}} → 24, No
     {{#date students-dob "dd/MM/yyyy"}}, {{#yesno students-dob}} → 03/01/2000, No
     

3. Adjust Date {{{#adjustdate ReplaceWithFieldApiName NumberOfDays "ReplaceWithDateFormat"}}

   • It adjusts a given date/time value from ReplaceWithFieldApiName by the specified number of days in NumberOfDays and formats the result according to ReplaceWithDateFormat.

   • If NumberOfDays is positive, the date moves forward (future).

   • If NumberOfDays is negative, the date moves backward (past).

   • For more details of formatting, visit here.

   • Example
     {{#date offers-offer_date "dd/MM/yyyy"}} → 23/09/2024
     {{#adjustdate offers-offer_date 7 "dd/MM/yyyy"}} → 30/09/2024
     {{#adjustdate offers-offer_date -5 "dd/MM/yyyy"}} → 18/09/2024

Format

1. Date {{#date ReplaceWithFieldApiName "ReplaceWithDateFormat"}}

   • You can convert the format of Date through this helper.

   • This helper requires 2 arguments. ReplaceWithFieldApiName should be the field API name that you want to convert and ReplaceWithDateFormat is the same as Current Date/Time but it doesn’t support Time format.

   • For more details of formatting, visit here.

   • Example
     {{#date offer_courses-start_date "dd MMMM yyyy"}} → 13 July 2023
     {{#date offer_courses-start_date "dd/MM/yyyy"}} → 13/07/2023
     

2. Currency {{#currency ReplaceWithFieldApiName CurrencySymbol LocateSymbolEnd}}

   • You can use this helper to add a currency symbol and display values with two decimal places.

   • Optionally, you can specify a currency symbol for the result. To use a currency symbol other than the default, enter the desired symbol within quotation marks in the CurrencySymbol. If you want to display the currency without any symbol, leave the field blank.
     For example: '£', '€', '₩', or ''.

   • If no value is provided in CurrencySymbol, the system's default currency symbol will be used.

   • If you want the provided Currency Symbol to appear after the number instead of before it, add true in the LocateSymbolEnd after the CurrencySymbol value. This must be used together with CurrencySymbol.

   • Examples
     {{offer-course_amount}} → 17520.50
     {{#currency offers-course_amount}} → $17,520.50
     {{#currency offers-course_amount ''}} → 17,520.50
     {{#currency offers-course_amount '£'}} → £17,520.50
     {{#currency offers-course_amount '₩'}} → ₩17,520.50
     {{#currency offers-course_amount '€' true}} → 17,520.50€

   Most of currency fields in eBECAS/EDMISS is already combined with this helper. Use this helper if you need to add a new field with a currency or modify how the currency unit is displayed.
   

3. Percent {{#percent ReplaceWithFieldApiName ReplaceWithPrecision}}

   • You can add percentage unit and decimal places through this helper displaying the value of a field as percentage by adding the % symbol.

   • Precision represents a number how many decimal places you intend to display. If you don’t provide it, it’ll follow the default value same as the format in your database.

   • Example - A course with 50% discounted.
     {{offer_courses-discount_percent}} → 50
     {{#percent offer_courses-discount_percent}} → 50.00 %
     {{#percent offer_courses-discount_percent 0}} → 50 %
     {{#percent offer_courses-discount_percent 4}} → 50.0000 %

Formula

ADVANCED

As Grid type template is about multiple values you need to show repeatedly, Sum currency helper shouldn't be placed in the grid template.

1. Sum Currency (grid-field) {{#sumcurrency ReplaceWithGridApiName ReplaceWithFieldApiName CurrencySymbol LocateSymbolEnd ComparisonFieldApiName ComparisonValue}}

   • You can sum all the values of a single field in a grid and display the result as currency. This is very useful when you want to show total prices for offers or items. Optionally, you can specify Currency Symbol, Location of the Currency Symbol and Comparison Field with a value to allow operation.

   • Required Arguments

     • ReplaceWithGridApiName

       • Replace it to the grid API name of Grid set(with a table icon).

     • ReplaceWithFieldApiName

       • Replace it to the field API name that you'd like to sum all from the selected Grid container in ReplaceWithGridApiName.

   • Optional Arguments

     • CurrencySymbol

       • To use a currency symbol other than the system’s default, enter the desired symbol within quotation marks in CurrencySymbol. If this is omitted, the system’s default symbol will be used. If you want to display the currency without any symbol, leave the field blank.
         For example: '£', '€', '₩', or ''.

     • LocateSymbolEnd

       • If you want the provided currency symbol to appear after the number instead of before it, set LocateSymbolEnd to true after the CurrencySymbol value.

       • This must be used together with CurrencySymbol.

     • ComparisonFieldApiName and ComparisonValue

       • You can apply a condition so that the operation only includes entries in the grid where the value of ComparisonFieldApiName equals ComparisonValue.

         • ComparisonFieldApiName must be from the selected Grid container in ReplaceWithGridApiName.

         • ComparisonValue can either be another field bookmark in the same grid or a manually entered value within quotation marks.

         • The comparison is case-insensitive.

         • To use this conditional comparison, you must include both CurrencySymbol and LocateSymbolEnd.

2. Sum Currency (single fields) {{#addcurrency ReplaceWithFieldApiName1 ReplaceWithFieldApiName2 CurrencySymbol LocateSymbolEnd}}

   • You can add the value of FieldApiName1 to the value of FieldApiName2 and formats the result as currency. Optionally, you can specify Currency Symbol, Location of the Currency Symbol. This is much helpful when you need to simply add two currency fields.

   • Required Arguments

     • ReplaceWithFieldApiName1 and ReplaceWithFieldApiName2

       • Replace them to the field API names that you'd like to add together. These fields must not be grid-fields.

   • Optional Arguments

     • CurrencySymbol

       • To use a currency symbol other than the system’s default, enter the desired symbol within quotation marks in CurrencySymbol. If this is omitted, the system’s default symbol will be used. If you want to display the currency without any symbol, leave the field blank.
         For example: '£', '€', '₩', or ''.

     • LocateSymbolEnd

       • If you want the provided currency symbol to appear after the number instead of before it, set LocateSymbolEnd to true after the CurrencySymbol value.

       • This must be used together with CurrencySymbol.

3. Sum Currency (grid-fields) {{#sumaddcurrency ReplaceWithGridApiName ReplaceWithFieldApiName1 ReplaceWithFieldApiName2 CurrencySymbol LocateSymbolEnd ComparisonFieldApiName ComparisonValue}}

   • You can sum all the values of FieldApiName1 and FieldApiName2 in a grid and formats the result as currency. Optionally, you can specify Currency Symbol, Location of the Currency Symbol and Comparison Field with a value to allow operation. This is much helpful to display the total sum values for 2 different fields.

   • Required Arguments

     • ReplaceWithGridApiName

       • Replace it to the name of Grid set(with a table icon).

     • ReplaceWithFieldApiName1 and ReplaceWithFieldApiName2

       • Replace them to the fields that you'd like to sum all from the selected Grid container in ReplaceWithGridApiName. Both fields must be grid-fields.

   • Optional Arguments

     • CurrencySymbol

       • To use a currency symbol other than the system’s default, enter the desired symbol within quotation marks in CurrencySymbol. If this is omitted, the system’s default symbol will be used. If you want to display the currency without any symbol, leave the field blank.
         For example: '£', '€', '₩', or ''.

     • LocateSymbolEnd

       • If you want the provided currency symbol to appear after the number instead of before it, set LocateSymbolEnd to true after the CurrencySymbol value.

       • This must be used together with CurrencySymbol.

     • ComparisonFieldApiName and ComparisonValue

       • You can apply a condition so that the operation only includes entries in the grid where the value of ComparisonFieldApiName equals ComparisonValue.

         • ComparisonFieldApiName must be from the selected Grid container in ReplaceWithGridApiName.

         • ComparisonValue can either be another field bookmark in the same grid or a manually entered value within quotation marks.

         • The comparison is case-insensitive.

         • To use this conditional comparison, you must include both CurrencySymbol and LocateSymbolEnd.

4. Subtract Currency (single fields) {{#subtractcurrency ReplaceWithFieldApiName1 ReplaceWithFieldApiName2 CurrencySymbol LocateSymbolEnd}}

   • You can subtract the value of FieldApiName2 from the value of FieldApiName1 and format the result as currency. Optionally, you can specify Currency Symbol, Location of the Currency Symbol. It’s useful to display differences between 2 currency fields.

   • Required Arguments

     • ReplaceWithFieldApiName1 and ReplaceWithFieldApiName2

       • Replace them to the field API names that you'd like to subtract. It’ll subtract the value of ReplaceWithFieldApiName2 from ReplaceWithFieldApiName1. These fields must not be grid-fields.

   • Optional Arguments

     • CurrencySymbol

       • To use a currency symbol other than the system’s default, enter the desired symbol within quotation marks in CurrencySymbol. If this is omitted, the system’s default symbol will be used. If you want to display the currency without any symbol, leave the field blank.
         For example: '£', '€', '₩', or ''.

     • LocateSymbolEnd

       • If you want the provided currency symbol to appear after the number instead of before it, set LocateSymbolEnd to true after the CurrencySymbol value.

       • This must be used together with CurrencySymbol.

5. Subtract Currency (grid-fields) {{#sumsubtractcurrency ReplaceWithGridApiName ReplaceWithFieldApiName1 ReplaceWithFieldApiName2 CurrencySymbol LocateSymbolEnd ComparisonFieldApiName ComparisonValue}}

   • You can subtract the sum of FieldApiName2 from the sum FieldApiName1 in a grid and formats the result as currency. This means it calculates the difference between the value of ReplaceWithFieldApiName1 and the value of ReplaceWithFieldApiName2 for each entry in a grid. Then, sum up all these calculated differences. Optionally, you can specify Currency Symbol, Location of the Currency Symbol and Comparison Field with a value to allow operation.

   • Required Arguments

     • ReplaceWithGridApiName

       • Replace it to the name of Grid set(with a table icon).

     • ReplaceWithFieldApiName1 and ReplaceWithFieldApiName2

       • Replace them to the fields that you'd like to subtract from the selected Grid container in in ReplaceWithGridApiName. Both fields must be grid-fields.

   • Optional Arguments

     • CurrencySymbol

       • To use a currency symbol other than the system’s default, enter the desired symbol within quotation marks in CurrencySymbol. If this is omitted, the system’s default symbol will be used. If you want to display the currency without any symbol, leave the field blank.
         For example: '£', '€', '₩', or ''.

     • LocateSymbolEnd

       • If you want the provided currency symbol to appear after the number instead of before it, set LocateSymbolEnd to true after the CurrencySymbol value.

       • This must be used together with CurrencySymbol.

     • ComparisonFieldApiName and ComparisonValue

       • You can apply a condition so that the operation only includes entries in the grid where the value of ComparisonFieldApiName equals ComparisonValue.

         • ComparisonFieldApiName must be from the selected Grid container in ReplaceWithGridApiName.

         • ComparisonValue can either be another field bookmark in the same grid or a manually entered value within quotation marks.

         • The comparison is case-insensitive.

         • To use this conditional comparison, you must include both CurrencySymbol and LocateSymbolEnd.

Document Utilities

Document Utilities are used for document management, such as document page break and page numbering.

1. Page Break {{{#pagebreak}}}

   • Insert it to break a page by force on a document.

   • Unlike other helpers, It must be placed in the triple curly brackets.

2. Page Number {{#pagenumber}}

   • It displays the current page number on a document.

3. Total Page Number {{#numpages}}

   • It displays the total page number on a document.

Conditional

ADVANCED

Conditional helpers are used to display different values or content based on specific conditions.

1. Conditional Value
   It evaluates a specified field's value against a given comparison value to determine which value to display based on the condition.

   CODE

   {{#ifcond ReplaceWithFieldApiName (ComparisonOperator) "ComparisonValue" "ValueIfTrue" "ValueIfFalse" "OptionalComparisonType"}}

   • ReplaceWithFieldApiName : Field used for comparison.  

   • (ComparisonOperator): Defines how to compare the field's value against the ComparisonValue. Supported operators are:

     • eq: Equal to

     • ne: Not equal to

     • lt: Less than

     • lte: Less than or equal to

     • gt: Greater than

     • gte: Greater than or equal to

   • ComparisonValue: The value being compared with the value of ReplaceWithFieldApiName.  

   • ValueIfTrue: The value to display if the condition is true.

   • ValueIfFalse: The value to display if the condition is false.

   • OptionalComparisonType (optional): Used to specify how the comparison should be evaluated. If this is not provided, all values are compared as plain text (string comparison).

     When comparing as text:

     • Operators like lt, lte, gt, and gte will perform a character-by-character string comparison, which may not give expected results for dates or numbers.

     To enable proper date or numeric comparison, specify one of the following types:

     • number: Converts both the field value and the comparison value into numbers. This allows accurate numeric comparison, especially useful for currencies or any numeric fields.

     • date: Treats both values as dates. You can also use "now" as the ComparisonValue to dynamically compare the field’s date against the current date.

     • matchcase: Applies only to string comparisons. Makes the comparison case-sensitive (e.g., "ABC" ≠ "abc").

2. Check Field Value Block
   It allows you to render content conditionally based on a specified field’s value.

   CODE

   {{#checkif ReplaceWithFieldApiName}} 
     "BodyIfTrue" 
   {{else}} 
     "BodyIfFalse" 
   {{/checkif}} 

   • ReplaceWithFieldApiName: This is the name of the field whose value will determine which block of content to display. If the field contains any value, except false, 0 or "" (empty value), the content inside "BodyIfTrue" will be displayed.

   • {{else}} "BodyIfFalse":This is an optional part of the conditional statement that defines the block of content to be displayed when the condition is false. If the field’s value is empty or contains a value such as false or 0 which makes the condition false, the content inside "BodyIfFalse" will be displayed.

{{#checkif enrolments-arrived}} 
  The student has arrived.
{{else}} 
  The student has not arrived yet.
{{/checkif}} 

3. Conditional Block
   It allows you to render content conditionally based on a specified field’s value against a given comparison value to determine which block to display based on the condition.

   CODE

   {{#blockif ReplaceWithFieldApiName (ComparisonOperator) "ComparisonValue" "OptionalComparisonType"}} 
     "BodyIfTrue" 
   {{else}} 
     "BodyIfFalse" 
   {{/blockif}}

   • ReplaceWithFieldApiName : Field used for comparison.  

   • (ComparisonOperator): Defines how to compare the field's value against the ComparisonValue. Supported operators are:

     • eq: Equal to

     • ne: Not equal to

     • lt: Less than

     • lte: Less than or equal to

     • gt: Greater than

     • gte: Greater than or equal to

   • ComparisonValue: The value being compared with the value of ReplaceWithFieldApiName.  

   • BodyIfTrue: The Body Content to display if the condition is true.

   • BodyIfFalse: The Body Content to display if the condition is false.

   • OptionalComparisonType (optional): Used to specify how the comparison should be evaluated. If this is not provided, all values are compared as plain text (string comparison).

     When comparing as text:

     • Operators like lt, lte, gt, and gte will perform a character-by-character string comparison, which may not give expected results for dates or numbers.

     To enable proper date or numeric comparison, specify one of the following types:

     • number: Converts both the field value and the comparison value into numbers. This allows accurate numeric comparison, especially useful for currencies or any numeric fields.

     • date: Treats both values as dates. You can also use "now" as the ComparisonValue to dynamically compare the field’s date against the current date.

     • matchcase: Applies only to string comparisons. Makes the comparison case-sensitive (e.g., "ABC" ≠ "abc").

Grid Utilities

The following utilities streamline the management of datasets containing multiple records.

1. Grid Wrapper

This utility allows to iterate through a series of records that belong to an Object. For example, if you want to iterate and insert all the Contacts (records) for a Student.

Let’s explore the syntax:

{{#each ReplaceWithGridApiName}} 
    {{GridApiName-FieldApiName}} 
{{/each}}

1. {{#each ReplaceWithGridApiName}} ... {{/each}}: These tags wrap the content that you want iterate through.

2. GridApiName: This is the API name of the object that you want to iterate through. This object must be a Grid Item.

3. FieldApiName: This is the API name of the field that will be inserted. This field must belong to the GridApiName defined in the {{#each}} tag.

Let’s see some examples:

Example 1: Insert all the contacts related to a student
Input

    Hi, Student!
    We're sending this email to confirm your emergency contacts.
    
    {{#each student_contacts}}
    Name : {{student_contacts-name}}
    Mobile : {{student_contacts-mobile}}
    {{/each}}
    
    Please let us know, if there's anything incorrect.                

Output
The output will have a list of all the contacts related to the student.

Hi, Student!
We’re sending this email to confirm your emergency contact.

Name : Jone Doe
Mobile : 0412123456

Name : Jane Doe
Mobile : 0498987654

Please let us know, if there’s anything incorrect.

Example 2: This is the same as the previous example but with some HTML code
Input

          
  <div>
    <p>Hi, Student!</p>
    <p>We're sending this email to confirm your emergency contact.</p>
    <table>
      <thead>
        <tr>
          <td>Name</td>
          <td>Mobile</td>
        </tr>
      </thead>
      <tbody>
        {{#each student_contacts}}
        <tr>
          <td>{{student_contacts-name}}</td>
          <td>{{student_contacts-mobile}}</td>
        </tr>
        {{/each}}
      </tbody>
    </table>
    <p>Please let us know if there's anything incorrect.</p>
  </div>
        

Output

Hi, Student!

We’re sending this email to confirm your emergency contact.

Please let us know, if there's anything incorrect.