Live Updates - Getting Started
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
The quickest way to get started with the SiteBuilder Live Updates API is to install a SiteBuilder layout which already uses it. Look out for the teal 'Live-updates ready' tag on the layouts, install and modify at will.
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.
{% comment %}Generate the public key as above and pass it to the main element of the HTML code as a data-attribite. Another data-attribute, data-sg-live-update-section, may optionally be used to supply a unique ID to the HTML section which will be referenced in the initialised Object.{% endcomment %}
{% if context.exports.sitebuilder.live_update_JS_loaded == blank %}
<script async src="{{'modules/module_86/js/v1-2/sitegurus_live_update_javascript_api.js' | asset_url }}"></script>
{% assign live_update_JS_loaded = true %}
{% export live_update_JS_loaded, namespace: sitebuilder %}
{% endif %}
{% function public_key = "modules/module_86/front_end/functions/v1/live_update_params_encode", layout: layout, model: _model %}
<section data-sg-live-update-key="{{public_key}}" class="bg-white dark:bg-gray-900">
<div data-sg-live-update-component="main_results">
{% comment %} This HTML tag and its contents are marked with the data-attribute as a component which will live update. {% endcomment %}
{%- include 'modules/siteglide_system/get/get_items', item_layout: 'item' -%}
</div>
<form data-sg-live-update-controls="sort_and_filters">
{% comment %} 1) Hidden fields {% endcomment %}
<input type="hidden" name="per_page" value="20">
{% comment %} 2) Ordinary HTML Form Elements{% endcomment %}
{% for category in context.exports.categories.items %}
<label>
<input type="checkbox" name="category" value="{{category[0]}}">
<span>{{category[1].name}}</span>
</label>
{% endfor %}
{% comment %} 3) Custom Toggle Buttons {% endcomment %}
{% assign month_start = 1682895600 %}
{% assign month_end = 1685574000 %}
<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>
{% comment %} 4) Sort buttons {% endcomment %}
<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>
</form>
{% comment %} Wrapping a component with aria-live alerts screen readers to changes in the number of results. {% endcomment %}
<div aria-live="polite">
<div data-sg-live-update-component="total_results">
{% capture exports_key %}webapp_{{id}}{% endcapture %}
{% assign per_page = per_page | default: context.params.per_page | default: 20 %}
{% assign total_entries = context.exports[exports_key].data.result.total_entries %}
{% assign total_pages = total_entries | plus: 0.0 | divided_by: per_page | ceil %}
{% assign current_page = context.params.page | default: 1 %}
<span class="text-sm font-normal text-gray-500 dark:text-gray-400">
Showing Page
<span class="font-semibold text-gray-900 dark:text-white">{{current_page}}</span>
of
<span class="font-semibold text-gray-900 dark:text-white">{{total_pages}}</span>
</span>
</div>
</div>
{% comment %} Our pre-built pagination solution when combined with a SiteBuilder pagination_layout which supports live-updates {% endcomment %}
{% include "modules/module_86/front_end/includes/v1/pagination", live_updates: 'true', lock_per_page: 'false' %}
{% comment %} A form example to allow users to change number of results per page {% endcomment %}
<form class="flex flex-wrap space-x-2 space-y-2 items-center" data-sg-live-update-controls="per_page">
<label for="rows" class="text-sm font-normal text-gray-500 dark:text-gray-400">
Rows per page
</label>
<select name="per_page" id="rows" class="bg-gray-50 border border-gray-300 text-gray-900 text-sm rounded-lg focus:ring-primary-500 focus:border-primary-500 block py-1.5 pl-3.5 pr-6 dark:bg-gray-700 dark:border-gray-600 dark:placeholder-gray-400 dark:text-white dark:focus:ring-primary-500 dark:focus:border-primary-500">
<option selected value="{{per_page}}">{{per_page}}</option>
<option value="25">25</option>
<option value="50">50</option>
<option value="100">100</option>
</select>
</form>
</section>
Step-by-step setup of a new layout
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.
{% if context.exports.sitebuilder.live_update_JS_loaded == blank %}
<script async src="{{'modules/module_86/js/v1-2/sitegurus_live_update_javascript_api.js' | asset_url }}"></script>
{% assign live_update_JS_loaded = true %}
{% export live_update_JS_loaded, namespace: sitebuilder %}
{% endif %}
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 'webapp', id: '3', layout: 'custom' %}or{%- include 'ecommerce/cart', layout: 'cart_custom' %}. - 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.
{% function public_key = "modules/module_86/front_end/functions/v1/live_update_params_encode", layout: layout, model: _model, collection: 'false', creator_id: nil %}
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 as well. For example, if you're using the tag: {%- include 'ecommerce/cart', layout: 'cart_custom' %}, then your public key function should look like this:
{% function public_key = "modules/module_86/front_end/functions/v1/live_update_params_encode", layout: layout, model: _model, model_type: 'ecommerce/cart', collection: 'false' %}
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:
{% function public_key = "modules/module_86/front_end/functions/v1/live_update_params_encode", model_type: 'code_snippet', include_id: '1' %}
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.)
<section data-sg-live-update-key="{{public_key}}" class="bg-white dark:bg-gray-900">
<!-- rest of layout markup goes here -->
</section>
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:
{% if context.exports.sitebuilder.live_update_JS_loaded == blank %}
<script async src="{{'modules/module_86/js/v1-2/sitegurus_live_update_javascript_api.js' | asset_url }}"></script>
{% assign live_update_JS_loaded = true %}
{% export live_update_JS_loaded, namespace: sitebuilder %}
{% endif %}
{% function public_key = "modules/module_86/front_end/functions/v1/live_update_params_encode", layout: layout, model: _model, collection: 'false', creator_id: nil %}
<section data-sg-live-update-key="{{public_key}}" class="bg-white dark:bg-gray-900">
<!-- rest of layout markup goes here -->
</section>
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).
<section data-sg-live-update-key="{{public_key}}" class="bg-white dark:bg-gray-900">
<form data-sg-live-update-controls="search">
</form>
<form data-sg-live-update-controls="filters">
</form>
<!-- rest of layout markup goes here -->
</section>
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.
<section data-sg-live-update-key="{{public_key}}" class="bg-white dark:bg-gray-900">
<form data-sg-live-update-controls="search">
<input name="keyword" placeholder="Search">
</form>
<form data-sg-live-update-controls="filters">
{% for category in context.exports.categories.items %}
<label>
<input type="checkbox" name="category" value="{{category[0]}}">
<span>{{category[1].name}}</span>
</label>
{% endfor %}
</form>
</section>
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 {%- include 'modules/siteglide_system/get/get_items', item_layout: 'item' -%}, which fetches our results, inside a new area marked as a component:
<section data-sg-live-update-key="{{public_key}}" class="bg-white dark:bg-gray-900">
<form data-sg-live-update-controls="search">
<input name="keyword" placeholder="Search">
</form>
<form data-sg-live-update-controls="filters">
{% for category in context.exports.categories.items %}
<label>
<input type="checkbox" name="category" value="{{category[0]}}">
<span>{{category[1].name}}</span>
</label>
{% endfor %}
</form>
<div data-sg-live-update-component="results">
{%- include 'modules/siteglide_system/get/get_items', item_layout: 'item' -%}
</div>
</section>
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:
- Check out the API Reference Guide each time you want to look something up.
- 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