Introduction and Use Cases

This example is useful if you want to use Siteglide filters on a WebApp or Module, but don't want to give your end-user the option of altering the filters by modifying the URL.

In this example, we set the filter as if we have a WebApp 1 with a custom field which can be filtered. We imagine there is a variable {{any_variable}} which might come from a datasource in a parent layout, or be hardcoded. These variables of webapp, field and filter value you can change depending on your use-case.

Example

Liquid in the wrapper.liquid file

{% comment %} Get public key as normal {% endcomment %}
{% function public_key = "modules/module_86/front_end/functions/v1/live_update_params_encode", layout: layout, model: _model, collection: 'false', creator_id: nil %}
{% comment %} Generate unique ID for the layout, unless one has already been generated and sent in the params. The main purpose of doing this here is to help the JavaScript reliably reference the instance of the Live Update object created for this layout.{% endcomment %}
{% if params.sitebuilder_uniq_component_id %}
  {% assign sitebuilder_uniq_component_id = params.sitebuilder_uniq_component_id %}
{% else %}
  {% capture sitebuilder_uniq_component_id %}sitegurus_component_{% increment sitegurus_gen_uniq_component_id %}{% endcapture %}
{% endif %}
{% comment %} Output Layout Wrapper code. {% endcomment %}
<section id="{{sitebuilder_uniq_component_id}}_table" data-sg-live-update-section="{{sitebuilder_uniq_component_id}}">
  {% comment %} Logic which will refuse to display any items until the correct filter is applied. {% endcomment %}
  {% if params.webapp_field_1_1 != any_variable %}
    {%- include 'modules/siteglide_system/get/get_items', item_layout: 'item' -%}
  {% endif %}
</section>
{% comment %} Re-render the layout using the filter param as soon as possible {% endcomment %}
<script>
  document.addEventListener('live_update_script_ready', ready);
  function ready() {
    {% comment %} Add to params the Siteglide filter relating to the WebApp custom field, and the unique ID custom parameter. {% endcomment %}


    window.sgLiveUpdateConfig['{{sitebuilder_uniq_component_id}}'].liveUpdate({webapp_field_1_1: '{{any_variable}}', sitebuilder_uniq_component_id: '{{sitebuilder_uniq_component_id}}'});
  }
</script>

Drawing your attention to the important bit: items are not displayed until the correct parameters are present in the URL. Users can't simply change the URL and access different content in this case!

{% if params.webapp_field_1_1 != any_variable %}
  {%- include 'modules/siteglide_system/get/get_items', item_layout: 'item' -%}
{% endif %}

Notes

• In this example, it's useful to have a reliable ID for the layout, no-matter how many are outputted on the page. We generate a unique ID if the layout is rendered front-end, but on the live-update re-render, we use the already generated ID that was sent in the params.

Introduction

SiteBuilder includes JavaScript files to add in interactive functionality which may not exist in the original design system or library.

Performance

We always load our module JavaScript asynchronously. This means it should not block page render and features will be initiated only when the JavaScript is ready. For example, if there is a button for sharing via Facebook, the button element will load straight away, but clicking it in the first second after page load will do nothing, but a seoncd or two later the functionality will be added.

Even with asynchronous loading, you don't want to load a script if it's not being used. Depending on the library, we'll load some scripts in the Page Template if they are used commonly across the library, whereas more specialised scripts will be included within layouts. Some scripts will not be included at all by default itf they're not generally needed. Feel free to add and remove scripts from your templates and pages if you're happy with the resulting functionality changes.

Data Attributes and Constructors

To start with, most of our JavaScript functions are initiated with data-attributes on particular elements which need functionality added.

As the module grows, we will start to make constructors more easily available so that functions can also be initiated with a new keyword and an options parameter.

See the specific documentation to learn more.

Extending or Callbacks

If you want to extend our JavaScript, we recommend waiting for the DOM to finish loading and the required scripts to finish loading first. Normally our scripts have an ID which can be targeted and given a "load" eventListener.

We recommend not using html event attributes to run our JavaScript e.g. onClick="" as these will probably attempt to find functions before they are defined.

Take your SiteBuilder development further with advanced features such as Live Updates API, JS and Liquid Functions:

1) Installing the Module and including the JavaScript

Firstly, make sure the SiteBuilder Module is installed on your site. Then, include the JavaScript via CDN in the Page. We recommend you use the Liquid in the example below; it helps to ensure that the JavaScript is only loaded once, even if used by multiple layouts, maintaining good performance.

2) Defining a Layout which will live-update and automatically generating a public API key

Secondly, choose which section of code you'd like the API to be ready to live-update.

• This must be some Liquid code which can be rendered using a single Liquid {% include %} tag. E.g. {% include 'module' %} or {% include 'webapp' %}. * The code must not rely on inheriting any variables from higher up in the Page because those variables will not be available on the API endpoint Page. If you need to pass in more variables, this must be done via URL Params and read via {{context.params}}.

At the top of this layout, in the wrapper file if it has one, you need to include the following Liquid. This generates a public_key you need to use the API. See "Thinking about Security" for why we use this. If you're using a WebApp or Module tag and layout from Siteglide, these variables will be available automatically.

However, if you're using a Liquid tag which has a value other than module or webapp, you will need to manually feed in the model_type parameter instead of model. For example, if you're using the tag:

...then your public key function should look like this:

You can also use the Live Updates API with a content_section or code_snippet. Note that these include types don't intrinsically react to changes in the URL e.g. setting a parameter like page would not be natively supported. This can however be a benefit if you intend to write custom code including GraphQl; you will have to write that server-side code yourself, but you can take advantage of the Live Updates JS and event-listeners to quickly implement filter functionality on the client-side.

To use Live Updates with a content_section or code_snippet, you need to add a model_type as above, selecting the one you intend to use. Then you also need to add an include_id to the ID of the snippet/ section:

See the collection and creator_id URL parameters for more details about setting collection to 'true' when generating the public key.

3) Initialising the JavaScript

Before you can use the API on a layout, you must let the JavaScript know that a particular layout needs to be prepared to connect to the Live Updates API. To do this we need to add a data-attribute containing the public key from earlier to a layout's main element. (See the API reference for an alternative method using the JavaScript new keyword.)

The layout will now initialise once the JS has loaded. You can check it has initialised and access the instance by typing window.sgLiveUpdateConfig into your JavaScript console.

4) Setting up a form for user interaction

At this point in our guide, your code should look something like this:

Next, a common feature of a layout with live updates is to add a form which the user can interact with to prompt some kind of change in what they are being displayed. For example, they may wish to sort, filter, change page or even edit the data they are seeing.

To add a form, we need another data-attribute. You can add as many forms as you need (if for example different controls need to be in different places in the layout).

The simplest way to add controls to your form is to use standard HTML form elements. The element's name should correspond to the URL parameter you wish the user to be able to change, while the value of the element obviously will set the parameter's value. Check the full example at the beginning along with the API Reference to see other kinds of supported controls and buttons:

Note ordinary HTML elements don't need any additional data-attributes. The API will watch for changes within the form area.

5) Defining Components

As you make changes to the elments in the form, the Live Updates API will update the entire layout with a new Liquid re-render and replace it in the DOM.

Replacing the entire layout in the DOM may not be ideal however, as users interactions with the form will be interupred by the change.

The API allows you to specify one or more "components" which should update when the data changes. Once you setup a component, the HTML in between components will no longer change.

Let's add the important Siteglide tag `

