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.

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:

<script>
  if(!window.sitebuilderSwiperConfig ) {
    window.sitebuilderSwiperConfig  = {};
  }
  window.sitebuilderSwiperConfig[''] = {
    initiated: false,
    //Choose any configuration from the docs here: https://swiperjs.com/swiper-api
    config: {
      slidesPerView: 1
    }
  }
  if(typeof window.sitebuilderSwiperInit == 'function') {
    //In case script is loaded already. Run initiation again. Sliders in the config will only be initiated if initiated property is set to false.
    window.sitebuilderSwiperInit();
  }
</script>

  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swiper@8/swiper-bundle.min.css"/>
  <script async src="https://uploads.prod01.london.platform-os.com/instances/668/assets/modules/module_86/js/sitegurus_sliders_javascript_api.1.js?updated=1695044531"></script>

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:

window.sitebuilderSwiperConfig[''] = {
  initiated: false,
  config: {
    slidesPerView: 1
  }
}

This contains the configuration settings required to acheive the Swiper.js effects the layout has out of the box, but it can be edited as per the parameters in the Swiper.js docs.

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

Note that some properties, for example pagination, may require you to add markup to the HTML alongside your changes to the JS object.

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

Under the configuration, you can define a callback function in the onInit property. This will allow you to run your own JavaScript when you can be confident that the Slider has initiated. The function will provide you a reference to the initiated slider which you can use to run any methods from the documentation:

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

<button id="reset">Back to start</button>
<script>
  window.sitebuilderSwiperConfig[''] = {
    initiated: false,
    config: {

    },
    onInit: callbackFn
  }
  function callbackFn(instance) {
    //When the slider (stored in instance parameter) is ready, initialise the custom reset button.
    var btn = document.querySelector('#reset');
    btn.addEventListener('click', function() {
      instance.slideTo(0, 0.3, true);
    });
  }

</script>

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

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:

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

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

Using form elements

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:

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.

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

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: