Live Updates - Guide - Using Methods

This guide will show you how to use methods after data-attributes initialisation. If you want to use the object constructor, look here.

What are Methods?

Methods are another name for functions which you can run on an object in JavaScript.

The Live Updates API builds an object we call an instance for each of the sections of code you add data-attributes to. You can access these and call methods to set advanced options, affecting how the API works.

Available Methods

You can see the full list of available methods in the API Reference

How to use Methods

1) Wait for the script to load

Since the Live Updates API JS loads asynchronously, you need to get your code to wait for it to finish loaded before accessing it.

We provide a custom event for this, so set an event listener to wrap all your code which will need to work with the Live Updates API (note the window.sgLiveUpdateInitiated variable was added in Live Updates v1-3, you'll need to update your scripts to use it):

if(window.sgLiveUpdateInitiated === true) {
  myFunction();
} else {
  document.addEventListener('live_update_script_ready', myFunction);
}
function myFunction() {
  //Target an instance of SitegurusLiveUpdate and use a method.
  
}

2) Optional: Add a data-sg-live-update-section data-attribute to the layout

Adding the data-sg-live-update-section with a unique value to the same element where you added data-sg-live-update-key allows you to reference it later.

This is useful if you want to use methods on a specific layout. If you want to instead apply the method to all instances of Live Update in a loop, you can skip this step.

3) Access the instance for the layout you're working on

Since using data-attributes automatically initialises the SitegurusLiveUpdate object, we provide a global JavaScript variable window.sgLiveUpdateConfig (and a custom event on the document element live_update_script_ready to inform you when it's ready to access) to provide a list of all the initiated instances.

Each instance is stored within the object against a key which is derived from the data-sg-live-update-section="your_key" attribute on the main element, or a incrementally designated number by default.

You can access a specific instance via this key, or loop over them all and run your method on the instance. In the example, replace methodName with the method name from this documentation.

<script>
  if(window.sgLiveUpdateInitiated === true) {
    ready();
  } else {
    document.addEventListener('live_update_script_ready', ready);
  }
  function ready() {
    //Access a specific instance with a known ID (see optional step 2.)
    var instance = window.sgLiveUpdateConfig['your_instance_id']
    //Loop over all instances, accessing each in turn
    for(key in window.sgLiveUpdateConfig) {
      var thisInstance = window.sgLiveUpdateConfig[key];
    }
  }
</script>

4) Call the method on the instance

<script>
  if(window.sgLiveUpdateInitiated === true) {
    ready();
  } else {
    document.addEventListener('live_update_script_ready', ready);
  }
  function ready() {
    //Access the first instance
    var instance = window.sgLiveUpdateConfig['your_instance_id']
    //Call method
    instance.setSuspenseHTML('<div>loading</div>');
  }
</script>

More methods can be found in the API Reference