Most commonly used directives

This quick overview describes the three most commonly used directives. For descriptions of all RPL directives, see Directive Reference.

if

With the if directive, you can conditionally skip a section of the template. For example, assume that you want to greet the boss, Big Joe, differently from other users:

<html>

<head>

  <title>Welcome!</title>

</head>

<body>

  <h1>

    Welcome ${profile.user}<#if profile.user == "Big Joe">, our beloved leader</#if>!

  </h1>

  <p>Our latest product:

  <a href="${latestProduct.url}">${latestProduct.name}</a>!

</body>

</html>

The example above instructs RPL that the '', our beloved leader'' should be used only if the value of the variable profile.user is equal to the string "Big Joe". In general, things between the <#if condition> and </#if> tags are skipped if the condition is false.

Let's look at the above example in detail:

== is an operator that tests whether the values at its left and right side are equivalent. The results is a boolean value true or false. On the left side of == we have referenced a variable with the syntax that should be already familiar; this will be replaced with the value of the variable. In general, unquoted words inside directives or interpolations are treated as references to variables. On the right side of ==, we specified a literal string. Literal strings in templates must always be enclosed in quotation marks.

IMPORTANT: In the example, ${profile.user} is used outside of the if directive, and profile.user inside of the if directive. ${user} is needed since we are in the HTML context and the ${…}construct indicates the beginning of RPL instructions. When inside the if statement, we are already inside an RPL context; therefore, RPL will treat the code as instructions and the ${…} is not needed.

Assuming the price of pythons is 0, the following example:

<#if animals.python.price == 0>

  Pythons are free today!

</#if>

produces this output:

Pythons are free today!

In this example, a number is specified directly. Note that the number is not enclosed in quotes; if it was, RPL would misinterpret it as a string.

To check whether the values are not equivalent, use the != operator. For example, if the price of pythons is not 0, the following code:

<#if animals.python.price != 0>

  Pythons are not free today!

</#if>

produces this output:

Pythons are not free today!

You can use the < operator to compare values. For example:

<#if animals.python.price < animals.elephant.price>

  Pythons are cheaper than elephants today.

</#if>

You can use the <#else> tag to specify what to do if the condition is false. For example, the following code:

<#if animals.python.price < animals.elephant.price>

  Pythons are cheaper than elephants today.

<#else>

  Pythons are not cheaper than elephants today.

</#if>

If the price of python is less than the price of elephant, the example will print Pythons are cheaper than elephants today. Otherwise, it will print Pythons are not cheaper than elephants today.

If a variable has a boolean value (true/false), you can use it directly as the condition of if:

<#if animals.python.protected>

  Warning! Pythons are protected animals!

</#if>

list

The list directive is useful when you want to list something. For example, merging this template with the data model we used earlier to demonstrate sequences:

<p>We have these animals:

<table border=1>

  <tr><th>Name<th>Price

  <#list animals as being>

  <tr><td>${being.name}<td>${being.price} Euros

  </#list>

</table>

produces this output:

<p>We have these animals:

<table border=1>

  <tr><th>Name<th>Price

  <tr><td>mouse<td>50 Euros

  <tr><td>elephant<td>5000 Euros

  <tr><td>python<td>4999 Euros

</table>

The generic format of the list directive is:

<#list sequence as loopVariable>repeatThis</#list>

The repeatThis part will be repeated for each item in the sequence, one after the other, starting from the first item. In all repetitions loopVariable will hold the value of the current item. This variable exists only between the <#list ...> and </#list> tags.

As another example, we list the fruits of the example data model:

<p>And BTW we have these fruits:

<ul>

<#list whatnot.fruits as fruit>

 <li>${fruit}

</#list>

<ul>

The whatnot.fruits expression references a variable in the data model.

include

You can use the include directive to insert the content of another file into the template.

For example, you have to show the same copyright notice on several pages. You can create a file that contains only the copyright notice, and insert that file anywhere you need the copyright notice.

The copyright file shown below is called copyright_footer.html and it is stored in cms://contentlibrary/common:

<hr>

<i>

Copyright (c) 2000 <a href="http://www.acmee.com">Acmee Inc</a>,

<br>

All Rights Reserved.

</i>

use the following code to include the copyright notice in your template:

<html>

<head>

  <title>Test page</title>

</head>

<body>

  <h1>Test page</h1>

  <p>Content...

<#include "cms://contentlibrary/common/copyright_footer.html">

</body>

</html>

and the output will be:

<html>

<head>

  <title>Test page</title>

</head>

<body>

  <h1>Test page</h1>

  <p>Content...

<hr>

<i>

Copyright (c) 2000 <a href="http://www.acmee.com">Acmee Inc</a>,

<br>

All Rights Reserved.

</i>

</body>

</html>

If you change the copyright_footer.htm , the new copyright notice will appear on all pages produced with this template.

For more information about the include directive, see Directive Reference.

data

Use the data directive to obtain data from additional tables by querying the database.

Usually, personalization data is automatically added to the template. However, data from additional tables used for personalization is not automatically included, since obtaining it requires additional criteria. Before using the data directive, you need to set up datasources in the system by including them in the campaign. When you include a datasource into a campaign, you need to give aliases for the datasource and its columns. You also need to identify which columns are used as lookup keys (i.e. the columns used to specify the criteria for the data to be returned). Interact is declarative in this respect. RPL uses only the aliases, and performs a full check as follows:

If a field is used as a lookup key in the filter section of the data directive, RPL checks the definition of the campaign to ensure that the field was declared as such. Failure to do that will result in an error.

If a field is used as a returned field in the fields section, RPL checks the definition of the campaign to ensure that the field was declared in the campaign with the given alias.

The examples in this section assume that you have created the aliases.

Example

To obtain data, you specify a data element with its three parts: the data specification, the filter specification, and the returned fields specification as shown in the following example:

These items are on sale right now!

<table>

<tr><th>Item</th><th>Total</th></tr>

<#data orders as order>

  <#filter custid=profile.custId>

  <#fields orderId product_quantity unitPrice >

    <tr id=”sale${order.orderId}”>

      <td>${order.product}</td>

      <td>${order.unitPrice * order.quantity}</td>

    </tr>

</#data>

</table>

The sections in the example are as follows:

The data declaration section (highlighted in blue in the example)

Specifies the structural nature of the request for data, including the datasource being used, the filter, and the fields being returned.

The declaration of the looping variable (shown in purple in the example)

Specifies the namespace hash being created, with the requested fields, as the source for each one of the records returned from the inquiry. The looping section can refer to this namespace to obtain the required fields, as shown in the section highlighted in yellow.

The looping section (highlighted in yellow in the example)

This section is repeated for each record obtained.

