Your First Personalized Page

You're currently viewing XMPL V3

Attention: XMPL V5 beta is now available!

In this entry we will look into a basic personalized page. To set it up review the Getting Started entry. The webpage can be also found here.

The webpage displays a single image and text. The actual image and text displayed are determined by the rid parameter passed at the browser URL. Let's turn to the page source.

The HTML Tag

The HTML tag for the webpage looks like this:

<html lang="en" ng-app="xmp.app">

The HTML tag attribute 'ng-app' ties the page to the XMPie angular application 'xmp.app', allowing for the rest of the page to use the XMPie HTML tags.

For those familiar with AngularJS, 'xmp.app' is an application tying together the directives, controllers and services that the XMPie infrastructure provides.

Placing this attribute and value is mandatory for using XMPL, unless you are defining your own AngularJS application.

The Header

the header for the page looks like this:

<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">
</head>

The link tag in the header contains a reference to the XPML library CSS file - xmp.css. This file is used to assist some tags defined in the XMPL library, such as xmp-cloak and xmp-facebook-share. Including this link is required for the proper functionality of the library tags.

The Body

The body contains the template definition of the personalized site. Each recipient will view a different HTML page based on the PURL through which they get to the site.

Let's review the basic webpage body:

<body>
    <div ng-controller="XMPPersonalizedPage" xmp-cloak>
        <div>hello {{xmp.r['First Name']}} {{xmp.r['Last Name']}}</div>
        <div><img xmp-image-asset="xmp.r['MainImage']"/></div>
    </div>
.....

The Controller Tag

The topmost div element contains the attribute ng-controller with XMPPersonalizedPage as its value. The definition of ng-controller is mandatory for using the library. The library defines 2 possible values:

XMPPersonalizedPage - for personalized webpages where the personalization content is set up by the URL, which contains the recipient ID.
XMPAnonymousPage - for pages that may not contain personalization initially, but may at a later stage. An example to this is a registration page, where the webpage viewer is not initially a recipient, but only becomes one once the registration form is submitted.

In this example we are using XMPPersoanlizedPage, and in accordance the URL for accessing the webpage would be index.html?rid=XXXXX, where XXXXX stands for a recipient ID, e.g. index.html?rid=Jane.Jones

The ng-controller tag can be placed at the top-level element of the HTML body, or somewhere else. It should encapsulate any XMPL tags.

The div also defines another attribute xmp-cloak. This tag hides its content until the XMPie recipient data is ready. It is good practice to use it to hide any personalized content until it is ready.

Personalization

Actual personalization occurs in the contents of the topmost div:

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

Note the {{xmp.r['First Name']}} {{xmp.r['Last Name']}}. This form of writing retrieves the literal value of the respective ADOR for the recipient, in this example First Name and Last Name. As a result we will see hello Jane Jones, for example, if the recipient id is Jane.Jones.

You can use this form ({{xmp.r['ADOR_NAME']}}) with any ADOR to retrieve its literal value regardless of the ADOR type. It is most expected though, to be used with Text ADORs. It is perfectly OK to use it not just as HTML text, but also as attribute values.

the xmp.r prefix means that the ADOR value is read from the recipient data. Sometimes when we will look at recipient reference scenarios we'll see that values can be taken also from the referred recipient using another prefix.

The next div shows an image ADOR:

        <div><img xmp-image-asset="xmp.r['MainImage']"/></div>

The MainImage ADOR is used as the value of an xmp-image-asset attribute of an image. What this attribute does is take the asset matching the ADOR for the recipient and set it as the img tag source, providing a personalized image. This works only with Image ADORs.

You may, though, use the literal access method we saw earlier for text ADORs to set the src attribute of an image. This is useful if you want to show a different website image per the viewing recipient. As opposed to that, xmp-image-asset is used specifically for assets that are hosted on the uProduce server.

Scripts

The bottom of the body contains references to scripts used by the webpage:

    <script src="https://code.jquery.com/jquery-3.6.0.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>

The first link includes jQuery. Including jQuery is mandatory for using XMPL. The second link includes the XMPL javascript code. This script defines the directives (HTML tags and attributes), controllers and services that form XMPL.

The last link includes the xmpcfg.js file that we downloaded from circle. This file includes the connection data for the project. XMPL uses it to connect to the XMPL server, and fetch the particular project data.

You are done!

Continue to Webpage Personalization to learn about more options to personalize the webpage, or to XMPL Library Infrastructure to learn about what xmp.min.js includes and what is in the xmpcfg.js file.

You're currently viewing XMPL V3. Alternatively, go to XMPL V5 beta.