Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
You can now fully customise your Pagination controls, by building a Pagination Layout. Change Page with style.
Pagination is a catch-all term for the website User's ability to navigate through "pages" of results. It's available on all List Views including WebApps, Modules and Categories.
You can now also change the HTML structure of the Pagination controls with custom Layouts on most Siteglide Features. Unfortunately, custom Pagination Layouts are not yet available on Site Search Results, as the results contain items from several features, making Pagination more complicated to implement.
Furthermore, we provide you with Liquid variables detailing for example:
The number of available pages
The number of items per page
Whether a previous or next page exists
This can help you build more advanced designs which adapt dynamically depending on the data available. Examples of Pagination Layouts will soon become available on the Layout Library.
Developing a Pagination Layout can start simple, but many designs will involve complex elements. We'd recommend checking out our Design System examples when they become available on Layout Library. You could alter these, or use them for inspiration and start from scratch.
In order to make a Pagination control button functional, you need to refresh the current Page with a modified URL query parameter.
For example, if I'm on the "About" Page of my site, the URL will be: /about
, by default, this will show page 1.
If I want to send the User to Page 11, you'll need to add a page query parameter on the URL so that it looks like this: /about?page=11
You can do this with HTML, using the <a> tag: <a href="/about?page=11">11</a>
Or, you can use JavaScript to achieve the same effect.
This will change page for all Pagination controls on the Page, so currently it's best practice to only display one WebApp/ Module List with Pagination on the Page.
Within Pagination Layouts, the following variables will be available to give you contextual information.
current_page
-The current page (integer)
previous_page
- Designed to be used with a Prev button, its value is the previous page number (integer), or false (Boolean) if there is no previous page.
prev_path
- href for previous button
next_page
- Designed to be used with a Next button, its value is the next page number (integer), or false (Boolean) if there is no next page.
next_path
- href for next button
first_path
: href for first button
last_path
: href for last button
total_pages
: The total number of pages (integer)
page_search_params
: The preserved search terms in URL format- starts with & so can be added at the end of URL to new Page (?page=x
will already be added at the end of a URL, so a prevailing & is appropriate).
For example, you might have a button which will take Users to the next Page, but it might be helpful to know whether or not a next page exists (otherwise, the User will see an error when they navigate). Using these variables and a Liquid if statement, you can disable the button when the user is on page 1. In this example, we also use a variable from the above list to set the button's href
.
In order to give developers full flexibility, we've exposed the For Loop in Pagination Layouts. The reason for this is that you may not want to show all Pagination buttons at once, but instead only show a limited range of buttons.
If you're not familiar with Liquid For Loops, the following platformOS documentation might be helpful:
Objects - Many of these objects give helpful information within the context of a loop iteration.
Timezone is defined by the user's system setting.
If the user is in New York, all dates/times in Admin will show in their local New York time. However, any updates to data (release_date, custom dates, etc.) will be stored in the database as UTC no matter what.
This is possible because Admin runs off JavaScript, which is able to access the user's system settings and show them date/time in their local time.
Timezone is UTC always.
If the user is in New York, all dates/times front-end will still show in UTC.
This is because front-end runs off Liquid, which does not have access to the requesting user's system settings, so just runs off the default (UTC).
Developers could hardcode a Timezone in their date formatting scripts. For example, {{this.release_date | to_time: "America/New_York"}}
Similar to 'Hardcoded Timezone', but instead of hardcoded Timezone, developers could set up a Custom Field in their CRM for Timezone.
Then when that user logs in it will format all dates to that user's selected Timezone.
Note: Experimental
You can improve performance of your website by implementing caching on your Module/WebApp calls.
Add a new parameter to your Module/WebApp include of cache: 'true'
Caching works by generating a cache key. If the cache key value is the same each time the include loads, then the content will be loaded from cache. If that cache key value changes, then the content is loaded from the database.
The cache key is generated using the following information:
Module/WebApp ID
Most recent delete date of an item in the Module/WebApp - So when an item is deleted, the content is reloaded to remove it
Most recent update date of an item in the Module/WebApp - So when an item is updated, the latest version is loaded
Layout name - In case you have multiple calls to a Module/WebApp on a page, this ensures the different layout is loaded in the correct the place
URL parameters - This needs to be taken into account for when search is being used, so the content returned is the relevant results
This feature is new to Siteglide, and there are some situations where it may not work. For example:
We need to add more information to the cache key, such as sort_type
and per_page
It's unclear how this will perform if there's a lot of nested DataSources in the layout, or calls to other Modules/WebApps/data
Remove the cache
parameter, and you will revert to loading from the database each time
Get in touch, and we'll investigate why it didn't work for your use-case, and we'll then be able to apply improvements across the board to the feature.***
Caching is a good way to speed up Page load for most of your Users for a period of time.
When you load a Page, a key metric is Server Response Time- the time it takes for the Server to deliver an HTML Page to the browser. This can be slightly higher for a Page which relies on dynamic content, because the server has more work to do.
Caching is one way you can reduce this time for most of your users. There are a few different ways to cache Liquid, but here we will cover Fragment Caching, as it doesn't require Siteglide CLI and is the easiest to get started with.
Here's how it works:
The Developer implements Fragment Caching around a block of code which includes some Liquid.
When the next visitor arrives on the Page, it will load as normal, but a snapshot of that Liquid code (a cache) is taken by Siteglide. It is stored on the server with an expiry time and a "key".
The Cache remains in place until either the expiry time runs out or the Cache "Key" is changed. During that time, visitors to the Page will enjoy a faster experience- because instead of running the Liquid, the server will deliver the snapshot of HTML instead. This does mean that they won't receive any updates made to content while the Cache is active- we'll discuss this below.
Once the Cache expires, the next User to visit will have to wait for Liquid content to load and another Cache snapshot will be taken.
You'll need to create a Cache Key. This is a String that effectively names the Cache that is taken of your Site. Changing it will bust the Cache and cause a new Cache snapshot to be taken. The Liquid Capture tag just creates a String with the contents you include inside it, so you don't need quote marks. You can give the variable any name you like, so here I've gone for `my_cache_key
`
You can include dynamic content in your cache key- a really useful thing to do is to include the URL of your Page in the Cache Key. This will allow things like Pagination to bust the Cache and load a new one- without it, changing Page will keep loading the same content. This is the same for things like search queries. `
`
You can use the Cache tag to wrap the block of Liquid code that is slowing your Page down. You can wrap languages like JavaScript too, but it will have no effect on performance, as they will run on the Browser - long after the Cache has loaded.
Getting this right is a fine art. It really depends on your Site and what you are trying to achieve. An integer is needed to determine the number of seconds a Cache will be active for before it expires and a new Cache is made.
Set this as a large number of seconds (e.g. a day 86400) if:
Performance is essential to your Page's purpose
Content is not updated regularly
Lots of Liquid is used on the Page, especially several `` `
`` tags.
You have a low traffic rate- If only a few users visit each day, you will need a longer expiry in order for the difference to be noticed.
Set this as a small number of minutes (e.g. 60) if:
Content is regularly updated
You just want to protect against DDOS attacks or you have high traffic and want to improve the experience for a large number of users.
What if you want the Cache to last from a long time normally, but you want content to be updated immediately when there is an update to a key piece of dynamic content? You may even just want to bust the Cache while you are developing something.
To do this, you want to change the Cache key.
Let's say the Cache key is just the URL of the Site.:
<div data-gb-custom-block data-tag="capture">{{context.headers.PATH_INFO}}</div>
To bust the Cache manually, you can either:
Add a parameter to the URL - ?test=test
Change the Cache key e.g. add a number at the end.
<div data-gb-custom-block data-tag="capture">{{context.headers.PATH_INFO}}-1</div>
To change the Cache Key dynamically, add dynamic Liquid to the Cache Key, e.g. from a custom GraphQL query, a WebApp or a Module.
A demo of how you can convert dates from English to a different language
We can use Liquid to format our "raw" date integer to a formatted date. However, this doesn't give the option to select a different language when outputting the date. Here is one example of how you can do this using Liquid:
First, we will need to create an object of Months converted from English to whichever language you'd like:
Now we have an object called "months" storing all the translated Months, simply change "FRE" and the translation to whichever language you'd like.
Now we've translated the Months we'll need to check which one needs to be outputted. Firstly assign a variable with the Month you'd like to translate, I'd like to do so with my items "release_date":`
`
We use the "date" filter here to format the "raw" date integer to a humanized date. This follows Ruby's STRF format, read here for more info on formatting dates.
We'll use "%B", as this will store the Month as a String.
Now specify which language in "month_map" you're using, I've chosen French: <div data-gb-custom-block data-tag="assign" data-language='fre'></div>
Next, we'll use these two variables to search the "month_map" and return the translated Month: <div data-gb-custom-block data-tag="assign"></div>
Now we've found the translated Month we'll need to format it into a complete date, and then store this so it can be outputted:
We assign the Date and Year, formatting them into integer dates using the "date" filter, then we append the finished date to the variable "date_complete", you can output this like so: {{date_complete}}
Pagination refers to the process of assigning multiple pages to website content.
It is an important thing to consider when building a website, especially if you are fetching dynamic data from a database.
When you output a List Layout it will fetch results based on the parameters you've given it.
The parameter per_page
will decide how many items will initially display in the List. By default, this value will be 20.
If more results were fetched than the per_page
value, Pagination controls will be added to allow the User to change page and view the rest of the data.
Set the parameter show_pagination: 'false'
to remove pagination controls.
Firstly remove the default Pagination controls, as above. Secondly, add the following Liquid where you'd like the controls to sit within your HTML structure: <div data-gb-custom-block data-tag="-" data-0='modules/siteglide_system/get/get_pagination'></div>
Layouts for Pagination should be stored in Code Editor at the following path: layouts/pagination/my_pagination_layout_name.liquid
Site Search is an include you can add to your Pages to enable users to search Pages, WebApp items, and Module items for terms they're looking for. By default, this will now search slugs, metadata and Page content.
Site Search now has more configuration options to make searching your site more powerful. This document will cover the new toolbox options for setting up a Site Search.
There are two parts of Site Search which you'll need to include in a Site:
Search Input
Search Results
search_placeholder
- default is search - Placeholder value that displays in the input field.
result_page_url
- This lets you define the relative URL of the Page where the Search Results are included. This can be the current Page URL. (default: 'search-results')
search_input_class
- class on input field
input_id
- id on input field (default: 'site_search_field')
button_id
- id of the button you want to control submission (default: 'site_search_submit')
If you're using a button to submit your Input Form and there are multiple Input Forms within the same Page there are a couple of attributes you'll need to ensure are added.
You'll need to add the button_id
parameter to the include for Search Input and this must be unique for each Search Form:
Then add an ID to the button that submits your input, please match this to the ID within the button_id
parameter, for example:<button class="btn site_search_submit" id="id_1">Submit</button>
per_page
- default is 20 - defines the number of items outputted on the page
layout
- default is default - defines the layout file used to display the results
{{_all_results | size}}
can be used in the wrapper layout, and this will return the number of total results.
When selecting "Site Search Results" from the toolbox, you have the option of selecting which type of content will be contained within the results. Here you can mix and match whether you would like to display results from Pages, WebApp Detail Pages or Module Detail Pages. For example if you only want to search for Pages on the website then you could have the results exclude any data from WebApps and Modules.
To get results from WebApps or Modules, you must turn on Detail Pages in their configuration in Admin.
If you select WebApps as a Type, you then get a further configuration option to select which WebApps to search. The WebApps dropdown will display all of the available WebApps, this allows you to either select one or multiple WebApps to show results from. If you leave this field empty them the search will show results all WebApps on your Site.
Sometimes you may want to show results from WebApps without detail Pages- perhaps the relevant information is shown in a table instead?
You can add the parameter: allow_list_items: 'true'
and WebApp items without Detail Pages will also show in the results.
We strongly recommend that if you use this parameter, you also update your Site Search Results Layout so that it hides links to the Detail Page if one does not exist. You can use the following Liquid if statement to achieve this:
By default, results will appear in a list. You can change the way they display with a custom Layout.
Site Search Module layouts are stored in the following folder structure, which you can view via Code Editor: layouts/modules/site_search/
Within this module folder you will find the following layout folders:
results/
- the results layout folder
design_system/
- default design system layouts folder
item.liquid
- items displayed within the results wrapper
wrapper.liquid
- wrapper of the list displayed using the results
To create a custom layout, right click on the results folder and write a folder, followed by the two required files (item & wrapper).
For example, type: custom_layout_1/wrapper.liquid
to create a folder called "custom_layout_1" that contains a file called "wrapper". Right click on your "custom_layout_1" folder to create the final item.liquid file.
Pages, WebApp Items and Module Items may all output different Liquid. This is because they are different sorts of database Objects.
If your search covers more than one type, you may wish to only use output fields which are available to all those types, or you could use if statements to show one field or the other depending on which is available.
For example, if you have a Search Results Layout and you want to display the SEO Meta Title for Pages and WebApps, you can use logic to show whichever one is actually available:
You can also use the default filter: <p>{{this.metadata.title | default: this.properties.meta_title }}</p>
The following output is available for Pages.
{{this.id}}
- ID of the Page
{{this.name}}
- Page Name from Admin
{{this.slug}}
- Unique section of relative URL marked by forward slashes
{{this.redirect_to}}
- Siteglide-CLI only
{{this.full_slug}}
- URL
{{this.content}}
- Page content- this will include Liquid in its un-rendered state- rendering Liquid from Search Results is blocked to securely avoid injection attacks. This field is most likely to be used only in a filtered form, or as part of a Logical operation
{{this.metadata.id}}
{{this.metadata.name}}
{{this.metadata.enabled}}
{{this.metadata.file_type}}
- In most cases- this will show as Page
{{this.metadata.last_edit}}
{{this.metadata.meta_desc}}
{{this.metadata.meta_title}}
{{this.id}}
- ID of the WebApp Item
{{this.name}}
- Name of WebApp Item
{{this.model}}
- Shows that this is a WebApp Item and the ID of the WebApp
{{this.full_slug}}
- URL for WebApp Detail Page
{{this.properties.name}}
{{this.properties.slug}}
- The WebApp Item's Unique URL Slug- without the preceding URL slug which precedes all detail Pages for this WebApp.
{{this.properties.enabled}}
{{this.properties.release_date}}
{{this.properties.expiry_date}}
{{this.properties.og_type}}
{{this.properties.og_title}}
{{this.properties.meta_desc}}
{{this.properties.meta_title}}
{{this.properties.weighting}}
{{this.properties.twitter_type}}
{{this.properties.category_array}}
- Array of IDs for categories assigned to this Item
{{this.properties.webapp_field_1_1}}
- Custom Fields where the first number is the ID of the WebApp and the Second number the ID of the Field. The IDs are integers given to WebApps and Fields in the order they are created- you can work this out by looking at the list of Fields in the WebApp's Admin View.
{{this.id}}
-ID of the Module Item
{{this.name}}
- Name of Module Item
{{this.full_slug}}
- URL for Module Detail Page
{{this.model}}
- Shows that this is a Module Item and the ID of the Module
{{this.properties.name}}
{{this.properties.slug}}
- The Module Item's Unique URL Slug- without the preceding URL slug which precedes all detail Pages for this Module.
{{this.properties.enabled}}
{{this.properties.release_date}}
{{this.properties.expiry_date}}
{{this.properties.og_type}}
{{this.properties.og_title}}
{{this.properties.meta_desc}}
{{this.properties.meta_title}}
{{this.properties.weighting}}
{{this.properties.category_array}}
- Array of IDs for categories assigned to this Item
{{this.properties.twitter_type}}
- SEO Twitter Type
{{this.properties.module_field_1_1}}
- Custom Fields where the first number is the ID of the Module and the Second number the ID of the Field. The Module IDs are fixed for all Sites, for example, the Blog Module always has the ID of 3.
You can output the value of any URL parameter using platformOS's context.params
object, including the search term in the "keyword" parameter: <p>Search results for: {{context.params.keyword}}</p>
Both are available in and it is up to you whether you put them on the same Page or different Pages.
This will depend on the WebApp. to see the results for your WebApps. Here is an example of a typical WebApp.
This will depend on the Module. to see the results for your Modules. Here is an example of a typical Module.
platformOS tag output to escape any malicious input using the Cross Site Scripting technique.