This section uses the namespace and the fields as specified in the fields declaration section. These are interpolations (${…}, but they could also be used in any other valid expression. The offer namespace hash is updated once for each iteration, with the data as present in each record from the given datasource.

The following table shows a database table called SALES, with the fields by which the table is indexed marked with an *.

ID*	CUSTID*	PRODUCT*	QUANTITY	UNIT_PRICE
1	0001	Paylesss Shoes – Size 13	1	25.99
2	0001	Gucci Sunglasses	2	229.99
3	0002	Coach Handbag	1	349.99
4	0003	Coach Handbag	2	349.99
5	0003	Giants Classic Cap	3	45.99

You can set up the datasources as follows:

Database/Field	Alias	Lookup
SALES database	orders
ID field	orderId	No
CUSTID field	custid	No
PRODUCT field	product	Yes
QUANTITY field	quantity	No
UNIT_PRICE field	unitPrice	No

If the profile.custId is "0001", the result of the previous example will be:

<table>

<tr><th>Item</th><th>Total</th></tr>

    <tr id=”sale1”>

      <td>Payless Shoes – Size 13</td>

      <td>25.99</td>

    </tr>

    <tr id=”sale1”>

      <td> Gucci Sunglasses </td>

      <td>459.98</td>

    </tr>

</table>

content

NOTE: To use the content directive, your account needs to be configured for its use. Please request access from your account representative.

In most cases, you add the contents of the message directly as HTML in the template. However, sometimes you need to create content dynamically, based on conditions in the recipient record. For instance, you might want to insert products based on location, or offers in nearby stores.

This type of content is usually defined by specific schemas that provide a structure that breaks down the content into consumable pieces and meta data (e.g. product name, description, images, price, size, etc.) The content directive is used for such situations.

While the data directive is useful for content has a lot of variance, the content directive is more suitable for content that repeats across multiple recipients. For example, if you launch a campaign with a million recipients, the data directive results in a million queries for the content. However, the content might have only 100 variations. The content directive is useful in this example as it automatically caches the results, resulting in 100 queries. In addition, the content directive allows for greater-than/less-than semantics useful for dates.

To use the content directive, the content must be loaded into Oracle Responsys in supplemental tables. After the content is uploaded and available in the system, a data source must be declared in the Campaign Workbook. You should declare the datasource with a unique alias that will be used to refer to the content in the content directive. Each field that will be used in a filter query should also be declared and aliased.

In addition to the efficiency on low variants, the content directive helps you with image paths. If your assets are hosted in the Oracle Responsys Content Library and you include the path to that asset in your content structure (with “/contentlibrary/” as the root folder), Oracle Responsys will automatically replace the image path and make the asset available on the content delivery network so it can be accessed from the external internet at launch.

For example, the following database of events across the United States. The data will be stored in a supplemental table called US_EVENTS.

EVENT_ID	DESCRIPTION	CATEGORY	VENUE_ NAME	REGION	DATE_ LOCAL
1	Eagles in concert	CONCERT	HP Pavillion	Bay Area	4/10/16 0:00
2	Knicks vs. Golden State	NBA	Oracle Arena	Bay Area	9/14/16 0:00
3	The Wizard of Oz	THEATRE	Eugene O'Neill Theatre	New York	5/30/16 0:00
4	Red Wings vs. Canucks	NHL	Rogers Arena	Toronto	8/10/16 0:00
5	Lakers vs. Golden State	NBA	Oracle Arena	Bay Area	5/5/16 0:00
6	Trailblazers vs. Kings	NBA	Sleep Train Arena	Bay Area	6/17/16 0:00
7	Cardinals vs. Giants	MLB	AT&T Park	Bay Area	6/1/16 18:00
8	Angels vs. As	MLB	Oracle Coliseum	Bay Area	6/3/16 19:30
9	Cardinals vs. Braves	MLB	Busch Stadium	Central	11/3/16 0:00

And the datasource is declared as follows:

Database/Field	Alias	Lookup
US_EVENTS	Events
DESCRIPTION	DESCR
CATEGORY	CATEGORY	Yes
VENUE_NAME	VENUE
REGION	EVENT_REGION	Yes
DATE_LOCAL	DATE	Yes

The content directive can then be used to retrieve content as follows:

<#assign today=.today>

<#assign next_week=dayadd(today,7)>

<table>

<tr><th>Description</th><th>Venue</th><th>Date</th></tr>

<#content Events as event>

  <#filter CATEGORY="MLB" && EVENT_REGION=PROFILE.REGION && DATE gte today && DATE lt next_week>

<tr><td>${event.DESCR}</td><td>${event.VENUE}</td><td>${event.DATE}</td></tr>

</#content >

</table>

The result of the previous example produces at most 3 events in the user’s region.

NOTES: If paths are used in the content table with prefixes that begin with the string /contentlibrary/, they will be translated to the externally available URL (CDN) path.

Note the use of the special variable .today in the example. This produces the time of today at midnight. If you use.now instead, the query will not be cached as each invocation of .now results in a different date and time.

As shown in the example, the content directive is composed of three parts:

The content declaration (highlighted in blue in the example)

This section is defined by the <#content directive and its options, and the <#filter sub-directive. It defines the data source to use and the filter to run.

The declaration of the namespace for the loop (shown in purple in the example)

This declaration identifies the hash that will be used to return the data from each row of the content. Note that in addition of the hash, two other fields are defined:

ns_has_next
Boolean value, defines if there are more rows in the namespace.

ns_index
Numeric value, identifies the row number for each content.

The name of these additional variables is composed of the namespace (shown as ns above) indicated in the <#content directive (event in the example), with the suffixes indicated.

In the example, the variables will be event_has_next and event_index.

The loop (highlighted in yellow in the example).

This loop is executed once for every row.

If the loop encounters a break directive, the looping will end.

The example, based on the filter criteria, produces the following output:

Cardinals vs. Giants	MLB	AT&T Park	Bay Area	6/1/16 18:00
Angels vs. As	MLB	Oracle Coliseum	Bay Area	6/3/16 19:30

<table>

<tr><th>Description</th><th>Venue</th><th>Date</th></tr>

<tr><td>Cardinals vs. Giants</td><td>AT&T Park</td><td>6/1/16 18:00:00</td></tr>

<tr><td>Angels vs. As</td><td>Oracle Coliseum</td><td>6/3/16 19:30:00</td></tr>

</table>

Next steps

Using directives together

Learn more

Defining your own directives

Directive Reference

Most commonly used directives

if

list

include

data

content

EVENT_ID

DESCRIPTION

CATEGORY

VENUE_NAME

REGION

DATE_LOCAL

Database/Field

Alias

Lookup

Next steps

Learn more

VENUE_
NAME

DATE_
LOCAL