Building a Simple Message Experience Template

In this tutorial we will cover the process of creating a template for Simple messages experiences. This tutorial is suitable for These tasks should be developers familiar with JavaScript and CSS.

You can read more about templates and how they are used to create experiences in Simple messages Experiences

Select Create new template.

Give your template a name and select on Let's start.

The triggers.js file controls when an experience will fire. Triggers are checked every pageview. If none are set, the experience will fire on every pageview.

The triggers.js file includes the following default code block:

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

In its default state, the experience will always fire because the cb() function is always called. But you can modify the triggers.js file to call cb() at any point.

For example, you can use the following snippet to ensure that the experience only fires if the visitor is in their first session:

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

So now, let's move onto adding content to the triggers.js file for this tutorial. We will do this in 2 steps:

1. Adding the remember preview module

   Using the remember preview module allows you to stay in preview mode, even without using the preview link. This is useful to test experiences across multiple pageviews.

2. Adding the poller module

   Before triggering the experience, you need to check that all the elements are on the page and have loaded. To do this, we recommend using the poller module.

   Whenever you interact with the DOM you need to ensure the required elements have loaded. Qubit provides you with the poller module, which allows you to wait for specific elements, window variables, or custom functions.

   See Polling For Elements for more information.

Start by selecting triggers.js from the list of files in the side menu.

Add the following lines to your trigger:

require('@qubit/remember-preview')()

This gives us:

module.exports = function triggers (options, cb) {
  require('@qubit/remember-preview')()
  cb(true)
}

For this tutorial we want to change the following elements:

• Image: #shopify-section-hero .hero
• Heading: #shopify-section-hero h2
• Subtitle: #shopify-section-hero .mega-subtitle
• CTA Link + Text: #shopify-section-hero .hero__btn

This means we need to poll for 4 elements:

const elements = [
  '#shopify-section-hero .hero',
  '#shopify-section-hero h2',
  '#shopify-section-hero .mega-subtitle',
  '#shopify-section-hero .hero__btn'
]

options.poll(elements).then(function ([container, heading, subtitle, button]) {
  // see next section
})

This gives us:

module.exports = function triggers (options, cb) {
  require('@qubit/remember-preview')()
  const elements = [
    '#shopify-section-hero .hero',
    '#shopify-section-hero h2',
    '#shopify-section-hero .mega-subtitle',
    '#shopify-section-hero .hero__btn'
  ]

  options.poll(elements).then(function ([container, heading, subtitle, button]) {
  // see next section
    cb(true)
  })
}

The example above ensures that the poller waits until all these elements have loaded before executing the callback function. As you can see the callback function gets the elements you poll for as arguments. Having the reference to the DOM elements is great so we don't have to search the DOM again, which is expensive.

As a best practice you should prefix your jQuery/DOM references with $.

Once the poller has passed we can call cb(true) to activate the experience.

However, before doing this we use options.state to pass our DOM reference to the variation code:

options.state.set('data', { $container, $heading, $subtitle, $button })

See Experience API for more information about options.state.

Here's our final snippet for triggers.js:

module.exports = function triggers (options, cb) {
  require('@qubit/remember-preview')()
  const elements = [
    '#shopify-section-hero .hero',
    '#shopify-section-hero h2',
    '#shopify-section-hero .mega-subtitle',
    '#shopify-section-hero .hero__btn'
  ]

  options.poll(elements).then(function ([container, heading, subtitle, button]) {
    options.state.set('data', {
      $container: container,
      $heading: heading,
      $subtitle: subtitle,
      $button: button
    })
    cb(true)
  })
}

The variation.js file controls what happens once the experience has been triggered and should contain the main body of your experience logic.

The code in this file executes once all the triggers and segment conditions have been met.

The variation code is responsible for actually changing the banner on the homepage. As a first step we get the DOM elements from options.state.

Start by selecting variation.js from the list of files in the side menu.

By default, the variation.js file includes the following default code block:

module.exports = function variation (options) {
}

Add the following lines:

const { $container, $heading, $subtitle, $button } = options.state.get('data')

Next you'll need to implement the code that changes the hero according to the brief, for example:

$heading.text('NEW TEXT GOES HERE')

However, rather than hard coding the heading, link, etc, we will use variables instead. So, for example:

$heading.text(options.data.heading)

You can read more about using variables in the next section.

Add the following lines:

$container.css('background-image', `url(${options.data.image})`)
  $heading.text(options.data.heading)
  $subtitle.hide()
  $button.text(options.data.cta).attr('href', options.data.link)

Here's our final snippet for variation.js

Rather than hard-coding the heading, link etc, we can define them as variables. You do this in fields.json.

Refer to Creating and Managing Experience Templates for more information.

Let's look at the following example:

fields.json:

{
  "groups": [
    {
      "id": "message",
      "title": "Message",
      "subtitle": "Configure the hero banner"
    }
  ],
  "fields": [
    {
      "key": "heading", // this is the key you reference in variation.js
      "type": "String",
      "label": "Heading",
      "description": "The hero heading text",
      "required": true,
      "groupId": "message"
    },
    {
      "key": "image", // this is the key you reference in variation.js
      "type": "Image",
      "label": "Image",
      "description": "The banner image",
      "required": true,
      "groupId": "options"
    },
    {
      "key": "link", // this is the key you reference in variation.js
      "type": "URL",
      "label": "Link",
      "description": "Where your banner links to",
      "required": true,
      "groupId": "options"
    },
    {
      "key": "cta", // this is the key you reference in variation.js
      "type": "String",
      "label": "CTA Text",
      "description": "",
      "required": true,
      "groupId": "message"
    }
  ]
}

And here's how you reference it in variation.js:

$heading.text(options.data.heading)

You will need to remove the comments when using the above example.

You can preview the template at any stage:

Once you're happy with the template you can enable it for production. This means the template will now be available for creating Simple Message experiences: