Markup Reference
You're currently viewing XMPL V3
Attention: XMPL V5 beta is now available!
The following provides a full reference for all markup that you can add to your webpage when including XMPL.
Setup related attributes. For more information on setting up an XMPL page, refer to Your First Personalized Page.
ng-app attribute marks the angular application. It should be placed on the topmost element that includes the angular application, e.g. the HTML or BODY tags. To use the default XMPL application, it's value should be xmp.app
ng-controller attribute marks the controller that implements the element behavior, where the element is the one on which the attribute is placed. Two possible controllers are available with XMPL:
-
XMPPersonalizedPage, which implements a personalized webpage. It identifies the recipient based on the page URL or cookies, and fetches ADORs during page load. -
XMPAnonymousPage, which implements an anonymous webpage. The page visitor is not an existing recipient. The page will usually contain a registration form to allow the adding more recipients.
Using double curly brackets as an attribute value, or in text content, will be translated to the value of the expression that is between the brackets. For Example, {{xmp.r['First Name']}}, will be translated to the value of the First Name ADOR for the viewing recipient.
The xmp-src attribute can be used in an img element to declare a variable image URL. The attribute value may contain ADOR references to provide the image variability. For example:
<img xmp-src="images/{{xmp.r['image_offer'}}">The HTML declaration defines an image object whose source is an image in the site images folder, the name of which is determined by the image_offer ADOR. For instance, if for the viewing recipient the value is goat.jpg, then the displayed image would be from images/goat.jpg.
The xmp-href attribute can be used in an a (anchor) element to declare a variable target URL (href). The attribute value may contain ADOR references to provide the URL variability. For example:
<a xmp-href="{{xmp.r['offer_page']}}">click here</a>
<a xmp-href="offers/{{xmp.r['offer_page']}}">click here</a>
<a xmp-href="{{xmp.r['XMPie.PDF.P1']}}">View the PDF</a>This example shows three methods of using xmp-href. In the first, the ADOR contains the full URL to the target page, and in the second, the ADOR contains part of the URL to the target page. In the third, the ADOR is the automatic ADOR for a PDF on Demand touchpoint and the ADOR contains the full URL to the target page.
xmp-class can be used to determine the css classes applied to an HTML element. Being an alias of the angular ng-class, it can use ADOR values directly as class names, or determine class names based on an ADOR-dependent condition. For example:
<span xmp-class="xmp.r.MyStyle"> Your Text Here </span>
<span
xmp-class="{'gold':xmp.r.Member=='Gold', 'plain':xmp.r.Member!='Gold'}">
Your Text Here </span>The first usage sets the class to be the value of xmp.r.MyStyle. The second form determines the class name, either gold or plain, based on a condition which uses the xmp.r.Member ADOR.
xmp-show attribute can be added to any HTML element to determine whether it is visible or not. The attribute value should be an ADOR name, whose value is true or false.
xmp-repeat is intended to be used with Table ADORs. Table ADOR values are arrays of items, where each item is a dictionary containing keys for the table columns, with matching values for the items. Use xmp-repeat on an HTML element to create duplicates of it based on the amount of items in the Table ADOR value. Each row can locally use the row item. For example:
<ul>
<li xmp-repeat="item in xmp.r['Courses']">
({{item['ID']}}) {{item['Name']}} - {{item['Hours']}} hours
</li>
</ul>The above HTML segment creates a list with an item per row of xmp.r['Courses']. Each row is represented by item, as defined in the xmp-repeat expression. Inside the element the item properties are used, where a property is defined by the table ADOR columns.
Note that you can also use the regular ADORs within the context of a Table ADOR, providing personalized customization.
Assets are content elements, such as images and text files, that are uploaded to the Circle campaign. You can use these assets in your HTML by adding assets-specific attributes, such as xmp-image-asset, and providing as their values ADORs that when personalized, will have the name of those assets.
Use xmp-image-asset with an img element to set it with an image which is an asset from the Circle project. The value of the xmp-image-asset attribute is an ADOR reference, whose value for a recipient will be an asset name.
Use this directive outside the form element.
For example, the following sets the image with an asset which is the value of the xmp.r.MyAdor ADOR:
<img xmp-image-asset="xmp.r.MyAdor"/>Use xmp-text-asset with an HTML element to set its internal text to be the content of a text asset. The text asset is hosted on the Circle project, and the value of the attribute is an ADOR name. When the page is loaded, The ADOR is evaluated for the recipient and the result value is an asset name. The asset is then fetched, and the text becomes the element text.
Use xmp-html-asset with an HTML element to set its inner HTML to be the content of an HTML asset. The HTML asset is hosted on the Circle project, and the value of the attribute is an ADOR name. When the page is loaded, The ADOR is evaluated for the recipient and the result value is an asset name. The asset is then fetched, and the HTML content becomes the element internal HTML.
There are several built-in forms that XMPL provides. The forms can be used to register a new recipient, update the data of an existing recipient, or refer the campaign to a friend. Each form contains multiple input fields that are connected to matching ADORs (write ADORs) using the xmp-write-ador attribute. When the form is submitted by clicking a submit button in the form (there is no need to define a click event or target, this is done automatically), the relevant activity is carried out (e.g. create a new recipient). As a result of the activity you may want to redirect the viewer to another page, or run a method. To learn about available options for post submit behavior, see Success/Failure Behavior Modifiers.
Use xmp-write-ador in an XMPL form to associate an input field with an ADOR. The attribute should be placed on an HTML input or selected element and its value should be an ADOR reference. The ADOR must have a write expression (meaning it has to be a write ADOR). For example, the following binds the input field to xmp.r.Fname:
<input type="text" xmp-write-ador="xmp.r.Fname">The attribute is based on the angular ng-modal attribute, so that two-way binding is supported.
When using an xmp-write-ador you can, in addition, provide a xmp-default-value attribute which will be used to define an initial value to the referred write ADOR.
The new attribute can be used in 3 optional forms: xmp-update, xmp-register , xmp-refer.
In case the value of retrieved ADOR is empty the default value will be assigned (update form).
In case the ADOR is not exist yet, the default value will be assigned (registration form, refer form)
<form xmp-update>
<select xmp-write-ador="xmp.r['categoryAdor']" xmp-default-value="category2">
<option value="category1">category1</option>
<option value="category2">category2</option>
</select>
</form> xmp-update is an XMPL attribute that you can add to a form element. When the form submit button is clicked, the recipient data is updated. Use this form to provide editing capabilities to the recipient data. xmp-write-ador attributes determine the specific ADORs that are affected by this form.
xmp-register is An XMPL attribute that you can add to a form element. When the form submit button is clicked, a new recipient is added with the form data as its initial values, per the defined xmp-write-ador attribute inputs. Use this form to register a new recipient.
The form should be used in the context of an XMPAnonymousPage controller.
xmp-refer is very similar to xmp-register in that it creates a form that can be used to register a new recipient. However, this form is filled by an existing recipient, to recommend the website/webpage to another person. The xmp-write-ador attributes now refer to xmp.referredRecipient as receptors of the ADOR values, and when submitted the form creates a new recipient based on them. For example:
<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> The form definition has xmp-refer, making it a refer form. The only input field refers to the Fname ADOR of the referred recipient via xmp-write-ador="xmp.referredRecipient.Fname".
The attributes described in this section determine the behavior of the page in four possible scenarios:
- Page load
- Refer form submit
- Register form submit
- Update form submit
In each of these cases the action may succeed or fail, and you have the ability to define how the page will behave as a result. There are several attributes to do that. For example, xmp-success-url determines a location to navigate to on successful completion of the activity.
You may define these attributes on the relevant object, that is on the form element for form activities and on the ng-controller element for the page loading activity.
Particularly to forms, you may choose to define the attributes on the submit button(s) instead of on the form. Using this method you can define different behaviors for multiple submit buttons in the same form.
xmp-success-trigger can be added to trigger an email or external touchpoint to be sent when an activity completes successfully. The attribute value can be an Email Touchpoint ID to use for sending the email, or a shared email configuration ID as defined by an xmp-email element. You can also define customization on top of the predefined value (for example, you can override the From address for the email). For more details, refer to Triggered Emails.
Add xmp-success-url to an element so that when the matching action successfully completes, the viewer will be navigated to a new website. The URL is defined by the value of the attribute.
Add xmp-failure-url to an element so that when the matching action fails to complete, the viewer will be navigated to a new website. The URL is defined by the value of the attribute.
Add xmp-success-js to run javascript code upon successful completion of the activity. The attribute value should be javascript code to run (similarly to the onclick attribute).
Add xmp-success-ng to run javascript code upon successful completion of the activity in the angular scope context of the relevant element. This should allow you to use the scope values (such as the xmp data structure).
The attribute value should be javascript code to run (similarly to the ng-click attribute).
Add xmp-failure-js to run javascript code when the activity fails. The attribute value should be javascript code to run (similarly to the onclick attribute).
Add xmp-failure-ng to run javascript code upon successful completion of the activity in the angular scope context of the relevant element. This should allow you to use the scope values (similarly to the xmp data structure).
The attribute value should be javascript code to run (similarly to the ng-click attribute).
xmp-tracking-page-name attribute should be placed on the top level element, containing the controller element (with either XMPAnonymousPage or XMPPersonalizedPage). Its value will be the page name for purposes of tracking. Any tracking that is done in the page via xmp-tracking-action will have this attribute value as the page name.
xmp-tracking-action can be used on a button, input field or any other type of HTML element to create a tracked event if clicked or edited. The value of the attribute is the action name with optional extra parameters. You can read more about this activity here.
xmp-facebook-share can be attached to a button that when clicked the Facebook share window comes up. The data in the sharing window - target URL, description, displayed image and so forth - are defined via extra attributes that may also be affected by ADORS. Use it as a method to recommend your campaign to others through the recipient's Facebook wall.
For more details, read here.
xmp-twitter-share can be added to an anchor or button to establish Twitter sharing behavior. When the button is clicked a window comes up allowing the recipient to share information in their Twitter account.
Extra attributes on the element are used to define the message and reference URL. To learn more about this capability, read here.
Email sending may be triggered by placing the xmp-clicked-trigger attribute on areas where a click triggers the sending of an email, as well as defining xmp-success-trigger on the form/page controller. The attributes below control email sending.
xmp-email elements define shared configurations of email sending. You define them with an ID that is used for the email sending attributes to refer to these configurations. To learn more about xmp-email shared configurations, refer to Shared Email Configurations.
xmp-clicked-trigger attribute can be placed on a clickable element to trigger email sending when that element is clicked. The value of this attribute should be either an email touchpoint ID, or a shared configuration ID defined by xmp-email elements. Other attributes may be used to customize aspects, such as the "from" and "to" addresses. Read more about sending triggered emails in Triggered Emails.
The xmp-unsubscribe is used by the recipient to opt-out from getting further email.
The unsubscribe page is a regular XMPL personalized page. However this unsubscribe page must not be called from the website itself, but rather from the Account Settings. Set the URL to the page in Circle > Build > Connect > uProduce Account > Edit > Email Settings > Unsubscribe Web address > Custom. In the page itself xmp-unsubscribe attribute should be placed on clickable content in an unsubscribe page. When the content is clicked it changes the email subscription status for the current recipient. Its value, true or false,
sets it to unsubscribe or resubscribe respectively.
Example 1
<li><a href="" class="button special" xmp-unsubscribe="true" xmp-success-url="unsubscribed.html"
xmp-failure-url="unsuscribedFailed.html" >Unsubscribe</a></li>Example 2
<li><a href="" class="button" xmp-unsubscribe="false" xmp-success-js="alert(‘action completed successfully');"
xmp-failure-js="alert('action couldn’t succeed');">Subscribe</a></li>When a personalized page is loaded the ADOR references for it are scanned and later the page requests the values of these ADORs for the viewing recipient. Some ADORs, such as uImage-based image ADORs, take a long time to compute, and are therefore loaded asynchronously, automatically displaying a loading indicator until the image is loaded.
In some cases you may want to control the ADOR loading so that even if the images are not uImage ADORs they are loaded asynchronously, as they take a long time to compute. The xmp-async and xmp-load-async-ador help you control whether certain ADORs are be fetched asynchronously.
The xmp-async attribute can be added to an element (with no value) to denote asynchronous loading of this element.
Each ADOR defined by another attribute in an element that has xmp-async attribute will be fetched not by the regular ADOR fetching, but rather a request is sent per xmp-async element for the ADORs that are referred in its attributes.
For example:
<img alt="Your Text Here" xmp-image-asset="xmp.r['uimage']" xmp-async />
Note that xmp-async does not affect child elements. Child elements will have their ADORs fetched with the initial load. If you want to wait for child ADORs, define them as xmp-async as well.
While the ADORs are loaded for the element, it will change its appearance. A DIV element will appear next to the element, now hidden. When loading ends the element will be removed and the original element shown.
You can control the appearance of the loading element with two attributes that you can place on the original element (one with xmp-async):
-
xmp-async-busy-class- if defined, this class name will be defined as a class for the loading element. Through this class you can control it's viewing aspects. -
xmp-adapt-progress-size- if defined, the dimensions of the loading object will be equal to the dimensions of the original element at loading time.
Adding xmp-load-async-ador attribute to your element (usually the one that holds the ng-controller attribute), and providing as its value one or more ADOR names (separated by comma), will declare these ADORs for asynchronous loading. These ADORs will not be loaded as part of the initial ADOR fetching for the recipient. Rather, they will be loaded using an asynchronous job. This is useful for ADORs that take long time to compute.
As opposed to using xmp-async attribute, using xmp-load-async-ador has no direct visual effect on the element that defines it (only the ADORs declared by this attribute are loaded asynchronously, not all attributes defined on this element).
When using the XMPL controllers, XMPAnonymousPage and XMPPersonalizedPage, the initial login or loading of ADORs may take some time. If you want to hide areas of your page until it is done, apply to them the xmp-cloak attribute. The XMPL CSS file defines anything with this attribute to display:none. When the page is loaded the directive definition for xmp-cloak removes itself, so the areas are not shown. (If you don't include the XMPL CSS file, create relevant definitions in your own CSS).
This practice is similar to the Angular ng-cloak. Note that areas using xmp-cloak do not require an extra ng-cloak, as the event causing xmp-cloak to be removed comes after the ng-cloak removal event.
You may want to update values for a recipient as soon as the page loads. To do this, define xmp-update-on-page-load elements. For example:
<xmp-update-on-page-load xmp-ador="xmp.r['Visited']" xmp-value="1"/>The example saves the value 1 to the Visited ADOR.
Two attributes are defined to the elements:
xmp-ador - a reference to the ADOR for which to save the value
xmp-value - the value to save
Note that xmp-value may be an expression (Angular expression), and it is evaluated when page load is finished, so that ADOR values may be used.
Use xmp-load-ador as an attribute anywhere within the controller element to declare ADORs for loading. Its value should be a comma-separated list of ADOR references.
Usually you don't have to do this as the controllers scan their content for ADOR references on load time (plain regex search). However, in some scenarios the ADOR references won't be available at this point. For example, if you are using ADORs outside of the XMPL controller (in case of sharing the xmp element), you will want want to declare them so that they are fetched.
Use xmp-load-ador-timeout attribute on the controller element to define a general timeout for all requests going to the XMPL server. The value should be the number of milliseconds for waiting.
Use xmp-no-caching attribute on the controller element (with no value) to note that there should be no caching done for get requests. The XMPL server caches ADOR get request, and resets them based on XMPL system updates (similarly to when write ADORs are executed). If you use methods outside of XMPie to update data for the particular project, use this attribute to turn off caching so that data will always be up to date. It is usually better to avoid this for performance reasons.
When there is an error in either page load or form submit then the XMPL controller controlled ares will be covered with a friendly error page providing details about the error (mainly HTTP data). This is provided to make sure you note that there are errors. If you want to turn it off, place xmp-turn-off-default-error attribute (with no value) on the controller element.
New!! Take a look at XMPL V5 Beta