¶ Expressions
¶ Introduction
Expressions are a powerful addition to Maven Documents. You've probably already noticed this term when going through elements reference. As you can find there, some of the attributes of those elements have the option to also use Expressions as the attribute value.
Maven Documents Expressions using Javascript Expression Language - powerful context-based expression parser and evaluator.
You will find that examples from the Jexl Documentation are fully compatible with Maven Documents.
There is also a free Jexl Playground that you can explore and play around in.
¶ Can Jexl Examples Simply be "Copy-Pasted"?
They almost can.
You only need to keep in mind two things when trying to copy-paste such examples.
- Expressions need to have a certain form in order for Maven Documents to recognize them successfully.
You are already familiar with {!QueryName.FieldName} notation which you can use to add fields in your Template Document.
And now when you write Expressions, you would need to input a slightly different notation: {!$Expression}. - If {!$Expression} receives any arguments, you would need to make sure that those arguments exist (are valid).
Arguments on Jexl Documentation most certainly will never be. But, you always have the information about arrays or fields that can be used as arguments in your Expressions in - either Template Builder or even Query Builder in Salesforce.
¶ What is the Best Way To Start Using Expressions?
Instead of going through Jexl Examples, we prepared some of the examples that are ready to be copy-pasted and tested out easily.
We suggest you use Sales Quote from our Document Solution Gallery which is fully compatible with every example we are using further in the document. These examples are sorted out by the input (argument) they ingest and you can find them below.
We also built custom Expressions based on the feedback of our current clients that are using the Maven Documents app and integrated them as well. These custom Expressions proved to be quite helpful in building a complex Document Template and serve as enrichment to standard Jexl ones.
You can recognize them by the marked "custom" checkbox in the tables below.
¶ Where Can I Use Expressions?
- As mentioned in the introduction, you can use Expressions in any attribute of the element that supports it. That information can be found in the elements reference.
- They can also be used in the variable elements themselves - which is the reason the variable element exists in the first place. Once placed inside the variable, it will hold the computed value of the Expression, and you can then place that variable in multiple places in the Template Document, instead of writing the same Expression every time over and over again.
- In Query Builder as an Expression Field. We call them Expression fields because they are used the same way as Salesforce fields are used in Query Builder.
These Expressions will be executed for every record on the Object that they are defined on.
They only have visibility of the exact record that they are located on and every Global Variable.
So inside of that Expression, you can use any Salesforce field that you selected with Query Builder and any Global Variable you created. - Expressions can also be placed directly in the Template Document. Same as you would place fields, but again with a slightly modified notation that is used for Expressions only - {!$Expression}.
¶ Value wrapping in Expressions
Every field value used inside of an expression is considered a String at first, regardless of its data type in Salesforce. That means that it's important to wrap the field value when performing data type-specific operations. For example, one might think that result of the following expression: '{!$Opportunity[0].Amount + 10}' will be the addition of the first opportunity amount and number 10. That is incorrect. Remember, once we import the field value of the opportunity amount into the expression it is considered a String. So expression parser will validate this as a concatenation of two string values. To perform addition we would have to wrap the opportunity amount field value using the toDecimal function.
¶ Array
| Expression | Expected | Actual |
|---|---|---|
{!$count( |
1 | 1 |
{!$isEmpty( |
No records in the "Account" object | false |
{!$isNotEmpty( |
The "Account" Object contains records | true |
{!$max(Account[0] |
The largest Account Opportunity Amount | 435000 |
{!$min(Account[0] |
The smallest Account Opportunity Amount | 435000 |
{!$sum(Account[0] |
Sum of the Account Opportunities Amounts | 435000 |
{!$join(Account[0] |
Connects all values of a field in an array of objects with a separator between them | 1,2,1,1 |
¶ String
| Expression | Expected | Actual |
|---|---|---|
{!$isBlank(Account[0] |
The "Account Name" field is empty | false |
{!$contains(Account[0] |
The "Account Name" field contains the letter 'a' | true |
{!$contains(Account[0] |
The "Account Name" field contains the letter 'z' | false |
{!$lastIndexOf(Account[0] |
The position of the last occurrence of the Account with the 'a' letter in the name | 34 |
{!$substring(Account[0] |
The Part of the Account's name between the 0th and 10th Indexes | Burlington |
¶ Number
| Expression | Expected | Actual |
|---|---|---|
{!$toDecimal(Account[0] |
The Opportunity's Amount | 435000 |
{!$toDecimal(Account[0] |
The Opportunity's Amount + 10 | 435010 |
{!$toPercent(0.123, |
Show the number as the percentage with 2 digits after the comma | 12.30% |
{!$round(10.234, |
Round the number to 2 digits after the comma | 10.23 |
{!$setScale(10.23, |
Show the number with 4 digits after the comma | 10.2300 |
{!$row()} |
Returns the row (number) of the Cell from Repeater in Google Sheets or XLSX file | 12 |
{!$column()} |
Returns the column (number) of the Cell from Repeater in Google Sheets or XLSX file | E |
{!$index()} |
Returns the index (ordinal number) of the repeating value in Repeater and Table | 1, 2, 3 |
¶ DateTime
| Expression | Expected | Actual |
|---|---|---|
{!$date(Account[0] |
Full Opportunity's closure date and time | Sat Jun 05 2021 00:00:00 GMT-0400 (Eastern Daylight Time) |
{!$time(Account[0] |
Full Opportunity's closure time | 00:00:00 GMT-0400 (Eastern Daylight Time) |
{!$dateTime( |
Full Account's creation date and time | Wed Aug 04 2021 04:37:00 GMT-0400 (Eastern Daylight Time) |
{!$now()} |
Full current date and time | Tue Aug 24 2021 03:10:24 GMT-0400 (Eastern Daylight Time) |
{!$addDays(now(), |
Full Current date and time + 10 days | Fri Sep 03 2021 03:10:24 GMT-0400 (Eastern Daylight Time) |
{!$addMonths(now(), |
Full Current date and time + 10 months | Fri Jun 24 2022 03:10:24 GMT-0400 (Eastern Daylight Time) |
{!$addYears(now(), |
Full Current date and time + 10 years | Sun Aug 24 2031 03:10:24 GMT-0400 (Eastern Daylight Time) |
¶ Format
| Expression | Expected | Actual |
|---|---|---|
{!$format( |
Opportunity Amount with two decimal 00 | 435,000.00 |
{!$format(now(), |
The current date in the short format | 8/24/2021 |
{!$format(now(), |
The current time in the short format | 12:10 AM |
{!$format(now(), |
The current date and time in the short format | 8/24/2021, 12:10 AM |
{!$format(dateTime |
Opportunity Last Modified Date in the short format | 8/24/2021 |
¶ Comparison
Lets say that {!$toDecimal(Account[0].Opportunities[0].Amount)} gives value of 150.
| Expression | Expected | Actual |
|---|---|---|
{!$toDecimal( |
The Account opportunity's amount is lesser than 100 | false |
{!$toDecimal( |
The Account opportunity's amount is greater than 100 | true |
{!$toDecimal( |
The Account opportunity's amount is lesser than or equal to 100 | false |
{!$toDecimal( |
The Account opportunity's amount is greater than or equal to 100 | true |
¶ Logical
| Expression | Expected | Actual |
|---|---|---|
{!$toBoolean( |
If the Account opportunity's amount is lesser than 100, it is true. Otherwise, it is false | false |
¶ GroupBy
We can use the groupBy function to group records by the desired field. Consider the following scenario.
Let's say that the example above generates a table like this one.
However, if we want to create separate tables for records with a different Quantity value we can use a variable which groups the OpportunityLineItems records using the Quantity field.
The example above will result in the following three tables.
