JavaScript Access
You're currently viewing XMPL V3
Attention: XMPL V5 beta is now available!
When creating your webpage you may want to access the XMPL objects from your JavaScript code. You may want to access the XMPL services, which allow you to perform activities related to your XMPie campaign data, such as get the ADORs of a recipient, update their data and track activities. If you have an XMPL controller in your page you may want to access it as well.
If you are working with AngularJS, calling the services from your code is a simple matter of including the xmpResource service, which should be available once you include the basic XMPL javascript (xmp.min.js).
But if you are not programming AngularJS code, you may simply be looking to access the services from plain javascript. Or access the controller.
XMPL provides simple accessors for the XMPL services and controller, if one exists.
The accessors work even if you did not define an angular app or an XMPL controller in your webpage setup, but just included the (xmp.min.js) code, to enable you to use the XMPL services.
In the following section we will see how this works.
To get the services of XMPL, the xmpResource service, from plain JavaScript, just include the xmp.min.js and use the xmpResourceDriver class.
<script>
var xmplOnReady = function () {
var res = new xmpResourceDriver({ configuration: xmpcfg }, true, true);
res.ready(function () {
var inOptions = {
adors: ['firstName', 'lastName', 'Gender', 'Age'],
}
res.getRecipientADORs(res.recipientID, inOptions,
function (data) {
$('#txtArea').val(JSON.stringify(data))
}
);
});
}
</script>
....The first line creates a new instance of xmpResourceDriver. The first parameter is an object determining how to start up the underlying xmpResource object. In this case, a configuration object is passed holding a reference to xmpcfg which looks as follows (it's defined in another file):
{
access: {
accessToken: 'XXXXX',
url: 'YYYY',
}
}The url part is the address of the XMPL server that this service should work with, and the token identifies the project. You can get such an xmpcfg object from the Circle project page. Fore more information, refer to Getting Started.
Once you have an xmpResource object initialized you can use it as if it was an xmpResource object using the same interface. For example, the following grabs the ADOR values for 'Jane.Jones':
res.getRecipientADORs('Jane.Jones',
null,
function(data){
$('#txtArea').val(JSON.stringify(data))
});Fore more information about the 'getRecipientADORs' method, refer to xmpResource Reference.
The third parameter of the function is a callback that gets the recipient data returned for this recipient. It simply places it in the txtArea text area element as a value.
When using the services through JavaScript, the same rules apply as when using xmpResource. The first call should be a login call. You can either make the call yourself (either login call, or getRecipientADORs call), or let xmpResourceDriver do it for you. Simply pass true as the second parameter:
var res = new xmpResourceDriver({configuration:xmpcfg},true,true);Passing true as the second parameter executes login.
In this example, the third parameter is also used, passing the true parameter. In this case the login service will also decipher the recipient ID from the URL. Use it if you are using a similar method to the XMPL controllers, looking at the URL as the source for fetching the recipient ID. Per the earlier example, you can see that this is not mandatory, and you can use other means to determine the recipient ID.
However, if you do ask login to decipher the recipient ID, it will be later available as a member named recipientID.
Note that whether you run login or not, calls to the xmpResourceDriver after initialization should be made AFTER it is ready. This is usually not immediately after the instance is created (usually because the document needs to be ready, or the login call needs to be made). To overcome this, place the code in a callback to its ready function, as follows:
var res = new xmpResourceDriver({configuration:xmpcfg},true,true);
res.ready(function(){
// do something with res.
});To do all this you don't have to go through all the page setup normally done for XMPL pages. Simply include the library javascript, and have a project set up in Circle (so you'll have the xmpcfg configuration) and that's it. No ng-app and no ng-controller.
We will now move on to a case where you have an XMPL page and you want to access the services from your plain (non-angular) JavaScript code. In this case there's a bit of work to do. You will be using the same xmpResourceDriver class, but the initialization is slightly different, as you will want to share the xmpResource instance of the XMPL page. Add this code to your JavaScript code:
xmpApp.run(['$injector',function($injector)
{
var res = new xmpResourceDriver({injector:$injector})
}]);The run method is a handler of AngularJS applications that is executed when the application starts. It passes an injector object to the driver instead of the configuration file. Through the injector object the xmpResourceDriver asks for the instance of xmpResource of the application.
For AngularJS programmers, if you have your own application module, and you do not use the default one for XMPL, use it instead.
If you are not sure how to get the application object, then passing the element on which you placed the ng-app directive is just as good, and you can do it on the $(document).ready jQuery handler, as follows:
$(document).ready(function()
{
new xmpResourceDriver({element:$('[ng-app]')}).ready(/*..do something with it..*/);
....Depending on the desired usage, you will have to figure out what is best for you.
Also in these cases you can to run login and ask it to decipher the recipient ID based on the URL.
Let's say you have an XMPL page, and you have some JavaScript code that should access this controller for its xmp structure. The XMPL library provides a driver for the controllers, and you should be able to initialize it with a controller as follows:
new xmpControllerDriver(
$('[ng-controller="XMPPersonalizedPage"]')
).xmp.recipientIDSimple! Just pass the jQuery object on which the controller is set up, and you can use two valuable members:
-
xmp- the XMP data structure. -
scope- the controller AngularJS scope. You can use it to make calls to the controller methods.
It is important to note that you should run this type of code from $(document).ready or later, so that jQuery will already be loaded and functional.
From version 1.9.1 and above there are 2 new callback functions:
- angularComponenetsOnReady is a variable that will be used by a user who develop customized script and defined new directive, controller or new angular applicaton on top of xmp.app application, will be be fired once angular xmp.app modules are ready
- xmplOnReady is a variable that will be defined by a user who develop customized script, the function xmplOnReady will be fired once xmp.app directived and controllers are ready in the browser
##Example The following is a complete example of how this is done. The below code checks the gender ADOR and navigate accordingly.
Notice: ng-app should be on html tag (not on body tag) when using xmplOnReady()
index.html
<!DOCTYPE html>
<html ng-app="xmp.app">
<head>
<meta charset="utf-8">
<title>navigate</title>
*******all basic scripts should come here********
<script src="./js/navigate.js"></script>
</head>
<body ng-controller="XMPPersonalizedPage" xmp-cloak="true">
</body>
</html>navigate.js
//The function "xmplOnReady" is required
//from xmp.min.js version 1.9.1 and above
var xmplOnReady = function()
{
//on version 1.8 and below use-> $(document).ready(function() {
var xmpControllerDriverVar = new xmpControllerDriver($('[ng-controller="XMPPersonalizedPage"]'));
xmpControllerDriverVar.ready(function() {
if (xmpControllerDriverVar.xmp.recipientFailed == true)
window.location="pageError.html";
else
{
var resourceDriver = new xmpResourceDriver();
var inOptions= {adors: ['gender']};
resourceDriver.getRecipientADORs(xmpControllerDriverVar.xmp.recipientID, inOptions, function (data) {
if (data.gender == 'male')
window.location="page1.html";
else
window.location="page2.html";
}, null);
}
});
//}); //end $(document).ready
} //end xmplOnReady 
New!! Take a look at XMPL V5 Beta