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.

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.

1. In the editor toolbar, click Insert Field Function .
2. In the dialog box, select the desired field.
3. Click OK.

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 Subset of recipients defined by rules and conditions and a logic relationship between them. For example, all recipients in the United Kingdom.. 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.

Editing 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:

  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 Channel through which advertising messages or information are transmitted to customers and prospects. For example, email, SMS, print or push.) 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 One component of a campaign. As examples, recipients and email are elements. Nodes are used to transfer elements through the sequence of actions that occur when a campaign is activated. 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>

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:

• &lt;. (< less than)
• &gt; (> greater than)
• &quot; (" quotation mark)
• &amp; (& 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}

Velocity classes and functions

Optimizely Campaign provides several classes and functions that you can use to define field functions.

• $user.data
• $bmFormat
• $bmMimeType
• $filter

$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).

$user.data.[field_name] == "string"

$user.data.[field_name] == X

$user.data.[field_name] != "string"

$user.data.[field_name].startsWith ("string")

$user.data.[field_name] != X

$user.data.[field_name] <= X

$user.data.[field_name] >= X

$user.data.[field_name] > X

$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:

#if($user.data.bmIsOnlineVersion)cLICK <a href="{Online-Version-Link}" 
target="_blank">here</a> to read an online version of this newsletter.

$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)

$bmFormat.formatPercentage

$bmFormat.formatCurrency

$bmFormat.formatDate

$bmFormat.formatDateTime

$bmFormat.formatTime

Attributes for formatting numeric values

$bmMimeType

Query the mime type of the mailing that is currently rendered.

$bmMimeType == "text/plain"

$bmMimeType == "text/html"

$filter

Invoke a target group. The submitted string must match a target group ID of your Optimizely Campaign client The working environment of Optimizely Campaign. A client is a stand-alone and closed system that serves to organize your mailings. Campaign users can use one or more clients for your scenario.. To get the IDs of your target groups, contact customer support. 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:

$filter.filterByRevisionedFilter

Field function templates

The following topics provide you with Velocity and ODR templates that let you create your own field functions: