XMPL Library Infrastructure

You're currently viewing XMPL V3

Attention: XMPL V5 beta is now available!

This entry discusses two elements of a personalized site that are required for its setup:

• the XMPL library
• the xmpcfg.js configuration file

There's a little bit of AngularJS talk here. It is perfectly fine if you don't understand it. AngularJS details are given to those who are familiar with this system and may want to use some of its elements independently.

XMPL Library

The XMPL library is comprised of the following files:

1. xmp.min.js / xmp.clean.min.js - a Javascript file defining the custom HTML tags and attributes, as well as page controllers and services to be used by the library. The .clean. version of the file does not include AngularJS source code, in case that you are using Angular independently in your site.
2. xmp.css - a stylesheet definition file setting up appearance for some of the tags defined by xmp.min.js.
3. An images folder - used by xmp.css and xmp.min.js for implementation of several tags.

The main file here is xmp.min.js. It defines three AngularJS modules that provide the XMPL solution:

1. xmp.services - defines xmpResource. An AngaulrJS service that implements the connection to the XMPL server for performing all personalization-related activities - fetching data, adding and updating recipient data, tracking, and so forth. The service can be preconfigured to connect to a single campaign/project. However, any method in the service can also accept connectivity information, to allow the use of multiple campaign data in the same page (or at least, avoid the preconfiguration).
2. xmp.controllers - defines two controller types:
   • XMPPersonalizedPage is a controller for a page that is loaded personalized. The personalization is either based on a landing page URL which contains the recipient ID, or the recipient ID was passed by cookies (handled by the controller) to other pages.
   • XMPAnonymousPage is a controller for a page that is not initially personalized. Personalization may take place later by way of submitting a registration form that is built on top of it, or by programmatic means.
     Both controllers lay the infrastructure for loading and saving recipient data, and sharing this data with the HTML elements and attributes (directives) that are resident inside their controlled area. For example, XMPPersonalizedPage controller, when loaded, collects all ADOR names that are used in the page, and requests their values, based on the recipient ID defined via the page browser URL.
3. xmp.directives - defines many multiple directives - custom elements and attributes - that you can add to your webpage for the sake of personalization. For the person not so savvy with AngularJS, these are the primary tools for personalization. The directives share with the container XMPie controllers the recipient data to minimize data access efforts and therefore go together with it (meaning they are mostly meaningless outside its scope).

In addition to the three main modules, the xmp.min.js code also includes:

1. xmp.app - the default application to be used in the ng-app tag. The application makes the XMPL three modules available to the HTML page and javascript code. In addition it preconfigures the xmpResource module with the connection data defined by the xmpcfg.js file. If you are familiar with AngularJS, you may define your own application. If doing so, then to expose all XMPL functionality include the three modules. In addition, you should configure the xmpResource service with the XMPL connection data.
2. xmpResourceDriver and xmpControllerDriver javascript classes - these classes are intended for use if you want to access the XMPie functionality from plain javascript (non AngularJS). They define some convenient methods for accessing the services layer, and methods for accessing XMPie controller data.

The xmpcfg.js File

The file downloaded from a Circle project contains a javascript definition of the connection data to the Circle project (and through it to the uProduce campaign supporting it). A typical xmpcfg.js file looks like this:

var xmpcfg = {
	access: { 
		accessToken: 'A KEY', 
		url: 'A URL'
	}
};

(Other keys may be defined under access, they are irrelevant to the functionality of the library).

The file defines an xmpcfg object with a single 'access' key. In it there are two keys:

• accessToken - An identifier of the Circle project for the XMPL server to use in order to identify this project/campaign out of the available projects/campaigns.
• url - The URL of the XMPL server to use for this webpage.

For AngularJS users, especially if you define your own ng-app application, you should use this data (or the likes of it) to connect to the XMPL server. This data may be preconfigured on the xmpResource service using a .config statement:

myApp.config(['xmpResourceProvider', function(inProvider) {
    inProvider.configure({
      access:xmpcfg.access
    });
}])

This will set up default configuration for xmpResource service. While you can still call the various service methods with different access data, you should know that this will serve as the default in the case that you don't. The XMPie controllers defined in xmp.controllers assume that xmpResoruce is preconfigured and don't pass additional access data when using its methods.