Build and managing experience templates

In this article, we will focus on the tasks of building, configuring, and managing the templates that are used to build experiences. These tasks should be performed by a developer familiar with JavaScript and CSS.

Select Experiences from the side menu, select , and Create new template

Enter a name for the template and a description-both are mandatory

Select Save

For those familiar with creating Custom experiences, the UI for editing code is very similar; you use the same editor to access and edit the JavaScript and CSS files that form the basic building blocks of each template. The JavaScript and CSS are contained in the following files:

• triggers.js(/content/developers/experience-triggers-js) - used to determine when an experience executes
• utils.js(/content/developers/experience-utils-js) - used to define common functions and variables that can be reused across experience files
• fields.json(/content/developers/experience-fields-json) - predefined schema used to define the options that will be made available to the user creating the Simple messages experience
• package.json(/content/developers/experience-package-json) - contains metadata about your experience, including package dependencies
• variation.css(/content/developers/experience-variation-css) - used to inject CSS rules into a page if your variation is executed

To get started select and Edit against the template you wish to edit:

Once you have finished editing the code, you must save it by selecting Save in the editor

You can now return to the Templates view by selecting in the top-right hand corner of the editor

The editor includes a default code block:

module.exports = function triggers (options, cb) {
  cb()
}

This trigger will pass when cb() is called. Any code that you wish to add must stay inside that function.

Code can be asynchronous.

The cb() function must be called at some point to ensure the trigger rule is seen as passed.

The variation.js file contains a code block that executes if the visitor is served the experience. Of course, the visitor is only served an experience once all the trigger and segment conditions have been met.

By default, an empty function block is provided:

module.exports = function variation (options) {
}

Any JavaScript added to the page must be added inside this function block.

Example:

module.exports = function variation (options) {
  var $ = window.jQuery
  $("#navigation_sale").text("offers")
}

All the code written in the editor is locally scoped.

In this section we will look at a few examples that you can use to get started with the variation.js file.

This is used to persist the preview of the experience across different pages, without the necessity of adding the preview URL parameter to the URL. This will persist the preview link for 15 minutes or until another preview link is loaded.

Example:

function (options, cb) {
  require('@qubit/remember-preview')(15)
  cb()
}

This can be used to poll for certain elements to ensure they are on the page before variation.js runs. It can poll for an array of elements or an outcome of functions within the array:

Example:

module.exports = function triggers (options, cb) {
  // 1.
  options.poll('.nav').then(cb)

  // 2.
  options.poll(function() { return true }).then(cb)

  // 3.
  options.poll(['.nav', '.header']).then(cb)

  // 4.
  options.poll(['.nav', 'window.universal_variable']).then(cb)

  // 5.
  options.poll(['.nav', 'window.universal_variable', function () {
    return true
  }]).then(cb)
}

The resulting targets will be passed into the callback function in the same order.

module.exports = function triggers (options, cb) {
  options.poll(['.nav', 'window.universal_variable.page.type', function () {
    return window.foo()
  }]).then(cb)
}

Within Experiences, we expose the options object. Within this there are the getVisitorState and getBrowserState functions. The following can be used to only run the experience if the visitor has more than 5 pageviews in the current session.

Example:

module.exports = function triggers (options, cb) {
  options.getVisitorState().then(function (data) {
    if (data.viewNumber > 5) cb()
  })
}

This can be used to return the total session count for a visitor.

Example:

module.exports = function triggers (options, cb) {
  options.getVisitorState().then(function (data) {
    if (data.sessionNumber > 2) cb()
  })
}

This file defines the options that will be available to the user building the experience. See fields.json for details of using this file.

Periodically, whilst building your template, it is recommended that you preview it to ensure it functions as expected.

Select

Enter a value in the Preview URL field and define the background image to use for the banner by entering a value in the Image field

This must be an absolute URL and include the prefix http://, for example, http://www.example.com/my-background-image will work. /my-background-image will not work.

Define the hyperlink for the banner by entering a value in the Link URL field

This must be an absolute URL and include the prefix http://, for example http://www.example.com/user-will-land-here will work.

Select Preview

The fields displayed above correspond to the input fields you defined in fields.json:

Example:

{
  "title": {
    "type": "url",
    "label": "Preview URL",
    "required": true,
    "description": "The preview URL"
  }
}

Once you have built and configured a template, it will be added to your list of templates. From this list, you can edit it, change its status, and duplicate it. Refer to the following sections.

To manage your templates, select Experiences from the side menu, select , and Manage templates

The Templates view shows a list of your templates and includes the following details for each one:

• The template name
• The type of experience the template can be used for
• The number of experiences the template is powering
• The status of the template

In the following example, we see that the template called Hero banner offer is currently powering 2 Simple messages experiences. Its status denotes that it has been tested and verified by QA and is therefore ready to be used in a productive environment. Only templates that are marked as Production-ready can be used to build experiences.

Once a template powers one or more experiences, it can no longer be edited. In this scenario, it is recommended to duplicate the template and make any changes there. See Duplicating a template for more information.

As long as your template is not being used by an experience, you can make changes to it.

Select the menu button and Edit, as shown in the following example:

As mentioned, duplicating a template is a good option if a template you built is already being used to power experiences and you want to make a change to the template. Duplicating is also recommended when you want to push a template to a productive environment and keep a copy as a draft that you could continue working on.

Select the menu button and Duplicate

Enter a name for the duplicate template and select Duplicate

As long as your template is not being used to power any Simple messages experiences, you can rename it

Select the menu button and Rename

Enter a name for the template and select Rename

As long as your template is not being used to power any experiences, you can delete it. Once deleted, a template cannot be retrieved. It is therefore recommended that you exercise caution when deleting templates.

Select the menu button and Delete

Select Delete to confirm