Introduction to field functions
This topic describes how to work with field functions to personalize or adjust mailing content. Optimizely Campaign uses the template engines Dynamic rendering (ODR) and Velocity that lets you create your own field functions.
ODR is an XML-based script language for field functions; Velocity is a Java-based language. You should have some knowledge of HTML/XML or Java because this documentation provides only the basics of using Dynamic Rendering or Velocity. For the most common use cases you can also use the Optimizely Campaign field function templates.
Note
Dynamic Rendering and Velocity classes and operations
The special feature, Edit Field Functions, provides a wide range of personalization options for your mailings. However, only classes, operations, and parameters documented in this manual are permitted for the creation of field functions. Velocity or Dynamic Rendering code not documented here may interfere with or damage your mailing templates and affect the sending of mailings.
Read this documentation thoroughly.
Always test user-defined field functions with the personalized preview. If you have any questions or doubts about the code and its correct utilization, contact customer support.
Adding field functions to mailings
In the context of a mailing (paragraph, subject, and so on), you insert field functions using a placeholder in curly brackets { }. To add a field function to a paragraph, follow these steps when editing a mailing.
- In the editor toolbar, click Insert Field Function .
- In the dialog box, select the desired field.
- Click OK.
Tip
If you know the name of a field function, insert the name between curly brackets wherever you want it to appear in a mailing. When the mailing is sent, the field function placeholder is replaced by the content for which the field function stands.
Field function use cases
Field functions replace or personalize content. The field function definition generates a string (some text) and inserts it in the mailing. Some field functions are a simple replacement, for example they set the name or a date. Others can distinguish among different cases and replace the content accordingly. Also, field functions can be defined through target groups. These only generate text if the recipient matches the target group. The following list gives examples of field functions:
- Date. The current date is inserted.
- Salutation. A salutation usually contains one for males, another for females, and neutral term for recipients whose name and gender are unknown.
- Subject line. For example, the name or other personalization strings.
Tip
Personalized links
You can use field functions to create personalized links in your mailings. You also can use field function placeholders in the domain part or path of a URL and in URL parameters. The link tracking of personalized links works as in regular links.
introduction-to-field-functions.mdxEditing field functions
To edit a field function, select Administration > Field Functions. The overview shows editable field functions. If you are working in a sub-client, the list also shows field functions inherited from the main client but these cannot be edited. Select a field function from the list and click Edit….
To create a new field function, click Create…. If you remove a field function, make sure it is not used in an active mailing.
- Inheritable. Select if you want to make the field function available in sub-clients. Users logged into a sub-client can use inherited functions, but not edit them.
- Type. Select which rules are applied for validation and execution of a field function:
Note
Do not change the type if you are not sure of what you are doing.
- JSPX. This type accepts only valid XML code.
- Velocity. This type accepts only Velocity code.
- Example. Shows a replacement example. Enter an actual example or a description of the field function that explains the field function.
- Content. Enter the field function definition using either Dynamic Rendering or Velocity for each mailing type, media type (marketing channel) or content type. This may be static text, dynamic text or both. To create dynamic content, enter commands and queries that are executed when the mailing is sent.
- Default Replacement. Contains a fallback that is applied if a field function is not defined. Also, if you do not want to specify different field functions for each email type, media type, and element type, use this field and leave the others empty.
- Text. Write the code and text for the field function used in the text version of a mailing.
- HTML. Write the code and text of a field function used in the HTML version of a mailing.
- SMS. Write the code and text of a field function used in SMS mailings.
- Subject. Write the code and text of a field function used in the subject line of a mailing.
Template engines
Template engines are software tools to process a field function. That is, they read the commands in a field function, query the database, and create an output string. Optimizely Campaign provides two template engines: the proprietary Dynamic Rendering engine, and the Velocity engine. The following paragraph introduces these two and lists available classes and functions.
ODR – Dynamic Rendering
If your are familiar with XML and HTML tags, you can learn how to write field functions in the Dynamic Rendering language. The following example shows a salutation logic written in Dynamic Rendering.
Sample code
<odr:choose> <odr:when test="%{not empty user.data.firstname and not empty user.data.lastname and user.data.salutation == 'Mrs.'}"> <odr:out value="Dear Mrs. %{user.data.firstname} %{user.data.lastname}," /> </odr:when> <odr:when test="%{not empty user.data.firstname and not empty user.data.lastname and user.data.salutation == 'Mr.'}"> <odr:out value="Dear Mr. %{user.data.firstname} %{user.data.lastname}," /> </odr:when> <odr:otherwise> <odr:out value="Dear Sir or Madam," /> </odr:otherwise></odr:choose>Tip
Remarks
- Line 1. The choose tag initiates a query of several parameters. It contains no attributes.
- Lines 2 and 7. The when tag initiates the query of a single parameter. Attributes are the parameter itself and the values. In the example, the tag checks whether the fields first and last name in the recipient list are not empty and whether the field Salutation contains Mrs. or Mr..
- Lines 4 and 8. The out tag contains the output string. This is static or dynamic text or both, like in the example.
- Line 12. The otherwise tag defines the output string for cases that do not match a previous tag. It contains no attributes
Line breaks, blank spaces and formatting with Dynamic Rendering
Line breaks and blank spaces between Dynamic Rendering tags are escaped during the rendering. You can insert blank spaces in the running text inside the quotation marks. HTML tags inside the Dynamic Rendering expressions (that is, inside the quotation marks) must be written as entities. Use the following entities to escape the respective characters:
- <. (< less than)
- > (> greater than)
- " (" quotation mark)
- & (& ampersand)
Velocity
Velocity is a Java-based template engine. Velocity algorithms can appear within HTML in a mailing or a website. An algorithm may contain conditions and fallbacks, which generate some text if true and another text or no text if false.
Velocity references are initiated with a $ sign, followed by a class and a function. Two examples are below.
Example: Insert first and last name of a recipient in a salutation
Dear ${user.data.firstname} ${user.data.lastname}!You also can use the expression ${user.data.[field_name]} to address any field in the recipient list by replacing [field_name] with the field name.
If your recipient list contains recipients whose first name is unknown, because it is usually not a mandatory field, the expression shown above needs to be extended. Otherwise, it could produce a salutation like "Dear Smith!". With Velocity, you can define an alternative expression, using "Dear Mrs." or "Dear Mr." plus the recipient's last name.
Example: Salutation with complete name and fallback
To consider possible cases, write an if-then algorithm. This algorithm is initiated with a pound sign (#) and the command if. Below, the different cases and an alternative (else) are formulated. The algorithm ends with #end:
#if("$!{user.data.lastname}" != "" &&"$!{user.data.gender}" != "")Dear#if($user.data.gender.startsWith("male"))Mr. #if($user.data.gender.startsWith("female"))Mrs.#end $user.data.lastname#else$!{null}Dear Sir or Madam#end$!{null}Tip
Remarks
- Line 1. To formulate the salutation, the recipient's last name and gender must be known. In this line, the field function checks whether both exist for a given recipient. (If lastname is not null AND gender is not null...) If you formulate an #if operation, use the special operator $!. Otherwise, if the variable is not defined, Velocity would read the variable's name as a string (and not its value, because there is none) and, when an expression "does equal" is formulated, the result would be false, because the string is unequal to a non existing value. The special operator $! suppresses this expression if the variable it is not defined. The whole expression is wrapped in quotation marks. If a field is not defined for a recipient, a query would deliver the result NULL. The quotation marks transform this into an empty string, which can be validated with conditions of the type ="" (is empty) or !="" (is not empty).
- Line 2. If the gender is male, the correct form "Mr." is chosen.
- Line 3. If the gender is female, the form "Mrs." is chosen, followed by the recipient's last name.
- Line 4. The placeholder #else creates a fallback, which is used if the first condition does not match, that is if either the last name or the gender are not known. In this case, a neutral, general salutation is displayed. If Velocity commands are inserted directly into continuous text, space characters after such commands are ignored. This may cause text that follows a Velocity command to be interpreted together with the command. The result is a syntax error. To avoid such errors, a NULL object must be inserted between the Velocity command and the text: $!{null}. This object does not generate any output but closes the preceding command. Close Velocity-Code with the Tag #end. After this tag, insert a line break.
Velocity classes and functions
Optimizely Campaign provides several classes and functions that you can use to define field functions.
introduction-to-field-functions.mdx$user.data
Query fields of a recipient list. Use this function either to insert the value of a field (such as a user's name) in a mailing (placeholder), or to check if the field matches a given value (if-then-function).
Function | Velocity code |
|---|---|
Value equals a string value | ``` |
$user.data.[field_name] == "string" | |
| Value equals a numeric value | ```
$user.data.[field_name] == X
``` |
| Value does not equal a string value | ```
$user.data.[field_name] != "string"
``` |
| Value starts with a string value | ```
$user.data.[field_name].startsWith ("string")
``` |
| Value does not equal a numeric value | ```
$user.data.[field_name] != X
``` |
| Value is less than or equals a numeric value | ```
$user.data.[field_name] <= X
``` |
| Value is greater than or equals a numeric value | ```
$user.data.[field_name] >= X
``` |
| Value is greater than a numeric value | ```
$user.data.[field_name] > X
``` |
| Special function: IsOnlineVersion | ```
$user.data.bmIsOnlineVersion
``` |
Use **IsOnlineVersion** to check whether the online version of a newsletter is currently displayed. The return value is `true`. To hide the link to the online version, if it is already displayed, specify the following Velocity code:
```velocity
#if($user.data.bmIsOnlineVersion)cLICK <a href="{Online-Version-Link}" target="_blank">here</a> to read an online version of this newsletter.introduction-to-field-functions.mdx$bmFormat
Format a value within this expression. You can only format dates and numeric values, but you can add an optional pattern or the number of decimal places (precision). The following code show an example of using $bmFormat:
You registered with us on $bmFormat.formatDate($user.data.created)Function | Velocity code |
|---|---|
Format as percentage | ``` |
$bmFormat.formatPercentage | |
| Format as currency. If the parameter **includeCurrencySymbol** is set to `true`, the currency symbol is displayed. | ```
$bmFormat.formatCurrency
``` |
| Format a date | ```
$bmFormat.formatDate
``` |
| Format a date and time | ```
$bmFormat.formatDateTime
``` |
| Format a time | ```
$bmFormat.formatTime
``` |
##### Attributes for formatting numeric values
| Attribute | Description |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| pattern | * **Numeric values**. Use the pattern **###,###,###.##** or **000000.000**.
# stands for a digit, 0 for leading or trailing zeros.
The dot indicates a decimal separator and can only appear once in the pattern. The comma is used is used as a grouping symbol and can appear any number of times, except after the decimal point where it may not appear.
:::hint{style="info"}
**Note**
The output that this creates has numeric values appear with German formatting; that is, the grouping symbol (comma in the pattern) is displayed as a dot and the decimal separator (dot in the pattern) is displayed as a comma—for example "1.000,00". English formatting (for example "1,000.00") is not supported.
:::
Examples for the value 1000:
Pattern Output###,###,###.## 1.000
000,000,000.00 000.001.000,00
##,##.0### 10.00,0
###.###.###.## ✘ invalid, there are too many dots
###.###,## ✘ invalid, the comma appears after the dot
* **Date values**. Use the pattern `dd.MM.yyyy`.
* **Time values**. Use the pattern `hh:mm:ss`.
For more information about formatting numbers and dates, see the [Java documentation](https://docs.oracle.com/javase/tutorial/i18n/format/simpleDateFormat.html) from Oracle. |
| precision | Integer value that specifies the number of decimal places to which the output value should be rounded. |
#### []()$bmMimeType
Query the mime type of the mailing that is currently rendered.
| Mime Type | Velocity code |
| ----------------- | ----------------------------------- |
| Plain text emails | ```
$bmMimeType == "text/plain"
``` |
| HTML emails | ```
$bmMimeType == "text/html"
``` |
#### []()$filter
Invoke a target group. The submitted string must match a target group ID of your Optimizely Campaign client. To get the IDs of your target groups, contact [customer support](https://support.optimizely.com/hc/en-us/articles/4413200618253). Do not use an ID if you are not sure it matches a target group; otherwise, your template does not work properly. The Velocity code for this function is as follows:
```velocity
$filter.filterByRevisionedFilterintroduction-to-field-functions.mdxField function templates
The following topics provide you with Velocity and ODR templates that let you create your own field functions: