cms.utils

The cms.utils namespace provides helper functions for common tasks in Total CMS templates.

URL Helpers

urlFilters()

Reads URL query parameters and converts them into include, exclude, sort, and search options compatible with loadMore, loadMoreButton, loadMoreDataView, and any other function that accepts these filter options.

This allows visitors to filter, sort, and search collection content using clean, shareable URLs without any JavaScript.

Basic Usage

{% set filters = cms.utils.urlFilters() %}
{{ cms.render.loadMore('blog', {
    template: 'blog/card',
    include: filters.include,
    exclude: filters.exclude,
    sort: filters.sort,
    search: filters.search
}) }}

URL Format

Property filters use the parameter name as the field name and the value as the filter value.

The - prefix on a value means exclude instead of include:

?published=true&draft=-true
→ include: "published:true"
→ exclude: "draft:true"

Complete Example

Given this URL:

https://example.com/blog?category=travel&tag=-beach&sort=-date&search=adventure

cms.utils.urlFilters() returns:

{
    "include": "category:travel",
    "exclude": "tag:beach",
    "sort": "-date",
    "search": "adventure"
}

Array Values

Use bracket syntax for multiple values on the same field:

?tags[]=travel&tags[]=vacation
→ include: "tags:travel,tags:vacation"

You can mix include and exclude within the same field:

?tags[]=travel&tags[]=-beach
→ include: "tags:travel"
→ exclude: "tags:beach"

Custom Parameter Names

By default, sort and search are the reserved parameter names. You can customize these to match your URL scheme or localize them:

{% set filters = cms.utils.urlFilters({
    sort: 'orderby',
    search: 'q'
}) %}

Now ?orderby=-date&q=hello maps to sort and search instead of ?sort=-date&search=hello.

When you rename a reserved parameter, the default name becomes available as a property filter:

?sort=asc&orderby=-date
→ With {sort: 'orderby'}: sort="-date", include="sort:asc"

Ignoring Parameters

Some URL parameters aren't filters — like pagination or tracking IDs. Use ignore to skip them:

{% set filters = cms.utils.urlFilters({
    ignore: 'page,id,ref'
}) %}

Now ?page=2&id=abc&category=travel only produces include: "category:travel".

Options Reference

Combining with Hardcoded Filters

You can merge URL-based filters with hardcoded defaults using Twig's ~ operator for strings:

{% set filters = cms.utils.urlFilters() %}
{% set baseInclude = 'published:true' %}
{% set include = filters.include ? baseInclude ~ ',' ~ filters.include : baseInclude %}

{{ cms.render.loadMore('blog', {
    template: 'blog/card',
    include: include,
    exclude: filters.exclude,
    sort: filters.sort | default('-date'),
    search: filters.search
}) }}

This ensures published:true is always applied, while visitors can add additional filters via URL.

Building Filter Links

Create navigation links that set URL parameters for filtering:

<nav>
    <a href="?category=travel">Travel</a>
    <a href="?category=food">Food</a>
    <a href="?category=tech">Tech</a>
    <a href="?sort=-date">Newest First</a>
    <a href="?sort=title">A-Z</a>
</nav>

Or combine filters:

<a href="?category=travel&sort=-date">Latest Travel Posts</a>

Search Form

Build a simple search form that sets the URL parameter:

<form method="get" action="">
    <input type="search" name="search" value="{{ getData.search }}" placeholder="Search...">
    <button type="submit">Search</button>
</form>

Use with Other Functions

urlFilters works anywhere include/exclude/sort are accepted, not just with loadMore:

{% set filters = cms.utils.urlFilters() %}

{# With galleries #}
{{ cms.render.gallery('photos', 'main', {
    include: filters.include,
    exclude: filters.exclude,
    sort: filters.sort
}) }}

{# With RSS feeds #}
{{ cms.render.rssFeed('blog', {
    include: filters.include,
    exclude: filters.exclude
}) }}

{# With sitemaps #}
{{ cms.render.sitemap('blog', {
    include: filters.include,
    exclude: filters.exclude
}) }}