Updating Recipient Data
You're currently viewing XMPL V3
Attention: XMPL V5 beta is now available!
In this entry we will look into the options for updating recipient data with XMPL tags.
Two methods are available:
- Using forms to update data with user input
- Automatically updating data on page load
As an example of a form using XMPL you can look into "update.html". To set it up and run it use the steps described in the Getting Started page.
Setting up a webpage that carries out updates is done in the same way as any other personalization page. Use the steps described in Webpage Personalization to set up the required javascript and css references, and to write the basic attributes.
The project plan is an exception. You should make sure to create write ADORs that can be associated with the elements that you wish to update. As an example you can review the SDK Sample Campaign plan.
One option to update user data is by providing the interactive means of a form. You can define an HTML form, let the user type in the data you wish them to update, and use the XMPL tags to both associate write ADORs with these values and ensure they get submitted to the server. Consider the following example:
<form xmp-update xmp-success-url="index.html">
<ul>
<li>
First Name : <input type="text" xmp-write-ador="xmp.r['First Name']">
</li>
<li>
Last Name : <input type="text" xmp-write-ador="xmp.r['Last Name']">
</li>
</ul>
<input class="btn-primary" type="submit" value="save">
</form> The form tag has two attributes:
-
xmp-update- marks the form for updating ADORs. When the form is submitted upon a submit button click, all ADORs that are associated with it (via the xmp-write-ador attribute in the contained elements) are collected with their respective form values and sent to the server to update the recipient data. -
xmp-success-url- provides the URL to navigate to after the form is successfully submitted. You may omit this attribute to remain in the same page after the form is submitted.
Input tags may be used to implement user input. To create a tie between an input field and the matching ADOR, add the xmp-write-ador attribute to the input element, and as its value provide an ADOR reference. For example, the following is a field that sets the First Name ADOR:
<input type="text" xmp-write-ador="xmp.r['First Name']">Note that when you place an ADOR reference using xmp-write-ador, then a two-way connection is created. This means that when the page loads, if the ADOR has also a "read" expression, the field is populated with its value.
In case the value of retrieved ADOR is empty, you can use a xmp-default-value attribute which will be used to define an initial value to the referred write ADOR.
If you want the field to be empty always, use an ADOR that has only a write expression.
Finally, to submit the form use a plain submit button. There is no need to provide any special attribute to the submit button for it to submit the form when clicked.
Note for AngularJS programmers. Behind the scenes, xmp-write-ador is translated to a simple ng-model. Apart from what is written in the "Hidden Fields and Initial Values" section below, the behavior of xmp-write-ador and ng-model is identical. Even so, make sure to use xmp-write-ador so that it is collected by the form to be saved on the server (ng-models are being ignored).
Hidden Fields and Initial Values
Sometimes you will want to automatically set values if a form is submitted. This behavior is common with regular forms, and for this purpose hidden input fields are normally used.
XMPL acts on this practice and allows you to use hidden input fields.
Normally for these kinds of practices you will want to provide a set value, instead of relying on an existing ADOR value in the database. To do this, set the value attribute to the desired value. Consider the following example:
<input type="hidden" xmp-write-ador="xmp.r['Update Form Submitted']"
xmp-default-value="true">In this example we have an input field that if placed inside a form will cause the ADOR Update Form Submitted to have the value of true, if the form is submitted.
This usage goes beyond just hidden fields. You can use the value attribute to preset any xmp-write-ador, although other than just this limited case of implementing automatic fields, it is better to avoid this practice and initialize the database with the correct initial value. For example, it is recommended to set up the database with the right values if you want a simple initial value for a null field. Set an actual non-null value when a record is created.
It is possible to place other attributes on an update form:
-
xmp-failure-url- redirect to the URL provided as a value in case of form fails to submit -
xmp-success-track-actionandxmp-failure-track-action- attributes providing the action name to track in case of success or failure to submit the form. -
xmp-success-jsandxmp-failure-js- javascript code (normally function calls) to run in case of success or failure to submit the form. -
xmp-success-ngandxmp-failure-ng- For AngularJS programmers. javascript code, evaluated under the Angular scope, to run in case of success or failure to submit the form.
When submitting a form you may want to carry out different activities based on the user's choices. One method to do so is to have multiple submit buttons, where each executes a slightly different action. For example, consider a form in an online shop where there are two buttons, one for submitting and continuing to browse products, and the other for immediate checkout. You can implement this by having two submit buttons, and using the XMPL ability to provide overrides to form activities, as can be seen in this example:
<input type="submit" value="Add to cart"
xmp-success-url="browseProducts.html">
<input type="submit" value="Add to cart and checkout"
xmp-success-url="checkout.html">We achieve this by adding an xmp-success-url with different values for each of the submit buttons. Based on the button that the user clicks when submitting the form, the attribute will override the respective form attribute (or, if there is no default, use it as the value) and act upon it.
This can be done with any of the xmp-update form attributes. You can provide defaults by defining the attribute on the form.
Another method of updating recipient values is to automatically set some values upon page load. This is normally used to track page visits, or to ensure users went through a certain step in a wizard.
To do so, place an xmp-update-on-page-load tag. For example:
<xmp-update-on-page-load xmp-ador="xmp.r['Visited']"
xmp-value="1"/>The above code ensures that the ADOR 'Visited' is set to 1 when the page loads.
The 'xmp-ador' attribute is used to provide the attribute reference, and 'xmp-value' provides the value.
Note that for a personalizaed page, xmp-update-on-page-load is considered after the data is loaded. This allows you to use expressions. For example, to convert the indication to a counter do the following:
<xmp-update-on-page-load xmp-ador="xmp.r['Visited']"
xmp-value="{{1 + parseInt(xmp.r['Visited'],10)}}"/>This should increment Visited on every load (make sure to preset it to 0 in the database).
Normally you would want to update a recipient input not as a first page. You will also want to redirect to another page after submitting a form.
When providing redirect instructions, you DO NOT have to place the rid parameter in the URL as you did in the initial landing page. XMPL passes the recipient ID through cookies, so at least for the same session redirects will have the recipient ID available for them. Therefore, there is no need for update.html?rid=XXXX if it comes from index.html?rid=XXXX.
important! For this to work you must set up the page and run it through an http server. Use the instructions in Getting Started to achieve this.
After learning how to update the data of existing recipients you may want to learn how to create registration forms to add new recipients. To learn more, go to Adding New Recipients Through Registration.
New!! Take a look at XMPL V5 Beta