`, which fetches our results, inside a new area marked as a component:

Now the results will update when we the user types in the search box, but their entries so far will not be lost as the form is not inside the component.

It's required to give the component a unique value in its data-attribute so the API can match up the component in the DOM with the component in the re-rendered document.

That's the basics of the Live Update API.

Learn more:

• How to add sort buttons

• How to add custom toggle buttons

• How to set up pagination

• How to use a method to change advanced settings

The forms JavaScript is a lightweight script which includes a small function for handling checkbox valiadation.

Essentially, it handles instances where there is one checkbox field in the Siteglide Admin with multiple options; the field is required, but only one of the options needs to be checked ideally before the form is submitted. The script dynamically adds and removes the required HTML attribute from the checkboxes to achieve this effect.

Most validation scripts are included directly in the forms layouts to allow easier customisation, but the checkbox validation script has been abstracted because it is quite specialised.

Normally included in:

Page Templates

Script Code

Pre-Requisites

• This guide assumes you have a basic familiarity with:

  • Building WebApp and Module Layouts on Siteglide using Liquid tags

  • HTML, including data-attributes

Using a ready-made SiteBuilder Layout

Having said that, if you want to modify any other layout to start fetching live updates with the API, we'll show how to do that next.

Basic Markup Example

The following markup example would work well in the wrapper.liquid file of a webapp or module layout. The layout and _model variables will then be inherited from the tag used to output the layout in the page.

Live Updates - An Introduction

Introduction

The SiteBuilder Live Updates API helps you quickly build interactive, dynamic website layouts for Siteglide which live-update parts of their content when the user interacts with them.

This allows you to use the convenience of server-side rendering with performance more akin to a JavaScript framework.

How it works

When you want the server to live-update Liquid content, you normally need to create a new Page for each specific type of content and write JavaScript to send a GET request to fetch that content and insert it into the Page. This API provides a single ready-built API endpoint Page to make this process quicker. When we describe "adding parameters to the request" in this documentation, we mean adding query parameters to the GET requests' URL.

See the URL Parameters Section for more details on choosing parameters to modify your content.

Thinking about Security

When using a single page to deliver multiple types of content, how do we prevent malicious users requesting content they should not have access to?

When using the API, you'll get the server to generate a public key which contains encrypted information about the exact Liquid layout you are intending to use and live-update. This includes for example:

• The path of the Liquid Partial

• The WebApp or Module ID

• The user ID which might be used to filter the items based on ownership.

The same server handles the requests and it will only accept valid public keys from which it can extract that same information. That means sensitive parameters which are stored inside the public key cannot be simply modified by a user who does not have direct access to the server.

Secure Zones

PlatformOS cookies and user sessions are preserved by the requests, so secure zones will apply as normal within the Liquid files which are re-rendered. You will need to write code which respects secure zones logic as you normally would.

Mutating/ Editing Data

Specialised Use Cases

Introduction

The sitegurus_sliders_javascript_api is a script which allows multiple layouts on the same page to run fully responsive sliders powered by Swiper.js.

We chose Swiper.js because it's a well maintained library, which has a very wide range of configuration options, allowing all sorts of slider effects.

SiteBuilder layouts can use any front-end JS library, so using this API is completely optional. However, for those layouts which do use it, this article aims to help you make the most of the benefits.

Read more about the Slider Module here](/documentation/sitebuilder/modules_and_more/sliders).

How Swiper.js is initiated

Each of the layouts which uses this script will include the following code for loading the script and setting up the configuration for the slider:

This code is included inside the layout in order to allow some level of configuration by developers, while maximising performance:

1. It loads asynchronously along with its dependencies, and includes Liquid logic to ensure it only runs once.

2. It allows multiple slider layouts to be initialised on the same page, each with different settings, without conflicts.

3. It allows the developer to configure the settings and write JS which manipulates the sliders after initialisation, should they wish.

This is achieved mainly through creating a globally-scoped variable window.sitebuilderSwiperConfig. Each inidivudal slider is added to this object with a unique name and important properties are stored against it. Once the JavaScript is loaded, it reads this variable and initialises the sliders.

How to update the configuration

You will see inside the layout a config object:

For example, changing slidesPerView to 2 would show 2 slides on the page at a time.

Only the config property directly maps to the Swiper.js documentation, the initiated and onInit properties are used by Sitegurus behind the scenes.

How to programatically update the Slider

In the example below, we show you how to add a button to manipulate the slider once it is ready.

The references to each initialised slider are also stored inside the window.sitebuilderSwiperConfig object.

Example

{%- function field_map = "modules/module_86/front_end/functions/v1/field_mapping", field_headings: field_headings, this: this -%}

Purpose

This function is an important part of how WebApp Layouts can automatically adapt to handle different sources of data.

It takes in a headings object which stores field IDs as keys next to the names of available field slots as values. It then returns a new object using the values in this which stores the data values against those field slots so that the layout can output the data.

Adjusting the Mapping

If you add a new field to the WebApp after creating the layout with SiteBuilder, you can safely access that value via the this object as you normally would in a layout.

However, if you wish, you can also modify the existing headings in the JSON object.

Starting with this Object...

{% parse_json field_headings %}
{
"Title": "name"
}
{% endparse_json %}

You could change it so that existing {{field_map['Title']}} outputs would output values from a different field like so:

{% parse_json field_headings %}
{
"Title": "webapp_field_1_1"
}
{% endparse_json %}

Or you can add a brand new slot to the WebApp {{field_map['Extra Slot']}} and populate it with a new field's data:

{% parse_json field_headings %}
{
"Title": "name"
"Extra Slot": "webapp_field_1_2"
}
{% endparse_json %}

As the field_headings are passed into the function, the function will return an object where the required data values are stored against the correct keys.

Example

{%- function detail_page_valid = "modules/module_86/front_end/functions/v1/detail_page_valid", fc_data: fc_data, full_slug: this.full_slug -%}

Purpose

This function aims to check two things:

1. Whether a WebApp has a Detail Layout enabled?

2. Whether a WebApp Layout has a {{this.full_slug}} which fits an expected pattern.

In future, this function should also be able to provide these checks for Module Layouts too.

Currently, the function is experimental and works well as a straight-out-of-the-box solution for Layouts installed, but we do recommend you also carry out a manual check to make sure links to detial pages are working correctly.

Introduction

In this section of the documentation, we'll cover some common Liquid functions which SiteBuilder adds into Layouts so you can understand what this code is doing and, if you like, use them yourself.

A Liquid function is similar to an include tag except that they return a single variable instead of printing to the page. They are also close to being "pure" functions in that they do not inherit variables other than the ones you pass to them explicitly inside the tag, making them more reliable and less prone to unexpected side-effects.

Read more about Liquid functions here: Liquid Functions.

Versioning

These functions can be modified by future versions of SiteBuilder. The /v1/ in the path will be updated for newer versions of the functions. Newly installed Layouts will use the new version, but your existing code can continue to use the older versions, for backwards compatibility.

Introduction

The cookie settings JavaScript is a lightweight script designed to support SiteBuilder Layouts which modify a cookie in order to store the user's cookie preferences.

Here we'll explain how you can use the features of this script while modifying a layout.

How it works

After the user first sets their preferences, these preferences will be stored in a cookie with the name: sg-cookie-policy-settings which will expire after a year.

Loading the script asynchronously

<script async src="https://uploads.prod01.london.platform-os.com/instances/668/assets/modules/module_86/js/v1/sitegurus_cookie_settings.js?updated=1695044532"></script>

The Liquid will ensure the script is only loaded once on the page.

Creating Controls to set the preferences

Use the data-sg-cookie data attribute to set an element as a control that will modify the settings. The value of the data-attribute will be the value of the preferences cookie when set. Theoretically you can set it to any string, but normally you'll want to differentiate between a simple set of choices.

Since the script is loaded asynchronously, the controls won't have event listeners attached immediately. Meanwhile the user may be eager to access the rest of the site and may try to dismiss the popup as soon as possible. Therefore, we recommend you start the controls with styling which indicates that they are disabled. You can then use the data-sg-cookie-btn-enabled data-attribute to store classes which you would like to use to style the button once it is enabled. The script will replace the value of the class attribute with the value of the data-attribute when the script is ready.

Using Buttons

<button disabled data-sg-cookie="all" type="button" class="text-white bg-blue-400 dark:bg-blue-500 cursor-not-allowed font-medium rounded-lg text-sm px-5 py-2.5 text-center" data-sg-cookie-btn-enabled="text-white bg-primary-700 hover:bg-primary-800 focus:ring-4 focus:outline-none focus:ring-primary-300 font-medium rounded-lg text-sm px-5 py-2.5 text-center dark:bg-primary-600 dark:hover:bg-primary-700 dark:focus:ring-primary-800" >Accept all</button>
<button disabled data-sg-cookie="essential-only" type="button" class="text-white bg-blue-400 dark:bg-blue-500 cursor-not-allowed font-medium rounded-lg text-sm px-5 py-2.5 text-center" data-sg-cookie-btn-enabled="text-gray-500 bg-white hover:bg-gray-100 focus:ring-4 focus:outline-none focus:ring-primary-300 rounded-lg border border-gray-200 text-sm font-medium px-5 py-2.5 hover:text-gray-900 focus:z-10 dark:bg-gray-700 dark:text-gray-300 dark:border-gray-500 dark:hover:text-white dark:hover:bg-gray-600 dark:focus:ring-gray-600">Accept essential cookies only</button>

Using form elements

<div class="p-6 border-t border-gray-200 rounded-b dark:border-gray-600">
  <div class="flex items-center mb-4">
    <input  disabled data-sg-cookie="all" id="cookie-preference-1" type="radio" value="" name="cookie-preference" class="ml-2 text-sm font-medium text-gray-400 dark:text-gray-500" data-sg-cookie-btn-enabled="w-4 h-4 text-blue-600 bg-gray-100 border-gray-300 focus:ring-blue-500 dark:focus:ring-blue-600 dark:ring-offset-gray-800 focus:ring-2 dark:bg-gray-700 dark:border-gray-600">
    <label for="cookie-preference-1" class="ml-2 text-sm font-medium text-gray-900 dark:text-gray-300">Accept all</label>
  </div>
  <div class="flex items-center mb-4">
    <input  disabled data-sg-cookie="essential-only" id="cookie-preference-2" type="radio" value="" name="cookie-preference" class="ml-2 text-sm font-medium text-gray-400 dark:text-gray-500" data-sg-cookie-btn-enabled="w-4 h-4 text-blue-600 bg-gray-100 border-gray-300 focus:ring-blue-500 dark:focus:ring-blue-600 dark:ring-offset-gray-800 focus:ring-2 dark:bg-gray-700 dark:border-gray-600">
    <label for="cookie-preference-2" class="ml-2 text-sm font-medium text-gray-900 dark:text-gray-300">Accept essential cookies only</label>
  </div>
</div>

Accessing the current settings value

Note in this example above, we also use Liquid context.cookies.sg-cookie-policy-settings to set a default checked value to the radio currently active on page load.

Success event

Since this uses data-attributes, we don't have a callback function on success. Instead we set a custom event on the document:

document.addEventListener('sgCookiePreferencesAfterUpdate', success);
function success(event) {
  console.log(event.details)
}

Accessing event.details will let you know the current state of the preferences, however, you could of course use JS to check the cookies directly.

The script does not actually remove google analytics cookies which are already set. Layouts will disable any analytics script wrapped inside their Liquid logic. If you do wish to delete analytics cookies directly, we recommend you do this in a function called after the success event.

Example

{% function table_config = "modules/module_86/front_end/functions/v1/get_table_config", model: _model, id: id, field_headings: field_headings %}

Purpose

This function fetches the configuration file which Siteglide uses to store metadata about the WebApp or Module. By outputting the returned Object {{table_config}} you can explore the JSON tree and find out information about the WebApp dynamically.

SiteBuilder Layouts might for example use this to output the name of the WebApp in a Layout, or to loop over custom fields to output the field names as labels alongside the values.

The function carries out a GraphQL call behind the scenes, so for performance reasons, we recommend only including this function if you need it. It may be more appropriate, when you know the data should not change often, to hardcode these values in the Layout instead. Following this, you are also welcome to replace this function where you see it in an installed layout, with a more straightforward hardcoded solution.

However, if you have a situation where the WebApp configuration is likely to change often and you want the layout to automatically change often to reflect that, this function can be very useful.

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

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)[/documentation/sitebuilder/live_updates/API_reference]. Other methods can be run on the instance in the same way.

\

Version 1.5 - Released 17th May 2024

• Added option to specify onlyUpdateComponent array of strings in .liveUpdate() and .changeStateTrailingDebounce() methods.

These specify which components should re-render in the DOM after the update, for example if you pass .update({onlyUpdateComponent: ['mainResults']}); only the element with data-sg-live-update-component="mainResults" will re-render, not data-sg-live-update-component="filters".

The re-render will still take the same amount of time on the server-side, but this may be helpful to improve UX by supressing any DOM replacements which are annoying to the user.

Version 1.4 - Hotfix - Released 20th March 2024

• Regression Bug found where since adding default params option, some types of control element were being ignored. This update should fix this.

Version 1.4 - Released 21st December 2023

• Added new method .mergeDefaultParams() - this is to be preferred in most cases over .setDefaultParams() as the passed object will be merged with existing defaultParams rather than completely overwriting it. Any common params will still be overwritten. This will avoid overwriting module defined internal defaultParams including those that send the original URL over to the endpoint.

• Added new data-attribute data-sg-live-update-default-param. This attribute should be given to an HTML form element within a data-sg-live-update-controls element. As usual, the element must also have a name to define which parameter it will set. This element will now set a defaultParams property instead of directly setting a parameter. This is useful because you can use the new default elements to set a default then use ordinary elements to override that default when the user makes a change. See reference docs for examples.

Version 1.3

• Fixed bug in data-attribute initiated Live Updates where <select> form controls would trigger both the input and change events, creating a duplicate update and small associated delay. Now form controls are either assigned an input or change event listener depending on the most appropriate one for their type. Please let us know any feedback if you think an input type could be improved by switching to a different event in future.

• Improved reliability: New Custom Event and global variable added to make it easier to execute a function after the asynchronous Live Updates JS is ready, or after any data-attributes have been passed (if using). A new event live_update_constructor_ready will fire on the document element when the new SitegurusLiveUpdate() constructor is ready to use. We've also added a new global variable window.sgLiveUpdateInitiated which tells you when the data-attributes have been read and instances of liveUpdates automatically constructed. Putting these together, you can now use the following code when waiting to use the constructor:

if(SitegurusLiveUpdate) {
  myFunction();
} else {
  document.addEventListener('live_update_constructor_ready', myFunction);
}

You can also use this code if you want to wait for each instance of Live Updates initiated by data-attributes to be ready; Useful if you are using methods to modify them:

if(window.sgLiveUpdateInitiated === true) {
  myFunction();
} else {
  document.addEventListener('live_update_script_ready', myFunction);
}
function myFunction() {
  //Target an instance of SitegurusLiveUpdate and use a method.
  window.sgLiveUpdateConfig['1'].setSuspenseCSSClassList('my-class');
}

This code is more reliable than previous patterns when your own script is running asynchronously, as it should work whether your script or the Live Updates script is executed first.

• Improved reliability - live_update_end event used to fire after all synchronous code related to the update had run; it now fires after all synchronous and asynchronous code has run.

• Improved console error messaging for a few scenarios where Live Updates code is incorrectly set up.

Version 1.2 - Released 9th August 2023

• Only form elements with names will now be automatically initiated as Live Updates filters. This helps avoid unwanted re-renders when typing in elements which are not intended to be used as filters. This helps compatibility with the search function of plugins like https://github.com/Choices-js/Choices

Version 1.1 - Released

• New functionality added for modifyHistory, including a method and data-attribute for setting it. When turned on, any changes to live update form elements will push those same changes to the history API. This causes the URL in the browser's address bar to change without reloading the page. It is useful if you want the URL to your live-updates-powered page to be shareable.

• If any of the live-updates filters have an HTML value attribute (with a truthy value) on page load, a live update will run immediately as soon as the JavaScript is ready. This allows you to take a shareable link provided by the above modifyHistory feature, or a link from a non-live-updates layout, like a Blog Detail page, load that link and instantly have it apply those filters.

• The combination of these two features is powerful, but we recommend only one live-updates layout has this feature turned on on each page, otherwise you can end up in a loop where one layout's filters update the filters of another.

About SiteBuilder updates and backwards compatibility

Summary

• Always install updates to the main SiteBuilder Module before any Themes

• SiteBuilder updates won't overwrite your site code

• Uninstalling the SiteBuilder module may cause some code to stop working.

In Detail

We're always adding to SiteBuilder and its associated Theme Modules. However, it's important to us that changes to this module do not cause you problems on your site.

Therefore, we never change the layouts on your site during an update. We only update the "master copy" of the layout in the module. That means brand new layout installs from the module will have updates, while older layouts will continue to function as before.

There are exceptions to this rule, for example Liquid includes which power functionality like dynamic forms. In these cases, we will only modify these files with non-breaking changes. For breaking changes, a new version of the file will be created and linked to new layouts, leaving the old version continuing to function with existing layouts.

For the optimum compatibility, we recommend always making sure the main SiteBuilder module is up to date before updating any SiteBuilder Theme modules. Some Theme module updates may rely on the latest version of SiteBuilder.

Releases

4.18.0 - Released November 15th 2024

• Theme Presets released for the Flowbite Theme - we'll talk about these a lot more in the coming days. In short, presets are a set of defaults for your Tailwind Config which set default colour, font and much more! You can switch preset to completely change the look of your site while keeping the HTML untouched. To start with we're releasing the following:

  • Gardening Preset

  • MNTNs Preset

• New layouts to be released alongside the presets which are fully compatible with the Flowbite Theme but have come from other designers' open-source work. These make a more generous use of both primary and secondary colour variables.

• Structured Data added to the following Detail layouts for better SEO:

  • Authors

  • FAQs

  • Events

4.17.2 - Released October 25th 2024

+ Flowbite Pro Version 1.9.4

• New Admin Table Layouts for Modules:

  • Blog List

  • FAQ List

  • Events List

• 2 New Blog Detail Layouts

• 2 New Form Layouts

• New Accordion WebApp Layout

• Original Blog Detail Layout updated with new features (will roll out to other Blog layouts soon):

  • Google Structured Data Support

  • Support for visiting URL with ?edit=true at end of URL to display edit form (after permission checks). This goes nicely with the Admin Tables which can link to it.

• Updated many modals to be "static" to prevent accidental closing

4.17.1 - Released October 2024

• Support for new Pro layouts in Preview Mode

• Removed console errors for Live Updates which were unnecessary (logs not errors).

• Flowbite Pro Theme - Version 1.9.4

  • A new eCommerce themed menu layout containing a mini cart preview

    • Cart preview includes product thumbnails, names and prices

    • User can delete items from cart, with live-updates supported re-rendering for a smooth experience

  • A new Blog Detail layout alternative

  • More static layouts for Portfolio and Promotional Section

4.17.0 - Released 24th September 2024

• Tailwind build method can now be overridden on the Page Template level, either by setting when you create a Page Template, or by using the template_build_method parameter (can be set to either "cli" or "preview"):

{% include 'modules/module_86/tailwind/head', template_build_method: 'cli', template_build_me optional_path_to_cli_css: '' %}

• New Preview build method for Tailwind. This is a replacement for the now deprecated JIT option, which should provide faster development times.

  • Preview mode is designed to load CSS fallbacks so that any Flowbite blocks added to the site will be supported out-of-the-box, using Flowbite default variables.

  • It can be used alongside a CLI build. The CLI build will override any classes you've used, with branded versions of the variables you've set in your Tailwind Config file, while continuing to fallback to Flowbite defaults when brand new blocks are added.

• New Static Layouts for Flowbite:

  • Portfolio

  • Promotional Section

4.16.3 - Released 19th September

• Small UX and styling improvements to navigation and scrolling

4.15.2 - 4.15.3 - Hotfixes - Released 10th September 2024

4.15.1 - Released 5th August 2024

• Patch to fix Flowbite WebApp Edit Form layout not installing properly in "static" mode.

4.15.0 - Released 3rd August 2024

• New Layout type- Category List Views - these work as code snippets which can be added almost anywhere and either loop over all categories or children of a category ID you pass in in settings.

  • SiteBuilder 4.15.0

    • 2 new Category List Layouts

  • Flowbite Pro Theme 1.9.0

    • 5 new Category List Layouts

4.14.0 - Released 17th July 2024

• New Flowbite Form Confirmation Layout which will automatically display submitted custom fields with headings.

  • Each field type will be displayed appropriately, e.g. files can be downloaded and images will be displayed.

• Page Templates and Flowbite Cookie Popup Layouts will include code for Google Tag Manager- ID will need adding manually in order to work.

• Cleaned up some old files no longer used

• Renamed some eCommerce layouts for clarity

4.11.1 - 4.11.4 - Released 17th June 2024

• Patches to manually-managed setting on files created with SiteBuilder

• Changes to Tailwind setup folder structure - for easier setup

4.11.0 - Released 14th June 2024

• Changelog coming soon. Suggest holding off on update until ready.

4.10.0 - Released 17th May 2024

• Updated Layouts generally to support latest version of Flowbite v.2.3.0 and Tailwind CSS 3.4.3. To get the benefit of newer Flowbite JS, you will need to update the <script> tag in any SiteBuilder-built Page Templates. When testing the Site Templates, we didn't find many compatibility issues- the main one was a change in syntax for Flowbite Modal components. Please report any you find which can be fixed on our end.

• Updated the Sitegurus Tailwind Template with these newer versions of Flowbite and Tailwind CSS. https://github.com/SiteGurus/Siteglide-Tailwind-Template You can update your existing CLI setups using NPM

• Released eCommerce Layouts

  • Product List View

  • Product Detail View

  • Cart

  • Form Confirmation with embedded Order Detail

  • Orders List View (requires login)

• Form Layouts

  • New Form Layout with embedded Cart Layout, designed to be used with Checkout/ Quote type forms

    • Added better support for Stripe Form elements in dark mode

  • Added better Flowbite dark mode support for spinners on buttons

• standard Blog list view layout

  • Fix for author snippets links

  • Improved displaying user-feedback on filtering

• A new Flowbite eCommerce Site Template will follow shortly, demoing many of these new layouts.

4.9.5 - Released 22nd March 2024

• Fix for addresses in form layouts

4.9.4 - Released 21st March 2024

• Hotfix for bug in previous update

4.9.3 - Released 21st March 2024

• Form Layouts

  • Fix for eCommerce-themed Form type Layouts asking which Module you wish to use, instead of which CMS Form.

  • Module Add and Edit Layouts have been upgraded to better support Custom Modules from the Marketplace. This will work alongside an upcoming Siteglide release

4.9.2 - Released 20th March 2024

• Live Updates 1-4 hotfix - changelog

4.9.1 - Released 15th February 2024

• Hotfix for form layouts not working with the minified version of JavaScript files. This issue would only have affected more recent installs.

4.9.0 - Released 21st December 2023

• Support for upcoming eCommerce features- including new version of Live Updates 1.4.

4.8.12 + 4.8.13 - Released 11th December 2023

• Support for upcoming eCommerce features

4.8.10 + 4.8.11 - Released 4th October 2023

• Fix for broken links in the SiteBuilder UI

4.8.9 - Released 27th September 2023

• Fix for JIT Tailwind script not loading correctly after 4.8.8.

4.8.8 - Released 14th September 2023

• Live Updates v1-3

  • New version of Live Updates 1.3. Existing layouts can be updated by manually changing the <script>. New layouts will use the new version.

• Performance

  • All SiteBuilder JS, including Live Updates, now has a minified version of the same file in the same folder. Simply replace .js with .min.js extensions for a performance boost. This will be applied to new installs of layouts going forwards. If you're experiencing unhandled JS errors and want to report a bug, you may find it helpful to switch back to the unminified version temporarily.

  • Performance boost to the SiteBuilder module UI

4.8.7 - Released 9th September 2023

• Forms

  • Datasources in forms used to only show a maximum of 20 options. A lower value may have increased performance, but also reduced the user's choices arbitrarily. Now that limit has been increased to 2000 by default on both dynamic and static form layouts. You can change the default on dynamic layouts by setting a datasource_limit parameter to a string value e.g. '1000' on the form_layout_fields include. On static layouts, the per_page parameter can be edited on the nested <div data-gb-custom-block data-tag="include"></div> tags inside the layout which fetch the datasource options.

• Cookie Popup Layouts

  • Fixed bug preventing some layouts from hiding scripts when cookies rejected. Remember changes will only apply to freshly installed layouts. If you need to fix an existing layout manually, replace: <div data-gb-custom-block data-tag="if" data-0='all' data-1='all' data-2='all' data-3='all' data-4='all' data-5='all' data-6='all' data-7='all' data-8='all' data-9='all' data-10='all' data-11='all' data-12='all' data-13='all' data-14='all' data-15='all' data-16='all' data-17='all' data-18='all' data-19='all' data-20='all' data-21='all' data-22='all'></div> with <div data-gb-custom-block data-tag="if" data-0='sg-cookie-policy-settings' data-1='sg-cookie-policy-settings' data-2='sg-cookie-policy-settings' data-3='sg-cookie-policy-settings' data-4='] == ' data-5='] == ' data-6='] == '></div>

• Live Updates

  • Added support for using a code_snippet or content_section as your layout. A new parameter of include_id has been added to the live_updates_params_encode include to store the ID of the code_snippet or content_section. See: Defining a Live Update Layout

4.8.6 - Released 9th August 2023

• New version of Live Updates 1.2

4.8.5 - Released 3rd August 2023

• Fixed bug in Page Template install in Themes with no cookie popup option

• Fixed bug in Live Updates error handling

4.8.4 - Released 25th July

• Improved PageBuilder Options. You can now set custom pagination layouts in PageBuilder in the options drawer.

• Improvement to WebApp table layout so that if a category filter is added, it's possible to choose a parent category in a Liquid variable at the top of the wrapper. This means you can organise relevant categories in a folder and only show those.

• Improvement to Blog layouts using a grid where if few results, the cards would stretch to fill the space. Now they stay at the correct unstretched size.

• Blog, Events, FAQ and other list layouts replaced with upgraded Live Updates versions of themselves, for better user experience. When using new list layouts alongside a details page, set use_adv_search: 'true' on the list view's tag to instantly apply detail page filters when linking back. (See below)

• Fixed missing parameter range_field for live Updates API

• Live Updates API now has a new version of its JavaScript file, with added functionality. This will be included in many new SiteBuilder layouts by default, or you can optionally upgrade your existing layouts with the tag:

<script async src="{{'modules/module_86/js/v1-1/sitegurus_live_update_javascript_api.js' | asset_url }}"></script>

• Live Updates API now adds a click listener to text input fields. This helps to cover an edge-case where a cancel button is nested inside the text area to clear the field. Non-breaking change.

• New feature modifyHistory changes te URL to match fitlers without page reload - useful for shareable links and single-page applications

• New feature automatically launches a live-update on page load if any of the live-update form elemtns has a value.

• Improvement to error message when a Liquid error is detected in updated HTML.

4.8.3 - Released 21st June

• Fixed a rare bug relating to module API page templates conflicting with site page templates.

4.8.2 - Released 15th June

• Fix for live-updates issue where radio button element's value is read incorrectly when filtering.

4.8.1 - Released 25th May

• Fix for issue from 4.7.2

4.8.0 - Released 25th May

• Added layouts to Flowbite and Bootstrap Themes for:

  • Cookie Policy Popups

  • Cookie Policy Settings Pages

• These are examples of a brand new type of layout for SiteBuilder, as installing them creates a Siteglide code_snippet with a unique ID. More code_snippet layouts are now possible for SiteBuilder developers. Currently, these are not supported in PageBuilder.

• Page Template creation now gives you an option to install a cookie popup layout directly into your new Page Template. If chosen, this replaces the Google Analytics script which would normally be entered by default. The cookie popup layout contains the same Google Analytics script, but wraps it in logic which allows it to be toggled on and off by the end-user. Cookies settings page layouts are not designed to be entered in the Page Template and must be installed via the layouts tab instead.

4.7.3 - Fix to previous release

4.7.2 - Released 18th May 2023

• Added new setting in settings tab for TinyMCE API key. This allows layouts to dynamically fetch key from one place.

4.7.1 - Released 17th May 2023

• Flowbite table webapp layout now uses left-align for its table headers.

4.7.0 - Released 16th May 2023

• Improvements to forms

  • All form components to use the {{field_id}} (plus any appropriate suffix) for their ID, instead of name (same for label for attributes). This should simplify any JS or CSS referencing it.

  • All required fields will have an asterisk " *" added after their labels by default. This can be changed in components.

  • All inputs will be given data-attributes containing the text of their human-readable label data-sg-validation-label and the main field ID for their field data-sg-validation-id (note this may be different from the ID of the element if there are multiple form elements responsible for controlling a field, e.g. checkboxes). These can be useful when writing custom validation rules.

  • If the error message from Siteglide validation references a field by ID, we will change the error message to be more human-friendly. The default is a generic message asking the user to complete missing fields, but a commented out alternative allows you to print the human-readable name of the first missing field. Likewise, we've added a more human-friendly error message when a captcha fails. These messages can be edited in the form layout JS.

  • Improvements for Date, File and Image fields when marked as required.

  • Improvements for rich-text textarea type fields when marked as required.

  • Added minimum value to date fields so they do not add a date which is out of range of Siteglide's date field. Siteglide dates must be within the unix epoch.

  • Improved animation transition on form progress bars.

4.6.5 - Released 11th May 2023

• Improvement to Flowbite Login Form Modal Layout - Wider padding and more modern syntax to make it less prone to closing accidentally. This may still happen if the user clicks on the backdrop, but is less likely to happen when missing a click event aimed at an input.

4.6.4 - Released 11th May 2023

• Supporting the ability to more easily add a parameter to redirect the form to a custom URL. Set custom_form_redirect parameter on the top include form tag or the include form_layout_fields tag.

• Fixes for dark mode on some Flowbite Layouts

4.6.3 - Released 27th April 2023

• Hotfix for Rich Text fields not submitting correctly in forms

4.6.2 - Released 27th April 2023

• Fix for Flowbite Typography dark mode on Flowbite Layouts

• Improvements and fixes to Sitebuilder Forms:

  • Type date fields now show initial values correctly, in local timezone, the same as Siteglide Admin. They also have max-values which don't allow invalid unix timestamps and expiry date will default to the max timestamp.

  • Textarea fields are now passed data-sg-rich-text attribute if rich_text is selected in the Siteglide Admin

  • Textarea fields now have rich-text-editor support when rich-text is turned on. This feature is powered by TinyMCE and requires a free API key to be added to remove warning notice. View the docs to add your API key and modify the settings.

• Added experimental support for datasources on Flowbite Live-updates WebApp table layout. This outputs the names of data-sourced webapp items in the table-cell instead of IDs. In future, we'd like to optimise this for performance, for now, we recommend only using it on short lists.

4.6.1 - Released 26th April 2023

• Fix for SiteBuilder forms- datasource (single) fields in edit forms were not previously showing initial values correctly.

4.6.0 - Released 25th April 2023

• Launching the JS Live Update API - Making it quick and easy to live-update server-side code on the client side when users interact with it and its state changes.

• New Flowbite Page Templates now have the beta feature option to select an alternative Template structure suitable for Portals and Applications. This supports a Flowbite sidebar layout.

• Improvements and Fixes for some Form Layouts

  • Added a variant of the Flowbite multi-part form with full-width fields for use in smaller form sections.

  • Flowbite multi-part forms now fill the container height, making it more convenient to add them inside a grid.

  • Fixes for edit email & password functionality on Flowbite forms (Bootstrap Theme did not have the bug)

4.5.6 - Released 31st March 2023

• Fixes for some Slider Layouts

  • fixes layouts which were either missing the Liquid to load the JS, or using an older, less efficient, version.

  • fixes for layouts with broken image alt fields.

• Fixes for compatible Themes, such as Flowbite Pro.

  • Fixed bug when installing a detail layout from a compatible theme on PageBuilder, where that layout would be given a list view tag.

  • Fixed bug in WebApp Layout field mapping where layouts from compatible Themes were given the wrong field slots.

  • Fixed bug viewing layouts from compatible themes on Layouts tab when the same ID was used in different Theme namespaces.

4.5.0 - Released 16th March 2023

• Added support for WebApp Layouts. WebApp Layouts allow agencies to map custom fields from a WebApp to slots in the Layout, so Generalised Layouts can suit a range of specific use-cases.

• UI Improvements including Validation and Accessibility

• Added a range of WebApp Layouts to the Flowbite Library.

• More WebApp Layouts coming soon.

4.4.0 - Released 26th January 2023

• Support for Siteglide Slider Module

• New optional JS script for layouts implementing a slider effect

• Added Slider layouts to Flowbite and Bootstrap Themes

• Fix for some layout options in Page Builder

• Improvements to UI

4.3.0 - Released 6th January 2023

• Support for WebApp and Module item add, edit and delete form layouts.

• Support for WebApp and Module item add forms to PageBuilder.

• Updated documentation to explain the new reliable way to change the order of custom fields in dynamic form layouts.

• Changed default order for system fields in forms to be negative. This will affect existing sites, so be prepared to review these when updating the module:

  • name: -40

  • email: -30

  • password: -20

  • Categories: -10 It is possible to order custom fields so that they fall before, after or between these system fields.

• PageBuilder UI updated to guide the user to select Page Template and name before the Theme is locked-in.

• Form Layout progress bars only display while form is submitting, not before.

• Improvements to Form Layout Image and File fields.

• Fixes to SiteBuilder UI

4.2.1 - released 9th December 2022

• Changed Home tab video

4.2.0 - released 9th December 2022

• Added new home tab to Module UI

4.1.3 - released 7th December 2022

• Fix for some issues in the settings page

4.1.2 - released 30th November 2022

• Further Static Layouts Fixes

4.1.1 - released 30th November 2022

• Fix for Static Layouts from compatible Themes e.g. Flowbite Pro, so that the Theme does not need to be installed on a Page Template, only installed to the Site, before the Static Layouts appear.

4.1.0

• Adds tips when a user adds a Module Layout in Page Builder, or when a Module Layout is installed.

• Links to Siteglide Admin from the UI now open in the same tab to take advantage of faster loading speeds.

• Multiple UI styling and responsiveness fixes

4.0.4

• Form field labels on Static Layouts now support apostrophe characters.

4.0.2

• Improves reliability of installs of layouts from compatible Themes.

4.0.1

• Fixes install bug

• Reduces Module install time

4.0.0

• Adds support for agencies to add SiteBuilder content through creating modules in the Siteglide Marketplace. These modules can be of two types, Themes which add entirely new Themes to SiteBuilder, or can extend existing compatible Themes. Or functional modules which add new content to Siteglide and can include SiteBuilder compatible layouts to extend any existing Theme. Read more in the documentation.

• New module UI which aims to deliver a clearer starting point for new users and better defaults for more experienced users.

• hcaptcha support for forms. This allows you to use Siteglide's recommended spam protection method.

• Remove unwanted PageBuilder sections

• Liquid tag recommendations when creating layouts

• More Modules and Sub-modules supported

3.2.3 - released 13th October 2022

• Bug fix for Form Layouts to support HTML entities like ' in form config field options e.g. in checkboxes.

3.2.2 - released 22nd September 2022

• PageBuilder Safari bugfixes

3.2.1 - released 21st September 2022

• PageBuilder UI design Improvements

3.2.0 - released 21st September 2022

• Released PageBuilder, a brand new user-interface for quickly building a page from scratch using SiteBuilder content. Access this by clicking a library and scrolling down to PageBuilder.

  • Search for and apply an existing Page Template

  • Add as many sections as you like and choose whether to add static or dynamic layouts

  • Visually preview and choose layouts from the current SiteBuilder library.

  • Use the UI to select module specific settings to automatically add to the Liquid tags when we build the page

3.1.14 - released 14th September 2022

• Support for form fields for changing email and passwords.

3.1.13 - released 7th September 2022

• Performance upgrade when adding duplicate layouts to the same PageBuilder Page

• Added support for adding Detail Layouts. Tip: use item_ids to select a specific item's detail page

• Added Changelog to documentation

3.1.0 - released 2nd August 2022

• Added new contextual docs links

• Improved Page Template Creation wizard to add Header/ Footer options

3.0 - released 12th July 2022

• Introducing the Flowbite Library

The Pagination Include

This include was designed to keep SiteBuilder layouts tidy by abstracting common pagination logic out of layouts.

It can be used to determine where in the layout the pagination layout should be displayed. Just move the tag to where you need it.

The include is an alternative to the documented Siteglide feature How to Move Pagination; it just adds a few extra SiteBuilder features.

Important The include will only output pagination if the main Liquid tag has the parameters use_pagination: 'true' and pagination_layout set. Otherwise, it will do nothing.

Example

<section class="p-8">
  <!-- Main Layout here -->
  <!-- Use the below Liquid tag to choose where your pagination will be outputted -->
  {% include "modules\module_86\private\views\partials\front_end\includes\v1\pagination", live_updates: 'false', lock_per_page: 'true' %}
</section>

parameters

Versions

V1 - original release

The original logic inside the function is as follows. You can use this to make a copy and modify if you wish in your own layouts.

{% if live_updates == 'true' %}
  <div data-sg-live-update-component="pagination">
    <div data-sg-live-update-controls="pagination">
      {% if lock_per_page == 'true' or lock_per_page == blank %}<input type="hidden" name="per_page" value="{{per_page}}">{% endif %}
      <input type="hidden" name="show_pagination" value="{{show_pagination}}">
      <input type="hidden" name="pagination_layout" value="{{pagination_layout}}">
      {%- if _show_pagination == 'false' and pagination_layout != blank and pagination_layout != "default" -%}
        {%- include 'modules/siteglide_system/get/get_pagination', pagination_layout: _pagination_layout -%}
      {%- endif -%}
    </div>
  </div>
{% else %}
  {%- if _show_pagination == 'false' and pagination_layout != blank and pagination_layout != "default" -%}
    {%- include 'modules/siteglide_system/get/get_pagination', pagination_layout: _pagination_layout -%}
  {%- endif -%}
{% endif %}

HTML data-attribute markup

HTML data-attributes are a convenient way to configure the Live Update API JavaScript. We recommend using these in most use-cases. Unlike some JavaScript Libraries, it is possible to use data-attributes along with JavaScript methods without any known conflicts.

GET URL Parameters

The Live Updates API, at its core, sends requests to the server to fetch a new version of the HTML content. Therefore, this section shows you which parameters can be sent in this request to modify how the Liquid will be rendered in the next response.

Before reading this section, it will help to be familiar with the Siteglide documentation relating to the kind of Liquid tag you are intending to live-update- here are a few useful links, but you may need to browse further to find the feature you're working with:

• WebApp List Layouts Parameters

• Parameters for Search and Filtering

• Blog Archive

On the endpoint page we provide, the Liquid tag being live-updated is output.

In order to make the process of dynamically modifying the output simpler, we are basing the parameters for modifying it 99% on existing Siteglide functionality. We will update this module after new Siteglide functionality is released. We do have a few custom parameters with an sg prefix which can be used to modify module behaviour.

**While in Siteglide some parameters must be set via Liquid e.g. item_ids:

{% include 'webapp', id: '1', layout: 'default', item_ids: '1,2' %}

...and others via URL e.g. page:

<!-- URL: /webapp_1?page=2 -->
{% include 'webapp', id: '1', layout: 'default' %}

...when using the Live Updates API, you can set any parameter via our URL parameters alone, giving you direct and consistent control.

If you need to use a URL parameter which is missing from the table above:

• If Siteglide recognises it as a URL parameter which can modify results, you should be able to use it safely.

• If Siteglide requires the parameter to be added as a Liquid parameter to the main tag, please ask Sitegurus and we'll add support for it, if possible.

Live Updates Custom Parameters

The following parameters modify the behaviour of the API endpoint page:

Interactive Form Areas and Controls

In the last section, we detailed the URL Parameters which the API uses to request data. This next section will detail how you can set these paramters and allow the user to interact with the HTML to change these parameters.

Form Areas

By interactive form areas, we mean any area of the layout which contains filters, sorting controls, pagination controls or buttons designed to change the state of the layout, causing it to live-update in some way. It will most likely have a <form> tag in the DOM for semantic reasons, but this is not strictly necessary.

The data-sg-live-update-controls attribute marks an element as an interactive form area and the JavaScript will search the area for Form elements and custom buttons to which it can attach event listeners.

Using HTML Form Elements

Any HTML Form elements with a name attribute (including hidden inputs) inside this element will automatically have event listeners added to them watching for "keyup" or "change" events which will trigger a live-update with new parameters based on the name and values all HTML form elements inside.

For example, the following markup can be used to add the parameters &per_page=20 to the request URL, changing that parameter in the endpoint Liquid tag and live-updating the content with the parameter applied. The name attribute provides the parameter key and the value property provides the value:

<form sg-live-update-controls="results_per_page">
  <select name="per_page">
    <option value="10">10</option>
    <option value="20">20</option>
    <option value="50">50</option>
  </select>
</form>

Using the data-attributes and our automatic event listeners allows the user to modify multiple parameters at the same time. If you have filters for both category and colour, when the category filter changes, it will trigger a live-update of the content, but both the current values of the category and the colour inputs will be included in the request. Once the color filter is changed, it will in turn also include the category filter's current value in the request.

Keyup events, targeting fields in which the user will type, will be debounced so that keyup events don't cause disorientating changes too often. After the user pauses in typing, the live-update will take the latest values and trigger the live-update. Other events are set to update immediately.

Using Hidden HTML Form Elements

HTML Form Elements with the type="hidden" attribute will behave the same as other HTML Form Elements for the purposes of controlling the GET Parameters the API will use in its requests.

One common use-case for these is to use as "default" settings that will be needed in every request, despite any choices made by the user.

Live Updates Toggle Buttons

Markup

<button data-sg-live-update-control-params="/blog?range_gte={{month.start}}&range_lt={{month.end}}&range_type=month" data-sg-live-update-control-group="month">{{month.start | date: "%b" }}</button>

What Problems do our custom toggle buttons solve?

Often in Siteglide, modules will have a single button which triggers JavaScript which will need to change multiple parameters in the URL at once, for example the archive buttons on the Blog and Events Lists needs to change both the range_lt and range_gte parameters.

• An ordinary form control in HTML can have only one name, so is not suitable changing multiple parameters at once without some other supporting JavaScript.

• Radio buttons cannot be unchecked easily by the user. It is useful to be able to clear filters.

To provide a consistent, convenient solution to both these problems, we're including custom toggle buttons in our documented markup:

Markup rules:

• They must use the <button> semantic element.

• They must have a data-sg-live-update-control-params data-attribute. This stores an absolute or relative URL, or just the search parameters of a URL starting with a ?. When the button is pressed, the query parameters from the passed URL will be added to the request, along with parameters sourced from other form controls.

• Optionally they can have a data-sg-live-update-control-group data-attribute. This allows them to act as radio buttons within that group, with only one pressed at a time, however, with the important difference that it is possible to uncheck all of them. If you do not provide this attribute, the buttons will be considered to be in a group with all ungrouped buttons.

When a custom toggle button is pressed, we'll automatically add the data-attribute aria-pressed="true" to make the toggle button match accessibility guidelines. When unpressed, we will set aria-pressed to false. For sighted users, we strongly recommend adding CSS to make buttons with aria-pressed="true" look visually as if they are toggled, for example by changing colour. e.g. in CSS:

[aria-pressed=true] {
  outline-style: solid;
  outline-width: 1px;
  outline-color: #22d3ee;
}

At the time of writing, the newest version of Tailwind supports the variant aria-pressed:.

If using Flowbite, you can place a toggle component inside your button and modify it to use group-aria-pressed:; it can then show the toggled state of the parent button very clearly, using CSS only.

<button type="button" class="text-white bg-blue-700 hover:bg-blue-800 focus:ring-4 focus:ring-blue-300 font-medium rounded-lg text-sm px-5 py-2.5 mr-2 mb-2 dark:bg-blue-600 dark:hover:bg-blue-700 focus:outline-none dark:focus:ring-blue-800 group" aria-pressed="true">
  <span class="mr-2">{{month.start | date: "%B" }}</span>
  <div class="relative inline-flex items-center cursor-pointer">
    <div class="w-11 h-6 bg-gray-200 group-focus:outline-none group-focus:ring-4 group-focus:ring-blue-300 dark:group-focus:ring-blue-800 rounded-full dark:bg-gray-700 group-aria-pressed:after:translate-x-full group-aria-pressed:after:border-white after:content-[''] after:absolute after:top-[2px] after:left-[2px] after:bg-white after:border-gray-300 after:border after:rounded-full after:h-5 after:w-5 after:transition-all dark:border-gray-600 group-aria-pressed:bg-blue-600"></div>
  </div>
</button>

The special group data-sg-live-update-control-group="page" behaves uniquely, as the page will always reset to "1" when another change is made to the parameters elsewhere. For example, if you are currently on page 2, but a filter change means there is now only one result, staying on page 2 would mean the result was hidden- the special group behaviour avoids this problem. If there is no available page 1 button, all page buttons will be unpressed.

Live Updates Sort Buttons

Controls to handle the sorting of module or webapp data require a slightly different approach. Such buttons commonly have three different states- unpressed, sort ascending and sort descending.

We've therefore provided specific markup for a sort button.

<div>
  Weighting
  <button data-sg-live-update-sort-order="unsorted" data-sg-live-update-sort-type="properties.weighting" type="button" class="ml-1">
    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor" class="w-5 h-5">
      <path fill-rule="evenodd" d="M2.24 6.8a.75.75 0 001.06-.04l1.95-2.1v8.59a.75.75 0 001.5 0V4.66l1.95 2.1a.75.75 0 101.1-1.02l-3.25-3.5a.75.75 0 00-1.1 0L2.2 5.74a.75.75 0 00.04 1.06zm8 6.4a.75.75 0 00-.04 1.06l3.25 3.5a.75.75 0 001.1 0l3.25-3.5a.75.75 0 10-1.1-1.02l-1.95 2.1V6.75a.75.75 0 00-1.5 0v8.59l-1.95-2.1a.75.75 0 00-1.06-.04z" clip-rule="evenodd" />
    </svg>
  </button>
</div>

Markup rules:

• They must use the <button> semantic element.

• It is strongly recommended that the button be a child of the semantic <th> element.

• Requires the data-sg-live-update-sort-type attribute to be set to the name of the field you wish to sort by. As you would on a Siteglide Liquid parameter of the same name, you need to prepend with properties. for any Siteglide field. platformOS core fields like id, external_id, created_at, updated_at and deleted_at do not require the properties prefix.

1. Requires the data-sg-live-update-sort-order="unsorted" attribute to be set. There are three available states: 'unsorted', 'asc' and 'desc'. You should set most sort controls to 'unsorted', but may set one to be sorted 'asc' or 'desc' by default. If you do sort a column 'asc' or 'desc' by default, you should add the correct aria-sort attribute to the <th> ancestor element. For subsequent button interactions, our JavaScript will apply this aria-sort attribute for you.

2. In order to show changes of state in the buttons to sighted users, the buttons will change their innerHTML dynamically according to the sortHTML property of the initiated SitegurusLiveUpdate object. By default, the module will use a series of icons (with the default unsorted icon being used as a default state in the example below). There is no need to use icons; any HTML is valid. We'll explain how to change these defaults below the main example.

When a sort button changes state to either 'asc' or 'desc', all other sort buttons will be set to 'unsorted'. The main reason for this behaviour is that sorting by multiple parameters at once is not supported by Siteglide, although it is possible via graphQL.

Changing default HTML for each button state

See the Methods section for .setSortHTML(); and the instructions for using methods with data-attributes.

Live-Updating the Interactive Form Areas

Sometimes it is very convenient to make components which control live-updating, live-update themselves. A pagination <nav> is an excellent example, because the server can live-update this with the correct number of page buttons based on the new content.

It is not such a good idea to do this with some other form elements, like <input> tags, because the user will lose focus while typing and lose their progress. However, custom JavaScript may allow you to mitigate both of these problems.

When live-updating controls, here are a few general principals to improve the experience when using the API.

• Wrap the element which you are using to indicate the live-updated area (data-sg-live-update-component) around the element you are using as a form (data-sg-live-update-controls).

• Make sure that the layout returns the form element no-matter what the logic, even if it is empty. Otherwise there will be an error in the console as the API tries to match up between the new content and the DOM. For example, a pagination component should return the main element even if there are no results and no pagination buttons are to be shown.

  • This means the component must also wrap the Siteglide tag `

