Introduction

Add responsive, navigable sliders and carousels to your Site with SiteBuilder's layouts for the Siteglide Slider module.

We'll also add layouts with slider functionality to other modules, where suitable, and this document will also cover them.

Layouts Utilising the open-source Swiper.js Library

Any developer can contribute layouts to SiteBuilder, so it's possible to add slider layouts using any front-end JavaScript library.

Having said that, Sitegurus' preferred library for this functionality at the current time is Swiper.js and we'll be using it for slider-like layouts on all of the Themes which we contribute to.

Swiper.JS

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>

Copy

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
  }
}

Copy

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>

Copy

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

What is a Dynamic Layout in SiteBuilder?

In Siteglide Module and WebApp layouts are called dynamic, because their content will change when the data in the WebApp or Module's database table changes. They use the Liquid templating language to pull dynamic data from the database into the HTML so it will be visible and functional on the front-end of a website.

Dynamic Layouts in SiteBuilder are categorised so that it's clear which Siteglide feature they provide a dynamic layout for: e.g.

• Modules e.g. "Menu Module" and Sub-Modules e.g. "Headers".

• WebApp

• Forms

• Pagination

• Form Confirmation

When you're navigating PageBuilder and the Layouts view, you can filter by module to quickly find layouts depending on their functionality.

These categories are sometimes named "modules" in SiteBuilder because most are associated with a module available in the Siteglide Marketplace. Some modules in SiteBuilder e.g. Pagination and Forms do not correspond exactly to a specific Siteglide module, because they provide layouts for functionality which is built in to the Siteglide system.

Installing Dynamic Module Layouts onto your Site

Layouts in SiteBuilder often consist of multiple files. One of the benefits of SiteBuilder is that when you install a layout, we automatically create all the files you need in the correct folder structure. We also give you the recommended Liquid code needed to output the layout, though you may wish to modify this with additional parameters.

Note that the required Siteglide or Marketplace Module must be installed for any SiteBuilder module layouts to function correctly. However, you may install SiteBuilder module layouts first if you wish. Once the required module is installed, those layouts will be ready to use.

Head to the layouts tab in the Module navigation to find a wide range of layouts which can be filtered by Theme and by Module.

Finding more Module Layouts

Keep an eye out for new SiteBuilder compatible Modules and Themes which you can download from the Siteglide Marketplace. Once you install a module from the Marketplace, its layouts should appear.

Introduction

Form Layouts are designed to supercharge your experience of setting up forms in Siteglide with these key objectives:

• Get started quicker. No need to copy and paste fields from the default layout into a custom layout anymore in order to add styling. With a click, you can have a styled form layout ready to go.

• Get consistent styles across your forms - Form layouts are modular, using component layouts to style individual UI-controls. This makes it easier to apply consistent styles between your contact form and secure zone signup form without editing every line individually. Just add the code for each component to that form's layout once.

• Low Maintenance - No need to change your form layout every time a new field is added or removed in the Admin. By choosing the dynamic option, your layout will automatically adapt to any changes in the Admin and display them in the form.

Currently Supported Siteglide Form Features

These are the currently supported form features out of the box. Feel free to add more to your Static Layouts (see more about static vs. dynamic layouts below) and we may add more if there is popular demand.

Types of Layout

The Form Layouts are organised into sections based on the Siteglide feature they provide layouts for:

• CMS Forms

• WebApp Item Create Forms

• WebApp Item Update Forms

• Delete Forms

• Module Item Create Forms

• Module Item Update Forms etc.

Layout Installation

The Form layouts can be installed in the same way as other SiteBuilder layouts, but with a few differences:

Note that it's recommended to output Update and Delete Forms for WebApps and Modules inside a WebApp Layout so that they inherit the correct ID and other data. This is why these layouts are not available directly on PageBuilder yet.

Choosing a Form

Siteglide stores form layouts in folders according to their form ID e.g. form_1 or form_2. When you install a form layout, we ask you which folder you want to install the layout into based on the form_id/ name. If you are installing a WebApp or Module CRUD form, the ID of the WebApp or Module will be used instead.

With dynamic layouts though, the form is not restricted to working on a single one of your forms. A contact form layout can be copied and pasted into another form folder and will work out of the box. We'll look more at static vs. dynamic layouts next.

Static or Dynamic?

When you install a SiteBuilder form layout, you must choose whether you need a static or a dynamic layout.

In summary, the main benefit of dynamic layouts is that they take very little code maintenance compared to traditional Siteglide form layouts. All features are controlled via the Siteglide Admin.

The main reason to choose static forms might be if you want full control over the order of your fields or the functionality in your form. In this case, you're using the power of SiteBuilder form layouts to get you started fast, then you're able to change anything you like from there-on-out.

If you're not sure, why not start with dynamic form layouts, then switch to static form layouts if you need to later.

Editing the Layouts

All form layouts have a main layout file, or wrapper, which takes the name you gave the layout and a subfolder of component layouts named after the layout, but with _components at the end. See the example below:

This file structure will be exactly the same whether you opt for a static or dynamic wrapper. The main difference between the two types of form layout will be the contents of the wrapper.

Static Wrapper

A static wrapper contains <div data-gb-custom-block data-tag="include"></div> liquid tags for each component in your form and passes them the data they need via parameters. These parameters may appear to be hardcoded, however, it was dynamically generated at the time the layout was created by SiteBuilder- it will just need editing if there are any subsequent changes in Admin.

Alternatively, after making changes to the form configuration, you can always use SiteBuilder to re-generate a new version of the layout with a new name and new parameters.

Dynamic Wrapper

A dynamic wrapper does not include components directly; instead it includes this include tag which runs the dynamic SiteBuilder script for fetching the latest configuration of the form:

This tag can be passed parameters to modify its behaviour. Any of the parameters below can alternatively be added directly to the Siteglide `

` tag and the `form_layout_fields` include will inherit their values.

The collection Parameter

Setting collection: 'false' means the fields will be outputted in the HTML exactly in the place of the <div data-gb-custom-block data-tag="include" data-0='form_layout_fields'></div> tag.

Setting collection: 'true' allows you to re-position key groups of fields within your wrapper.

Outputting field groups on the page while using collection='true'

The available field groups are:

Siteglide and Custom Form Fields

This contains all Siteglide and all Custom Fields in the Form:

Hidden Fields

This contains hidden fields needed to run the form:

Address Fields

This is an array which contains all CRM addresses added to the form, if any are present:

The code here will loop over them all and output them all, but you can edit this if you want to display Billing and Shipping addresses separately.

reCaptcha

This contains the hCaptcha or reCaptcha, if present:

Note that Siteglide recommends using hCaptcha with forms. This file however, continues to be named reCaptcha for backwards-compatibility reasons.

Payment Gateway

This contains the payment gateway and payment fields, if present:

The disable_fields Parameter

disable_fields: can be passed a comma-separated string of field names to hide from the form. In the example above, the field called Name from the addresses is hidden.

The name field for the User's name and other mandatory Siteglide fields are exceptions. It cannot be removed from the form using this method.

The defer_fields Parameter

The defer_fields: parameter is useful where you want to use the advantages of dynamic form layouts for most of your fields, but also want to manually move a few key fields out of the main field output and into a separate section within the form.

To do this, first add the fields' names to a comma separated list in the defer_fields: parameter.

Then, you can output the individual field where you would like it using the following code:

In fact, the full range of deferred fields are available as an array here:

Developers can use this to loop over the fields if they wish. The additional filters in the example above help to find the item in the array with the field name you need, access the HTML needed to output the field and finally bypass platformOS's sanitization so that the HTML is output as intended (see Form Layout Sanitization section for details).

This feature could also be useful if you wish to hide and show some fields conditionally and therefore require greater control over these.

The hide_name_while_logged_in and hide_email_while_logged_in Parameters

These parameters exist primarily for the use-case of implementing a form with multiple parts or sections, where each section is actually a form in its own right. Siteglide mandates the inclusion of the name and email fields in every form that outputs, but this solution allows you to hide these fields on the 2nd, 3rd etc. sections of the form while the user is logged in and their values are auto-filled behind the scenes (and is still submitted along with the form). This use-case is demonstrated on the Flowbite Demo Site:

For both parameters, the default is 'false' and turning on the feature is 'true'.

If the user is not logged in, the fields will show as normal, as they are awaiting user input.

Important note: this functionality relies on the name_field and email components to contain code which will hide these fields, because the fields need to output, but hidden. If your component does not contain this code, you can add the example from below:

Parameters for editing email and password

Fields to edit email and password are not part of the Siteglide Form Configuration and are instead added by parameters.

Set include_email_editor to 'true' to include the edit_email component in the form.

Set include_password_editor to 'true' to include the edit_password component in the form.

Authorizing the Change

Including either of these parameters will also cause the current password component to display, as this is needed to authorise the change.

Validation

Siteglide provides server-side validation to ensure the security of this functionality.

On most form layouts we provide, the default behaviour for client-side validation is that if an edit_email or edit_password component is displayed on the form, it is required. This is the simplest behaviour to implement and makes sense if you have an account area with separate small forms for each possible action. If you have one large form and you want editing email/password to be optional, it might be sensible to add JavaScript to remove the required classes from the fields if they are empty, or to change this directly in the component layouts. You would also need to remove the required class from the password field in the situation that neither an attempt to change email, nor password was attempted.

Adding Confirmation Validation

Set confirm_email_password to 'true' and any email or password edit field will come along with a confirmation field for validation. This comes with client-side and server-side validation.

Troubleshooting Edit Email & Password

A form must have a secure zone set against it for this feature to work properly.

Editing Email & Password on Static Form Layouts

The custom_form_redirect parameter

This is a quick way to override the form_redirect path that's set in the Siteglide Admin for a specific form. One common use case would be to set the form to redirect to the current page:

