Skip to content

Cheat Sheet for Web

Jump to bottom
Batyah Rubin edited this page Jun 12, 2023 · 104 revisions

You're currently viewing XMPL V3

Attention: XMPL V5 beta is now available!

This page is intended for developers who are familiar with the XMPL language. This page acts as a quick reminder for the website creation workflow, and as a source for code snippets which can be easily copied and pasted. Note that XMPL is built on top of AngularJS 1.3, and therefore AngularJS documentation also applies.

Download the Config File

  1. In Circle, open the project that you wish to connect to.
  2. Download the XMPL configuration file for the project: Build > Library > Website > Configuration file. The downloaded file name should be xmpcfg.js.
  3. Copy it to the root folder of your website.

Head

Add the following references to the jQuery javascript file, the XMPL library javascript and CSS files, and the configuration file:

<head>
        <!-- XMPie XMPL library -->
        <link href="https://ajax.xmcircle.com/ajax/libs/xmpl/3.1.4/xmp/css/xmp.css" rel="stylesheet" media="screen">
        <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>
</head>

Body or div

Add the following attributes to the body or div tag of the section that needs to be personalized. Landing pages (the page you link to with the recipient ID):

<body ng-app="xmp.app" 
      ng-controller="XMPPersonalizedPage" 
      xmp-cloak
      xmp-clear-all-cookies-onload
      xmp-tracking-page-name="Landing">
YOUR PERSONAL CONTENT HERE
</body>

Internal pages:

<body ng-app="xmp.app" 
      ng-controller="XMPPersonalizedPage" 
      xmp-cloak
      xmp-tracking-page-name="PageName">
YOUR PERSONAL CONTENT HERE
</body>

Note: The value of xmp-tracking-page-name can include the numbers 0–9, the letters A–Z (both uppercase and lowercase, English only), hyphens (-), underscores (_) and spaces. Special characters are not allowed.

To use a custom failure page add xmp-failure-url="error.html" to the list of attributes, where error.html is your failure page.

ADORs

Text

There are three ways of representing an ADOR. The third notation can be used only if the ADOR name consists only of alpha numeric ascii characters.

{{xmp.r['My TextAdor']}}
{{xmp.r["My TextAdor"]}}
{{xmp.r.MyTextAdor}}

XMPieRecipientKey ADOR

{{xmp.r.XMPieRecipientKey}}

Graphic (Image)

Using assets:

<img xmp-image-asset="xmp.r.MyAdor"/>

Using website images with Text ADORs; or uImage Graphic ADORs:

<img ng-src="images/{{xmp.r.MyAdor}}"/>

Style

When the ADOR value is the class name:

<span xmp-class="xmp.r.MyStyle"> Your Text Here </span>

In this case also ensure to add all possible ADOR values as class definitions in your site's CSS.

Use of expression to determine the class name:

<span 
xmp-class="{'gold':xmp.r.Member=='Gold', 'plain':xmp.r.Member!='Gold'}"> 
Your Text Here </span>

In this case also ensure to add the class options to your site CSS.

Visibility

Show a tag only if the expression is true:

<div xmp-show="xmp.r.Membership=='Gold'">
:
</div>

Link

Create a link to an address supplied by an ADOR.

<a xmp-href="{{xmp.r['Blog']}}"> xmp-tracking-action="Blog">Go to my blog</a>
<a xmp-href="{{xmp.r['Suppliers']}}" xmp-tracking-action="List of Suppliers:CTA">List of Suppliers</a>

Note that clicks of links and buttons can be tracked in Circle Analytics by adding the xmp-tracking-action="" parameter to the tag. If your page has many links and buttons to track, you can add ":CTA" to the end of the action name on the button or link which is the page's main Call To Action. In Circle Analytics you can then choose to report on clicks of all page links, or on only the main Call To Action.

PDF on Demand

Create a link to a PDF on Demand touchpoint. The PDF on Demand shows the data available at the time the link in the webpage was clicked.

<a xmp-href="{{xmp.r['XMPie.PDF.P1']}}">View the PDF</a>
<a xmp-href="{{xmp.r['XMPie.PDF.P2']}}">Get your coupons</a>
<a xmp-href="{{xmp.r['XMPie.PDF.P3']}}" xmp-tracking-action="Get your ticket:CTA" target="_blank">Get your ticket</a>

Table ADOR

<table>
   <tr>
	<th>First Name</th>
	<th>Last Name</th> 
   </tr>
   <tr xmp-repeat="Department in xmp.r.Departments">
 	<td>{{Department.FirstName}}</td>
	<td>{{Department.LastName}}</td>
   </tr>
</table>

Or

<ul>
    <li xmp-repeat="item in xmp.r['Fuel Consumption']">
        {{item.Date}}:  {{item.Liter}} Liters                       
    </li>
</ul>

Website Referral Source and Media Parameters

Circle Web analytics can be enhanced by tracking the source which referred traffic to the website, so that you can assess which of your campaign touchpoints, or media performed best. For example, the source could be the touchpoint from which the web URL is clicked in order to arrive at the website (e.g., E1-Invitation), and the media is the type of touchpoint media (email, SMS, webpage, social media, print document's QR Code).

Tracking the media and source of the website visit is achieve by using URL parameters: xmpmedia for the media type and xmpsrc for the name.

If you have PersonalEffect 10.2 or later, you can use Special Web ADORs that are created automatically and will include referral tracking parameters in the web URL by default. Alternatively, you can manually add parameters to the URL.

Examples:

https://mycompanydomain.com/mycampaign/MyRecipientKey?xmpmedia=SocialMedia&xmpsrc=Facebook
https://mycompanydomain.com/mycampaign/index.html?rid=MyRecipientKey&xmpmedia=Web&xmpsrc=CompanySite
https://mycompanydomain.com/mycampaign?xmpsrc=E1

For more information about Web Analytics and the referral source and media parameters, refer to Web Analytics.

Update

	<form xmp-update>
          First Name: <input type="text" xmp-write-ador="xmp.r.Fname"><br/>
          <input type="checkbox" xmp-write-ador="xmp.r.Gift" 
          xmp-true-value="SendGift" xmp-false-value="DontSendGift"> Send me my gift card. <br>
          Model:  
			<select name="singleSelect" xmp-write-ador="xmp.r.MyAdor">
			  <option value="Defender">Defender</option>
			  <option value="Discovery">Discovery</option>
			  <option value="Evoque">Evoque</option>
			</select>
		<input class="btn-primary" type="submit" 
                       value="save" xmp-success-url="thanks.html" xmp-tracking-action="form submitted:CTA">
	</form>

Radio buttons get a slightly different form:

	<input type="radio" value="Sports"  xmp-write-ador="xmp.r.MyAdor">Sports <br/>
	<input type="radio" value="Pickup"  xmp-write-ador="xmp.r.MyAdor">Pickup <br/>
	<input type="radio" value="Antique"  xmp-write-ador="xmp.r.MyAdor">Antique <br/>

Self Registration (GURL)

The self registration requires an XMPAnonymous controller:

<body ng-app="xmp.app"
      ng-controller="XMPAnonymousPage"
      xmp-cloak>

And the form is as follows:

	<form xmp-register>
		First Name: <input type="text" xmp-write-ador="xmp.r.Fname">
		<input class="btn-primary" type="submit" 
                       value="save" xmp-success-url="thanks.html">
	</form>

In a GURL, the second time the form is used (on the same browser), to make sure the form is cleared of the previous data, add the forgetRecipient() function to the submit button. In this way the previous values in the form are cleared, and the form functions as a GURL each time:

        <form xmp-register xmp-success-url="index.html">
            <ul>
                <li>
                    First Name : <input type="text" xmp-write-ador="xmp.r['First Name']"  size="30">
                </li>
                <li>
                    Last Name : <input type="text" xmp-write-ador="xmp.r['Last Name']"  size="30">
                </li>
            </ul>
            <input class="btn-primary" ng-click="forgetRecipient()" type="submit" value="save">
        </form>

Refer a Friend

	<form xmp-refer>
		First Name: <input type="text" 
                                   xmp-write-ador="xmp.referredRecipient.Fname">
		<input class="btn-primary" type="submit" 
                       value="save" xmp-success-url="thanks.html">
	</form>

Form Validation

It is common for a form to use validation. XMPL is based on Angular 1.3.0 and uses its validation technique. Below are example of usage of validation based on control state binding and on CSS. There are additional methods in the Angular documentation.

Add this to you CSS file.

		.error {
			color: red;
		}
		.css-form input.ng-invalid.ng-dirty {
			background-color: #FA787E; //red background
		}

		.css-form input.ng-valid.ng-dirty {
			background-color: #78FA89; //green background
		}

Note how the css and the various validations are integrated into the form.

    <form name="form" xmp-update novalidate class="css-form">
          First Name: <input type="text" xmp-write-ador="xmp.r.Fname" required ><br/>
		  Email: <input name="email" type="email" xmp-write-ador="xmp.r.Email" required><br/>
				<div class="error" ng-show="form.email.$dirty && form.email.$invalid">
				  <span ng-show="form.email.$error.required">Tell us your email.</span>
				  <span ng-show="form.email.$error.email">This is not a valid email.</span>
				</div>

        <input class="btn btn-default" type="submit"  ng-disabled="form.$invalid"
			value="save" xmp-success-url="thanks.html" xmp-tracking-action="form submitted:CTA">
    </form>

There are more form validation examples here: Form validation examples

Triggered Touchpoint

To trigger an email or external touchpoint on submitting a form, use xmp-success-trigger

<form xmp-update>
  Email: <input type="text" xmp-write-ador="xmp.r.Email"><br/>
  <input class="btn-primary" type="submit" 
      value="Update" xmp-tracking-action="form submitted:CTA" 
      xmp-success-trigger="E1">
</form>

To trigger a touchpoint on page load, use xmp-success-trigger

<body ng-app="xmp.app" 
      ng-controller="XMPPersonalizedPage" 
      xmp-cloak 
      xmp-tracking-page-name="Landing"
	  xmp-success-trigger="E3">

Note: The value of xmp-tracking-page-name can include the numbers 0–9, the letters A–Z (both uppercase and lowercase, English only), hyphens (-), underscores (_) and spaces. Special characters are not allowed.

To trigger a touchpoint on clicking a button, use xmp-clicked-trigger

<button xmp-clicked-trigger="E2">I Like! </button>

You can also trigger more than one touchpoint by separating them with a comma:

xmp-success-trigger="E1,E2,X1"
xmp-clicked-trigger="X3,X4"

Note: A prerequisite for external touchpoint is XMPL 3.1. In every webpage that uses an external touchpoint, make sure that the library references in the head tag refer to XMPL 3.1.

Deprecated directives

The following triggered email directives are deprecated from XMPL version 3.1, but will still function:

xmp-success-triggered-email xmp-clicked-triggered-email

For future projects, please use the new directives.

Method

To add a method, you can use angular controllers.

Add the script.

//The function "angularComponentsOnReady"  is required 
//from xmp.min.js version 1.9.1 and above
var angularComponentsOnReady = function() 
{
            //adding a controller to xmp.app
            var app = angular.module('xmp.app');
            app.controller('FuelCalc', function($scope) {

                //define a method
                $scope.fuelSum = function() {
                    var sum = 0;
                    angular.forEach($scope.xmp.r['Fuel Consumption'], 
                                    function(value,key) {
                                            sum = sum + Number(value.Liter);
                                    }); //for each
                    return sum;
                };

            }); //controller

} //end angularComponentsOnReady

Use the method in the body of the HTML.

<div ng-controller="FuelCalc">
       Your total consumption is {{fuelSum()}} Liters
</div>

User Authentication - SecURL

Sign-In

Sign-in allows the user to gain access to secured pages by providing a username and password.

<body ng-controller="XMPPersonalizedPage">
    
    <form xmp-signin xmp-success-url="index.html" xmp-failure-js="onError()">
        <ul>
            <li>
                Username : <input type="text" xmp-username>
            </li>
            <li>
                Password : <input type="password" xmp-password>
            </li>
        </ul>
        <input type="submit" value="Sign-In">
    </form> 

    <script>
        function onError(){
            var resposeData = window.XMPLLastHttpError.data;
            var errorCode = resposeData.ErrorCode;
            var displayMessage = resposeData.DisplayMessage;
            alert(displayMessage);
        }
    </script>
</body>

Sign-Out

Sign-out allows the user to sign out from his/her authentication session.

<input type="submit" value="Sign-Out"  xmp-signout>

Password Field in Registration Form

In order to mark an input as a password field in the Registration form, use the XMPie.Web.NewPassword fixed ADOR name. For example:

<form xmp-register>
    <input type="password" xmp-write-ador="xmp.r['XMPie.Web.NewPassword']"> 
</form>

Password Field in Update Form

You can allow the user to change his/her password after authentication. In order to mark an input as the new password field in the Update form, use the XMPie.Web.NewPassword fixed ADOR name. In order to mark an input as the existing password field in the Update form, use the XMPie.Web.ExistingPassword fixed ADOR name. For example:

<form xmp-update>
        <ul>
            <li>
                Username : <input type="text" xmp-write-ador="xmp.r['UsernameAdor']">
            </li>
            <li>
                Existing Password : <input type="password" xmp-write-ador="xmp.r['XMPie.Web.ExistingPassword']">
            </li>
            <li>
                New Password : <input type="password" xmp-write-ador="xmp.r['XMPie.Web.NewPassword']">
            </li>
        </ul>
        <input type="submit" value="Update">
</form>

Automatic Sign-In of New Registered User

On the Registration form you can set newly registered users to be automatically signed in using xmp-signin-auto="true". For example:

<form xmp-register xmp-signin-auto="true"></form>

Automatic Redirect to Login Page

You can set all personal pages to automatically redirect to the login page if the user is not authenticated.

  1. Create a file named xmpcustom.js in your site folder.
  2. In this file add a link (relative or absolute link) to login page in the following format:
var xmpcustom = {
  loginUrl: 'https://Domain/Site/login.html'
}
  1. In all personal pages add, the following link to xmpcustom.js:
<script src="xmpcustom.js" type="text/javascript"></script>

Confirm Password

In the Registration and Refer-a-friend forms you can add a confirm user password input, in which case the user will need to enter the password twice in order to register.

  1. Add the xmp-password attribute to the password input that is connected to the XMPie.Web.NewPassword write ADOR.
  2. Add the xmp-confirm-password attribute to the second input where the user will re-enter the password..
  3. In addition, add xmp-failure-js to set the error function. Example:
<input type="password" xmp-password xmp-write-ador="xmp.r['XMPie.Web.NewPassword']">
<input type="password" xmp-confirm-password xmp-failure-js="onConfirmError()">

Reset Browser to Current Recipient

Use one of the following options:

Option 1

Add xmp-clear-all-cookies-onload to the body tag. On page load, the current recipient will be reset.

<body ng-controller="XMPAnonymousPage" xmp-clear-all-cookies-onload >

Option 2

Add xmp-clear to the button. On button click, the current recipient will be reset.

<button xmp-clear>Clear</button>

Error Handling

To control the error display on your page use:

  1. XMPLLastHttpError – Includes the error code and the display message. For more details about XMPL error codes, refer to XMPL Rest API help. You can access the XMPL Rest API help from Circle > Library > Web area.
  2. xmp-prevent-default-error-handle – Prevents the default error page from being displayed when an error occurs.
<body ng-controller="XMPPersonalizedPage" xmp-prevent-default-error-handle>
...
<form xmp-update xmp-success-js="onSuccess()" xmp-failure-js="onError()">
...
<script>
    function onError(){
        var resposeData = window.XMPLLastHttpError.data;
        var errorCode = resposeData.ErrorCode;
        var displayMessage = resposeData.DisplayMessage;
        alert(displayMessage);
    }
</script>

Directive / Google Charts

Below is an explanation how to add a Google Chart directive. However, it explains how to add a directive in general.

Use a mychart directive attribute in the HTML code, that receives the table ADOR and three labels as parameters.

<div mychart  table="xmp.r['Fuel Consumption']" xlabel="Date" ylabel="Liter"></div>

Add the following script to the header:

        <!-- Google Charts-->
        <script type="text/javascript" src="https://www.google.com/jsapi"></script>

The javascript that defines the directive, in this case running Google Charts.

google.load('visualization', '1', {packages: ['corechart', 'bar']});

//The function "angularComponentsOnReady"  is required 
//from xmp.min.js version 1.9.1 and above
var angularComponentsOnReady = function() 
{
angular.module('xmp.app').directive('mychart', function() {
    function link(scope, element, attrs) {
        var chart = function (rawElement) {
            //extract the parameters from the tags
            var param = attrs['table'];
            var data =  eval("scope." + param);


            var table = [
                [attrs['xlabel'], attrs['ylabel']]
            ];
            angular.forEach(data, function (value, key) {
                var row = [ value.Date, Number(value.Liter)];
                table.push(row);
            });
            var data = google.visualization.arrayToDataTable(table);

            var options = {
                width: 400,
                height: 200,
                bars: 'horizontal' // Required for Material Bar Charts.
            };

            var chart = new google.visualization.BarChart(rawElement);
            chart.draw(data, options);
        }; //draw basics

        //this callback is called when the ADORs are populated
        scope.xmpReady(function () {
            var rawElement = element[0];
            chart(rawElement);
        });
    };

    return {
        link: link,
        restrict: 'A'
    };
}); //directive

} //end angularComponentsOnReady

Google Maps

To add Google Maps, you may want to use the open source project https://github.com/XMPieLab/XMPL-Maps

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

Search

XMPL V3

New!! Take a look at XMPL V5 Beta

Release Updates (22-Jan-2022)

Home

Cheat Sheet for Web

Cheat Sheet for Email

Deprecated

User Manual

Getting Started

Your First Personalized Page

Webpage Personalization

Updating Recipient Data

Adding New Recipients through Registration

Refer a Friend

Web Analytics

Social Media Tags

Corporate Website

JavaScript Access

XMPL Library Infrastructure

How Does it Work

PDF on Demand

Triggered Emails

Form Validation Examples

User Authentication (SecURL)

Error Handling

Clear Browser Cookies

Video

Browser Support

Reference

Markup Reference

xmpResource Reference

Clone this wiki locally