` as this will not render if there is no more than one page of results. * Make sure the user does not lose focus or the values of form elements they are in the middle of using.

Methods

The following guides show you how methods can be used, depending on your method of initialisation:

• Using methods after data-attribute initialisation

• Using methods after JS initialisation

Example of setSortHTML method:

instance.setSortHTML({
  unsorted: `<bold>Sort ASC</bold>`,
  asc: `<bold>Sort DESC</bold>`,
  desc: `<bold>Sort ASC</bold>`
});

changeStateOptions

• onlyUpdateComponent allows you fine control over which components should re-render on this update.

Example of changeStateOptions:

instance.changeStateTrailingDebounce(undefined,false,{
  onlyUpdateComponent: ['a','b']
})

<div data-sg-live-update-component="a">
  //Will re-render this time
</div>
<div data-sg-live-update-component="b">
  //Will not re-render this time
</div>

Events

The module JavaScript defines and dispatches the following custom Events. You can watch for these using ordinary JavaScript event listeners. Alternatively, you can use the callback functions on initialisation to achieve the same goal, but note that the callback functions are more appropriate for one-off functions for a particular live-update, while the events below are useful for code which should run every time.

Liquid Includes and Functions

• See Pagination Include for settings specific to live-update data-attributes.

Endpoint Logic Reference

This Section is included to provide useful information to advanced users and assist with troubleshooting. It may not be relevant to all users.

After the GET Request is sent with all of your chosen parameters, the context in which the new re-render of the Liquid is output is modified in the following ways:

1. The Siteglide Constants Liquid tag is run, unless the special sg_skip_siteglide_constants URL parameter is passed in. You can optionally experiment with this to improve server response time if the content you use does not require it.

2. The tag is given the Siteglide use_search and use_adv_search parameters set to 'true' automatically. This means that any URL parameters described in this set of documents will be allowed to manipulate the filtering Search and Filtering.

3. The {{context.params}} variables relating to the URL of the endpoint page are overwritten with those of the referring Page. This is to prevent any discrepancies in Layouts using them. Note we do not currently overwrite the {{context.location}} or {{context.headers}} objects, though future versions of this API might add an option to do this if requested.

4. There is no way to dynamically change the layout or the module/webapp id parameter- these are ignored. See "Thinking about Security".

5. The following params range_lt, range_lte, range_gt and range_gte are inspected. If they contain a date format which includes a dash - we convert them to the Unix timestamp which Siteglide expects and context.params is overwritten to reflect the new format. This allows you to skip the step of converting them in JavaScript from the value of a standard HTML field.

6. If the layout is a webapp layout and the type param is not set to "detail", we will add the use_wrapper: 'true' parameter to the Liquid tag. This means we only support WebApp list layouts with wrappers, as this allows them to be output self-contained. If you need to migrate an existing WebApp Layout to use a wrapper, you can see the differences here: WebApp List Layouts

7. Any custom parameters you wish to send over you can. These can of course be accessed in the logic of the layout itself under {{context.params}}.

8. The URL parameters in the table above are read and, if necessary, turned into variables which are passed directly into the Liquid tag as Siteglide parameters.

Using the JavaScript Initialisation

Constructor Arguments

The following arguments can be passed into the options Object as key:value pairs when initiating the new SitegurusLiveUpdate constructor.

e.g.

const instance = new SitegurusLiveUpdate({
  defaultParams: {per_page: '20'}
});

The dark_mode script is based on Flowbite's own documentation for dark mode. See . We include step 1 directly on your page template, as this needs to load immediately. Our JavaScript script implements step 3 from the documentation.

Usually added to:

Flowbite Theme Templates

Script code:

Example

Purpose

This function can be fed an order ID, perhaps from a URL and returns the details of the form submission which was made as the order was created. This is useful in order confirmations and order detail layouts.

The Sitegurus social sharing is a light wrapper around an open source JavaScript Plugin called Vanilla Sharing. It was added in order to save time and easily allow the functions to be implemented using data-attributes.

Normally included in

Layouts where sharing functionality is needed.

We use context.exports to make sure the script is only loaded once on the page:

Script Code

Usage

We use and power it using data-attributes, so this documentation is vital for understanding usage.

Add data-s-g-social-feature to a <button> element to make it a sharing button. The value of the attribute should be the name of one of the functions listed in the vanilla-sharing documentation, or you can also use data-s-g-social-feature="clipboard" which creates a button for copying the URL to the clipboard.

Add data-s-g-option-<option-name>="<option-value>" to the same element to add options from the vanilla-sharing documentation. Any array type options like data-s-g-option-hashtags="hashtag,hashtag2,hashtag3" should be given a comma-seperated string value and we'll convert these to an array for you.

The data-s-g-option-url is normally a required option and if you leave it blank, we'll default to the current page URL!

Full Twitter example: