Blogs

Expression Evaluation

By Leo Liu posted 01-13-2022 21:22

  

An Expression in the HTML template is a syntactic entity inside {{#Wp_Eval}}, {{/Wp_Eval}} section, it is a combination of one or more constants, variables(merge fields), and operators that the template engine interprets and computes to produce another value.

For example:

There are totally {{#Wp_Eval}} 1 + 2 {{/Wp_Eval}} items.​

Returns:

There are totally 3 items.

Expression with Merge Fields

If you are familiar with the Mustache template engine, Wp_Eval is a lambda function,  and the expression is the argument of that function.

The lambda function is invoked after all the merge fields are replaced with values, which means the expression consists of constants only at the time of expression evaluation.

For example:

You have paid {{#Wp_Eval}} {{Invoice.Amount}} - {{Invoice.Balance}} {{/Wp_Eval}} dollar(s).

{{Invoice.Amount}} and {{Invoice.Balance}} will be replaced with 100.0 and 90.0 for example, so the template engine will evaluate:

{{#Wp_Eval}} 100.0 - 90.0 {{/Wp_Eval}}


which returns:

You have paid 10 dollar(s).

 

Data Type

There are basically 3 types of data in expression:

  • number
  • string
  • boolean

Be aware of the data type because some operators require the same data types on each side. For example:

"-" requires both sides to be a number. You can't do {{Invoice.InvoiceNumber}} - {{Invoice.Balance}}, since InvoiceNumber is a string but Balance is a number.

You need to quote the string-type merge fields to return text content, for example:

{{#Wp_Eval}} {{Invoice.InvoiceNumber}} {{/Wp_Eval}} is an invalid example, because by merge field substitution, the expression evaluation engine will receive something like: {{#Wp_Eval}} INV-000001{{/Wp_Eval}}. As the INV-000001 is not quoted, the engine will treat it as an invalid expression. To correct it, you just simply quote enclose the merge field, like:

{{#Wp_Eval}} "{{Invoice.InvoiceNumber}}" {{/Wp_Eval}}​

Null

There is a difference between the business object value and the rendered value in the template.

For example, Invoice.Comments as a property of a business object, if it's unspecified, its value is null. But if you use it in the template, by the template rendering mechanism, null value will be rendered as a blank string effectively, so, the following expression is invalid:

{{#Wp_Eval}} {{Invoice.Comments}} == null ? "null" : "not null" {{/Wp_Eval}}

That's because by merge field substitution, {{Invoice.Comments}} will be replaced as a string, blank in this case, which is not null. So, the engine will receive an expression like:

== null ? "null" : "not null"

which is obviously invalid.

To correct it, you need to do string comparison:

{{#Wp_Eval}} "{{Invoice.Comments}}" == "" ? "null" : "not null" {{/Wp_Eval}}

Operators

All supported operators are listed in the knowledge center.

Comments

Condition checking could be complicated, especially if there are multiple if-else, to improve the readability, you can add comments for the expression.

There are two ways to add comments:

  • Mustache comment "{{!   }}"

Mustache comment will be substituted with blank string before the expression is evaluated

  • Expression comment "//"

For example, the following comments are all valid:

{{#Wp_Eval}}
  {{! mustache comment }}
  // expression comment
  "hello world"
{{/Wp_Eval}}


Escaping in the Text Box

If you are using the expression in a Text box, like:

It won't work, because the editor will escape the text content. In the above example, there are two problems:

  1. The ">" character in the expression will be escaped as ">"
  2. There are line breaks, which underneath is "<br/>"

So, the engine actually received an expression like:

<br/> &nbsp;100.0 &gt; 0 ? "positive" : "zero or negative"

To fix it, you can either use the same expression but in an HTML box, or replace the ">" with "gt" and also remove line breaks, like:

{{#Invoice}}{{#Wp_Eval}}{{Amount}} gt 0 ? "positive" : "zero or negative"{{/Wp_Eval}}{{/Invoice}}

Remember, the best practice is to use expressions in an HTML box.

Decorate the Expression

The decorator functions also work for expressions.

For example, you use an expression to sum up the total:

{{#Invoice}}
{{#Wp_Eval}}
  {{Amount}} + {{TaxAmount}}|Round(2)|Localise
{{/Wp_Eval}}
{{/Invoice}}


The decorators are appended at the end of the expression, no whitespace in between.

Caveats

Expressions are used for simple value evaluation use cases, you can't use them for:

  • Variable declaration
  • Assignment
  • Function definition
  • Statements like if, for, while, do/while, etc.
  • Block, code inside curly braces, `{ }`
  • Nested Expression (Wp_Eval in another Wp_Eval)
0 comments
106 views