Steps to Initialise Live Updates with JS

Initialising Live Updates with the Object Constructor in JavaScript

Until this point, we have focussed on how to use our data-attributes to configure the Live Updates API. In this guide we'll show you how to initialise with JavaScript. This is intended for advanced users, who may wish to extend the functionality.

1) Include the JS

Similar to the Getting Started Section, include the following Liquid to asyncronously load the JS only once per page.

{% if context.exports.sitebuilder.live_update_JS_loaded == blank %}
  <script async src="{{'modules/module_86/js/v1-6/sitegurus_live_update_javascript_api.min.js' | asset_url }}"></script>
  {% assign live_update_JS_loaded = true %}
  {% export live_update_JS_loaded, namespace: sitebuilder %}
{% endif %}

We'll skip this snippet of code in the next few examples, for brevity.

2) Add an event-listener to watch for the Script to load

Since the JS runs asynchronously, the constructor function cannot be invoked immediately. We provide a custom event on the document which can be listened for so that we know when the script is ready.

<script>
  //The live-update module's script is loaded asynchronously, so you must wait for it to be ready before using its functions.
  document.addEventListener('live_update_script_ready', ready);
  function ready() {

  }
</script>

3) Passing in the Public Key and Initialising

First, include the module JavaScript via CDN and generate the public_key on the server-side as shown earlier in this article.

Next, you'll need to pass the public_key to your JavaScript. You can either:

a) write the JS in an inline <script></script> tag and output the public_key straight into the JS using Liquid b) or you can use Liquid to output the public_key into a data-attribute and fetch it from the DOM when needed. Tip: You may not wish to use a different attribute other than data-sg-live-update-key, as this will trigger the default event-listeners in the module if present. c) Or you can use Liquid to output the public key as a global JS variable in an inline script tag.

Inline Script Tag example:

<script>
  //The live-update module's script is loaded asynchronously, so you must wait for it to be ready before using its functions.
  document.addEventListener('live_update_script_ready', ready);
  function ready() {
    //Initialise an HTML element to mark it as ready to live-update
    const section = new SitegurusLiveUpdate(
      {
        publicKey: "",
        element: document.querySelector('#mySectionID'),
        liveUpdateComponents: Array.from(document.querySelectorAll('[data-sg-live-update-component]')),
        defaultParams: {
          per_page: 2
        }
      }
    )
  }
</script>

Refer to the API Reference for the full range of available options which can be used while initialising with JS.

4) Add an HTML control and attach an Event Listener

<script>
  //The live-update module's script is loaded asynchronously, so you must wait for it to be ready before using its functions.
  document.addEventListener('live_update_script_ready', ready);
  function ready() {
    //Initialise an HTML element to mark it as ready to live-update
    const section = new SitegurusLiveUpdate(
      {
        publicKey: "",
        element: document.querySelector('#mySectionID'),
        liveUpdateComponents: Array.from(document.querySelectorAll('[data-sg-live-update-component]')),
        defaultParams: {
          per_page: 2
        }
      }
    )
    var myControlElement = document.querySelector('#mySectionID').querySelectorAll('button');
    //Use the liveUpdate() method to live-update the component when something happens.
    myControlElement.addEventListener('change', function(button) {

    })
  }
</script>

5) Trigger a Live Update when the Event Callback runs

Earlier we stored a reference to the Live Update instance in a variable called section. We can use this now to run the liveUpdate method inside the event callback function.

<script>
  //The live-update module's script is loaded asynchronously, so you must wait for it to be ready before using its functions.
  document.addEventListener('live_update_script_ready', ready);
  function ready() {
    //Initialise an HTML element to mark it as ready to live-update
    const section = new SitegurusLiveUpdate(
      {
        publicKey: "",
        element: document.querySelector('#mySectionID'),
        liveUpdateComponents: Array.from(document.querySelectorAll('[data-sg-live-update-component]')),
        defaultParams: {
          per_page: 2
        }
      }
    )
    var myControlElement = document.querySelector('#mySectionID').querySelectorAll('button');
    //Use the liveUpdate() method to live-update the component when something happens.
    myControlElement.addEventListener('change', function(button) {
      section.liveUpdate({
        page: button.dataset.page
      })
    })
  }
</script>

You can find the full reference for this method and others in the API Reference. Other methods can be run on the instance in the same way.