Prior to v. 4.6.3 this was already possible in hidden fields, so this parameter just adds the convenience of setting this at a higher level in the code. It relies on the new versions of the form layout's hidden

Components

Components are files within the layout which are re-usable. This helps speed up development and achieve consistency as a string component need only have classes added once to re-style all <input type="text"> elements in the form. Components are used by both Static and Dynamic forms of each layout. Below is an example string.liquid component (the classList for the <input> has been simplified for the sake of readability!):

There is a component for each Siteglide field type that is available on standard forms. There are also components for additional features such as Secure Zones or eCommerce which can be used if required. Most layouts will include these extra fields as an option even if the layout design might not appear to need it, in case these are required in future. Once installed, the layout is yours and you can delete any components which are not needed.

Some Siteglide field types are available only for CRM fields at the moment. We will provide a component file for all of these, but it may be empty if we don't support that field type in your library yet.

The main components available are as follows:

More components may be added in future.

The main Liquid parameters passed into form layout components are as follows:

Re-ordering fields in a Dynamic Form Layout using Siteglide CLI

Using Siteglide-CLI, it is possible to give your Form's custom fields an order property. This will affect the order they appear in the Siteglide Admin, default form layout and SiteBuilder Form Layouts. For dynamic SiteBuilder form layouts, changes in order will appear immediately, however for static form layouts, the order will only affect the initial install of the layout.

2. Next find the table's JSON file. The tables directory is at marketplace_builder/views/partials/tables/. Within that, you can find directories for forms, webapps and modules, with each one containing files numbered by IDs.

4. (Optional) If you carried out step 3, minify your JSON file.

5. Sync the JSON file to the site.

6. Save the form in the Siteglide Admin. This copies the changes from the JSON file into the Form Configuration automatically. (Previously we recomended making changes to order in the form configuration directly, however, the method stated above is now the only reliable method.)

Default system field order

Since it is not currently possible to edit the orders of system fields e.g. name, email, using the above method, it's useful to note that we now assign default orders to these fields. We use negative values with large gaps between them deliberately, so that these fields default to the beginning of the form, but there is ample room for custom fields to be ordered before, between and after them.

• name: -40

• email: -30

• password: -20

• Categories: -10 (This refers to WebApp and Module item categories)

This is a breaking change in 4.3.0, so older sites which update to this version may need their fields re-ordered using the documented method.

Form Layout Sanitization

When outputting user-submitted values on a web-page e.g. the value attribute in a form field, there is a chance of a malicious user introducing executable code into that value by submitting it in a form field.

platformOS will automatically sanitize fields when values are outputted in {{ }} Liquid tags, unless the | html_safe filter is used. Since the html_safe filter is recommended in the main part of your Form Layouts, you may be re-assured to know that the value attribute will have been already outputted at the stage of your form components being rendered from Liquid to HTML by the server. This means the user-submitted values will have already been sanitized and you can use html_safe safely where we recommend it.

Enabling fields for controlling webapp visibility

On WebApps, fields like enabled, release_date and expiry_date were originally hidden away in hidden fields. We needed them to be there and inheriting default values, but didn't yet have UI support for them.

If you want users to be able to edit them, you can add custom code to the hidden field component and make them visible there.

Proper support for these fields will be added in a future update.

Modules and Dynamic Layouts

Once you've installed a Page Template, the other tabs will be available including the Layouts tab. Here you can toggle the Module on the right hand side and view all the different dynamic layouts available.

When you find a layout you want to use just click Add to Site, in the modal you will need to give the layout a name and there might be some additional settings to complete depending on the Module:

Once installed you can copy the include code that you just insert into your chosen HTML page.

You can insert it via CLI or via the Admin. Simply paste in where you want it to display:

Dynamic Form Layouts

A really powerful part of SiteBuilder is the Dynamic Form Layouts that automatically update to reflect any changes to forms. For example you could add or edit fields in the form and the layout will update automatically!

More information on Form Layout options with SiteBuilder:

More info on Dynamic Layouts:

Next Steps:

Want to add more Modules to your site?

Want to edit the Module Layouts themselves? We recommend doing this via CLI but you can also do it in Admin:

Static Layouts are sections of pre-built HTML code that you can add to your pages in the Siteglide Admin. They do not generally contain any Liquid templating, so won't pull in any dynamic content from the server or CMS. Instead, you can use Siteglide's Studio tab to edit their content directly in the page.

Insert Static Layouts from Studio Sidebar

Navigate to CMS > Pages, select a page and then from the right hand side bar you can click the blue button and insert various static layouts.

Insert Static Layouts From Other Sources

You can essentially use any TailwindCSS Layouts or code blocks. A few ideas of how to extend beyond the Layouts you'll find in Studio:

Ready to Install Dynamic Layouts?

Use Siteglide's prebuilt Modules (Blog, Events etc) or build your own with WebApps. SiteBuilder helps you quickly install layouts that will handle the dynamic code for you.