Customize a customer’s experience of previewing your app on their website.

By default, when customers change options on the install page for your app, their site’s preview will have to reload before they can see the result of their changes. On slower websites, and in situations when the customer is making many quick changes at once (such as typing into a text field), this can make the install experience slower than we’d like.

You can, however, fix this by adding Live Update support to your app. Live Update uses JavaScript to update your app’s preview instantly as the customer changes options.

How to enable Live Update

To enabled Live Update, you must add one or more preview handlers to your app’s install.json file.

When one of the matched options are changed, the execute block of JavaScript will be executed on the page being previewed upon.

You can use this teardown and re-initialize your app, or you can implement a method to just update it with the new options.

"preview": {
  "handlers": [
    {
      "options": ["_default"],
      "execute": "INSTALL_SCOPE.updateOptions(INSTALL_OPTIONS)"
    },
    {
      "options": ["_product"],
      "execute": "INSTALL_SCOPE.updateProduct(INSTALL_PRODUCT)"
    }
  ]
}

(function () {
  'use strict'

  var options = INSTALL_OPTIONS
  var product = INSTALL_PRODUCT

  function updateElement() { /* ... */ }

  window.INSTALL_SCOPE = {
    updateOptions: function updateOptions (nextOptions) {
      options = nextOptions

      updateElement()
    },
    updateOptions: function updateProduct (nextProduct) {
      product = nextProduct

      updateElement()
    }
  }
}())

Handler Format

Each handler has the following properties:

options

REQUIRED

The options section is an array of property keys which this handler should apply to. When any of those options are changed during a preview, this handler will be triggered. A given property may have multiple handlers.

Options can also be handled using special keys:

In this example the INSTALL_SCOPE.updateAlignment function will execute when the customer changes either horizontalAlignment or verticalAlignment. INSTALL_SCOPE.updateOptions will execute when the customer changes the location or theme options.

Multiple update handlers are useful when an app has options that have different updating procedures.

execute

OPTIONAL

A block of JavaScript which will be executed on the page being previewed. Use this JavaScript to instruct your app to update based on the updated options.

"options": {
  "horizontalAlignment": {...},
  "verticalAlignment": {...},
  "location": {...},
  "theme": {...}
}

"preview": {
  "handlers": [
    {
      "options": ["horizontalAlignment", "verticalAlignment"],
      "execute": "INSTALL_SCOPE.updateAlignment(INSTALL_OPTIONS)"
    },
    {
      "options": ["_default"],
      "execute": "INSTALL_SCOPE.updateOptions(INSTALL_OPTIONS)"
    }
  ]
}

reload

OPTIONAL

Should the page being previewed reload? Reloading the page is the default way we update the app without Live Update handlers. By default, when you set an execute block for a property that reload is disabled, meaning you generally don’t need to set reload: false if you set an execute block.

If you have a property which does not affect the preview experience, you can set reload: false without setting an execute block to instruct the preview to not bothering reloading the preview.

"preview": {
  "handlers": [
    {
      "options": ["email"],
      "reload": false
    }
  ]
}

Writing execute blocks

It’s generally necessary to expose a global object inside your app which your execute block can call. For example, the Self Summary app exposes a setOptions function.

Adding Live Update to some elements is more complex than others. It’s perfectly acceptable to only add live updating handlers to some fields, while allowing others to use preview reloading.

Dealing with element fields

When you use a field with type: "object" and format: "element", you generally call INSTALL.createElement to create a new element using the provided selector and method. (Learn more about the INSTALL object and other environment variables in Environment.)

The createElement method finds the provided selector and inserts a new element at the location specified by method. For the append, prepend, before and after methods all you generally have to do is either remove the previous element, or not recreate it.

The replace method however replaces the old element with the new element created by createElement. When the customer then changes the element using Live Update however, the old element will have been lost. To prevent this, always pass the previous element as the second argument to createElement.

(function () {
  'use strict'

  var element = null

  function updateElement () {
    element = INSTALL.createElement(options.container, element)

    // Set the contents of element here.
    element.textContent = 'Hello there, ' + options.name + '.'
  }
}())

See the Add Content app for an example of how to do this with an array of elements.

Hiding the preview

Some apps don’t add anything visually to the website they’re being installed upon. Showing a preview when nothing visually on the website has changed can be confusing to the customer, leading them to think your app is broken.

Often it still makes sense to embed a message on the previewed page to explain to the customer what is being installed and how it works. For example, if you are building an analytics tool you could take the customer through a tour of the types of things which would be measured.

If you can’t find such an opportunity however, you can disable the preview to prevent any confusion.

"preview": {
  "hide": true
}