Webpage Personalization

You're currently viewing XMPL V3

Attention: XMPL V5 beta is now available!

Assuming you have a project set up with a plan, that plan defines a list of ADORs. These ADORs are the variables that can be used in a webpage in order to personalize it.
In this section we will review all ADOR types that can be placed in a webpage, and how to place them.

As an example we will use the "index.html" webpage of the SDK "Sample Site" . If you want to install it, follow the steps in Getting Started using the "Sample Campaign" materials as the project materials and the SDK "Sample Site" folder as the site folder.

Setup

To set up a webpage for personalization, there are initial items that need to be taken care of. We'll quickly review them here. For more information, go to Your First Personalized Page.

A webpage that has been set up looks like this:

<!doctype html>
<html lang="en" ng-app="xmp.app">
<head>
	<meta charset="utf-8">
	<title>Sample Recipient Page</title>
	<link href="https://ajax.xmcircle.com/ajax/libs/xmpl/3.1.4/xmp/css/xmp.css" rel="stylesheet" media="screen">
	<link href="./css/main.css" rel="stylesheet" media="screen">
</head>
<body>
	<div ng-controller="XMPPersonalizedPage" xmp-cloak>
        .....
        </div>
  	<script src="https://code.jquery.com/jquery-3.4.1.min.js"></script>
        <script src="https://ajax.xmcircle.com/ajax/libs/xmpl/3.1.4/xmp/js/xmp.min.js"></script>
	<script src="./xmpcfg.js"></script>
</body>
</html>

The following lists the steps for setting up personalization:

In the html tag there is an ng-app attribute. It should be set up with the value of xmp.app
In head there is a link to the xmp.css file. It is required for styling some elements of the XMPL library.
In body at the bottom there are script references
- jQuery - required for XMPL
- xmp.min.js - XMPL library code
- xmpcfg.js - defines connection info for XMPL

In addition, all content that uses ADORs should be surrounded by a single element (in this example a div, but it can also be the body or some other element), that has the attribute of ng-controller. In this case we are using XMPPersonalizedPage as the value of the controller, to note that this page loads recipient ADORs as it loads, according to the recipient ID marked at the page URL (rid=XXXXX).

Also, the xmp-cloak attribute is used. This causes the page to appear blank until data is fetched. It is good practice to use it so the page doesn't flicker with the template elements prior to having the correct data.

Adding ADORs

All personalized information should be placed in tags inside the main tag containing the ng-controller definition.

Variable Text

To place the text of an ADOR, simply refer to it from inside curly brackets:

<div>{{xmp.r['First Name']}}</div>
<div>hello {{xmp.r['First Name']}} {{xmp.r['Last Name']}}</div>

In the first div the text is completely set by the value of First Name ADOR. Note that the ADOR name is written as a key inside an xmp.r object. The xmp.r object contains all values retrieved for the recipient. With xmp.r[XXXXX] we're simply taking the XXXXX ADOR value for the recipient.

Note that you can do this for all ADORs, not just text ADORs. In addition, you can do it not only as part of an ADOR text, but also as the value of an attribute.

Variable Images

Variable images can either come from the uProduce server, as assets, or reside on the website. Consider the following HTML snippet:

<!-- fetching an asset from the server -->
<img xmp-image-asset="xmp.r['MyImage']"/>
<!-- fetching an asset from the site images folder, using the ADOR to determine the value -->
<img xmp-src="images/{{xmp.r['Image2']}}"/>

In the first img tag the attribute xmp-image-asset is used. Its value is an ADOR reference (note the lack of curly brackets). When evaluated, the asset with the value of the ADOR MainImage for the recipient will be placed as the source of the image.

The second example shows a variable image using local site images. The src attribute of the image is set to the image in the images folder, whose name is stored in the value of Image2 ADOR. You can use either src, xmp-src or ng-src to get more or less the same effect (the last two wait to set src only when the attribute value is non empty). This is a good example of using the literal value as input for an attribute of an element, as was explained for text ADORs. It is quite meaningless that this ADOR is image, as it could well be a text ADOR.

Variable Text Files

You can define text files in uProduce as assets, to provide variable text, as an alternative to using text ADORs. Then define text file ADORs to refer to them. To use text file ADORs in a webpage use the xmp-text-asset attribute, as in the following example:

<div xmp-text-asset="xmp.r['Introduction']"></div>

In this example the value of Introduction ADOR is a reference to a text file asset. When used with xmp-text-asset, the file is fetched and its content (either text or HTML) is used as the content of the tag using the attribute.

Variable Style

Using variable style you can determine a different appearance (e.g, color, font) for content. Define a collection of classes and for each recipient have the ADOR value match one of the classes. Then, to set up particular elements to be affected by variable style, use the xmp-class attribute as follows:

<div xmp-class="xmp.r['Theme']">what's up?</div>

It is also possible to use a regular class attribute, however it must be used with curly brackets, so that the literal value is fetched:

<div class="{{xmp.r['Theme']}}">now with regular class</div>

For AngularJS aficionados, using xmp-class is equivalent to using ng-class and has the same advanced features, such as conditional class placements.

Variable Visibility

With visibility ADORs you can turn on and off content in the webpage, according to what you wish to show to the particular recipient. Use the xmp-show attribute on an element, where the value is a visibility ADOR reference, to toggle its visibility per the ADOR value. For example:

<div xmp-show="xmp.r['IsStudent']">this text should be visible if isStudent is true</div>

Variable Links

Variable links can be simply implemented as literal ADOR placements ({{XXXX}}) on the href attribute. Alternatively, use an xmp-href attribute with reference to a link ADOR. For example:

<a xmp-href="{{xmp.r['Blog']}}">users blog</a>

The benefit of using xmp-href is equivalent to using ng-href, and is that both manipulate the href attribute to be set to a value only when the literal value is non null.

Variable Table

You can use a table ADOR in a webpage as a source for a multi-item list with xmp-repeat attribute. Consider the following example:

<ul class="no-list repeater">
    <li xmp-repeat="item in xmp.r['Courses']">
        <span class="{{xmp.r['Theme']}}">{{item['Name']}}</span>
        <span>{{item['Hours']}}</span>
    </li>
</ul>

The value of xmp.r['Courses'] is an array of objects, where each contains Name and Hours property. This is per the definition of the Courses ADOR in the project plan.
The result of the HTML definition is that for each row in the Courses ADOR value for this recipient there will be an li tag created (list item), which will contain two spans - one showing the Name ADOR value for this row, and the other showing the Hours ADOR value. Note that for the span containing Name ADOR value there is a class attribute whose value is set by the Theme ADOR value, which is a plan non-table style ADOR.

To refer to the table columns, the item prefix is used instead of xmp.r, which is used for the recipient value. This is achieved by using item in the xmp-repeat attribute of the li item, which formulates the repeat functionality.