Field functions

This topic describes how to work with field functions to personalize or adjust mailing content. Episerver 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 Episerver Campaign field function templates.

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

Image: Field function icon

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 Episerver image.
  2. In the dialog box, select the desired field.
  3. Click OK.

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 groupsSubset 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.

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.

Editing field functions

To edit a field function, select AdministrationField 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 Add. If you delete 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 channelChannel 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.

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. Episerver 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.

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 (i.e., 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}

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, i.e. 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

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

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

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

    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:

    PatternOutput
    ###,###,###.##1.000
    000,000,000.00000.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 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 Episerver Campaign clientThe working environment of Episerver 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: