Format and Encode Strings

These functions format, convert, and encode strings. They return a string which can be displayed in a message or evaluated with operators in personalization rules or selections.

The functions change the value only for the output or the query. The data stored in the source is not changed.

Function Overview

ecm:base64Encode

The function ecm:base64Encode encodes a string in Base64, for example a personalized value in a link. After encoding, the value (for example, the contact's last name) is not directly readable, but the target website can decode it. The value returned is a string data type.

Example

Without encoding, a personalized HTML link has the following format:

<a href="https://website.com/shop/<%${user['LastName']}%>">Shop Now!</a>

This link resolves to the following example URL: https://website.com/shop/Smith

With the base64 encoding function, a personalized HTML link has the following format:

<a href="https://website.com/shop/<%${ecm:base64Encode(user['LastName'])}%>">Shop Now!</a>

This link resolves to the following example URL: https://website.com/shop/U21pdGg=

Structure

ecm:base64Encode(string)

Parameters

fn:escapeXml

The function fn:escapeXml escapes characters that could be interpreted as XML or HTML markup, for example <, >, and &. The value returned is a string data type.

Example

A custom attribute stores free text that contacts entered in a form. Before the value is inserted into the HTML of a message, markup characters are escaped so that they are displayed as text:

<%${fn:escapeXml(user.CustomAttribute['Comment'])}%>

Structure

fn:escapeXml(string)

Parameters

fn:replace

The function fn:replace replaces all occurrences of a string in a target with a specified string. The value returned is a string data type.

Example

Values saved in a group attribute include underscores. When these values are inserted into a message, the underscore characters are replaced by a space.

The expression for inserting these values into a message is constructed as follows:

<%${fn:replace(group.CustomAttribute['Name'],'_', ' ')}%>

Structure

fn:replace(string, string, string)

Parameters

fn:toLowerCase

The function fn:toLowerCase converts all of the characters in a string to lower case for the purpose of performing a query. The actual source string is not changed in any way. The value returned is a string data type.

Example

The custom attribute user.CustomAttribute['job title'] contains any number of possible job titles. When the list used to populate this data was created, the spelling of these values was not verified. The values stored in the attribute contain variations in capitalization, for example "MANAGER", "manager", and "Manager".

All recipients with 'manager' (any case) will receive a special text in their email.

The function fn:toLowerCase is used to convert all values in the target attribute to lower case. This result is then compared to specified value manager using the operator == to convert the resulting string into a Boolean value. The text is inserted into the message using an InsertIf statement, which is constructed as follows:

<%InsertIf expression="${((fn:toLowerCase(user.CustomAttribute['job title'])=='manager'))}"%>Text<%/InsertIf%>

Structure

fn:toLowerCase(string)

Parameters

fn:toUpperCase

The function fn:toUpperCase converts all the characters of a string to upper case for the purpose of performing a query. The actual source string is not changed in any way. The value returned is a string data type.

Example

The custom attribute user.CustomAttribute['job title'] contains any number of possible job titles. When the list used to populate this data was created, the spelling of these values was not verified. The values stored in the attribute contain variations in capitalization, for example "MANAGER", "manager", and "Manager".

All recipients with 'manager' (any case) will receive a special text in their email.

The function fn:toUpperCase is used to convert all values in the target attribute to upper case. This result is then compared to the specified value MANAGER using the operator == to convert the resulting string into a Boolean value. The text is inserted into the message using an InsertIf statement, which is constructed as follows:

<%InsertIf expression="${((fn:toUpperCase(user.CustomAttribute['job title'])=='MANAGER'))}"%>Text<%/InsertIf%>

Structure

fn:toUpperCase(string)

Parameters

fn:trim

The function fn:trim removes leading and trailing white space, tabs, and linefeed characters from a string. The value returned is a string data type.

Example

The data imported from an older source had not been cleaned up and contained white spaces. The values must be cleaned up before being evaluated in an expression.

The data was imported to a member attribute named remarks. The function for removing the white space is constructed as follows:

${fn:trim(user.MemberAttribute['remarks'])}

Structure

fn:trim(string)

Parameters

ecx:capitalizeFirstLetter

The function ecx:capitalizeFirstLetter converts the first letter of a string to upper case. The value returned is a string data type.

Example

Today's date, including the day of the week, is inserted into a message. The day of the week appears as the first word in the phrase and must be capitalized. This element is not capitalized by default in French.

The function ecx:formatDate formats the date in French, and ecx:capitalizeFirstLetter corrects the capitalization. The expression that inserts the result into a message is constructed as follows:

<%${ecx:capitalizeFirstLetter(ecx:formatDate(date.Today, 'EEEE d MMMMM yyyy', ecm:timeZone('Europe/London'), 'fr', true))}%>

Structure

ecx:capitalizeFirstLetter(string)

Parameters

ecx:capitalizeWords

The function ecx:capitalizeWords converts the first letter of every word in a string to upper case. The value returned is a string data type.

Example

The customer's last travel destination is stored in a custom attribute. This value is stored in lower-case text. To use this value in a message, the text string must be formatted correctly. The function ecx:capitalizeFirstLetter does not correct the capitalization for city names with more than one word, for example, San Diego.

The following example uses the ecx:capitalizeWords function to format the city names and insert them in a message:

<%${ecx:capitalizeWords(user.CustomAttribute['Last Destination'])}%>

Structure

ecx:capitalizeWords(string)

Parameters

ecm:concat

The function ecm:concat concatenates the specified string values. The value returned is a string data type.

Example

Values stored in a group attribute represent prices for accommodations in various cities. Prices are saved as fractional numbers to two decimal places. When the price of a hotel in London is inserted into a message, the decimal values are replaced with a dash and preceded by the pound sign (i.e. 255.85 is converted to £255.-). The function fn:substringBefore extracts the value before the decimal point from the attribute Rate_London as follows:

${fn:substringBefore(group.CustomAttribute['Rate_London'], '.')}

The currency symbol and dash are added to the result using the function ecm:concat. The expression for adding the special characters and inserting the extracted value into a message is constructed as follows:

<%${ecm:concat('£', fn:substringBefore(group.CustomAttribute['Rate_London'], '.'), '.-')}%>

Structure

ecm:concat(string...)

Parameters

ecm:urlEncode

The function ecm:urlEncode encodes the specified object for use in a URL. Spaces and special characters in the value are converted so that they do not break the link. The value returned is a string data type.

Example

A registration link passes the last name of the recipient to the registration page. URL encoding ensures that last names with spaces (de la Hoya) or special characters (Nuñez) do not break the link:

<a href="https://www.example.com/register?name=<%${ecm:urlEncode(user['LastName'])}%>">Register</a>

To encode the value with a specific character set, use ecm:urlEncodeUsingCharset.

Structure

ecm:urlEncode(object)

Parameters

ecm:urlEncodeUsingCharset

The function ecm:urlEncodeUsingCharset encodes the specified object for use in a URL, using the specified character set. The value returned is a string data type.

Example

A registration link is included in a message that takes the information stored in the recipient attribute user['LastName'] and passes it as a variable to the registration page. The message itself is encoded using the ISO-8859-15 character set.

URL encoding ensures that last names with spaces (de la Hoya, van der Waal) or special characters (Nuñez, Köhl) do not break the link.

The HTML for inserting the link in a message is constructed as follows:

<a href="https://www.example.com/register?name=<%${ecm:urlEncodeUsingCharset(user['LastName'], 'ISO-8859-15')}%>">Register</a>

Structure

ecm:urlEncodeUsingCharset(object, string)

Parameters