Theme development with liquid templating

Themes control how the website is built and are written in HTML, CSS, javascript and Liquid as templating language.

It is possible to have multiple themes uploaded at the same time, but only one can be published. Themes can be duplicated, exported, imported and deleted.

There are several premade themes that are customisable with theme settings and theme code. Checkout our github for themes and components.

Code editor in Cradle CMS — Theme code editor view

The easiest way to modify and develop themes is with the built-in code editor. When the site is open it is best to work on a copy of the theme and publish when ready.

Themes can be imported and exported making it possible to work on a theme on a separate site and importing when the theme is ready.

Theme structure

A theme consists of six folders: layout, templates, snippets, components, assets and config. All files ending with .liquid can contain code evaluated server-side.

More about the implementation of Liquid templating with Cradle CMS.

Layouts

The layout folder will contain the main structure files for a website. Commonly two files are present here:

theme.liquid : default file when site is open.
restricted.liquid : default file when the site is closed.

Default layout

For open sites theme.liquid is the default layout file for the rendering of all pages for a website.

Example of barebones content for theme.liquid

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8" />
        <title>{{ site.name }}{% if meta.title != blank and meta.title != site.name %} | {{meta.title}}{% endif %}</title>	
        <meta name="description" content="{{ metaDescription | escape }}" />
        <meta name="keywords" content="{{ metaKeywords | escape }}" />
        <link rel="canonical" href="{{ canonicalUrl }}" />
        {% if template == 'index' %}
        <script type="application/ld+json">
            {% include 'structured-data' %}
        </script>
        {% endif %}
        {% include 'open-graph-tags' %}
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <link rel="stylesheet" type="text/css" href="{{ 'site.css.liquid' | asset_url }}"
        <link rel="stylesheet" type="text/css" href="{{ 'editor-styles.css' | asset_url }}"
    </head>
    <body id="{{ meta.title | handle }}" class="template-{{ template | replace: '.', ' ' | split: ' ' | first | handle }}">
        <header>
            <h1>{{ site.name }}</h1>
        </header>
        <main>
        	{{ contentForLayout }}
        </main>
        <footer>
            <p>Copyright &copy; - {{ site.name }} - All rights reserved</p>
        </footer>
    </body>
</html>

Using alternative layout

If a template (for example the product.liquid template file) has a specification {% layout 'alternative' %} for an alternative layout, in this case referring to a layout file named alternative.liquid.

Render witout layout

It is possible to render a template without the surrounding template.

{% layout 'none' %}
{{ product | json }}

Templates

The templates folder contains all the template files for the different context in the system and for a web site: index, page, blog, blogs list, article, 404 and search.

It is common to use several templates for the same type of object, for example themes usually contain a page.contact.liquid template that adds a contact form on the pages where the contact template is chosen.

For eCommerce the templates folder includes templates for collections, products as well as for customer accounts and checkout process.

Snippets

Snippets is a folder where code snippets can be stored. Snippets would be used for breaking out parts of the code for reoccurring parts or to make a main layout or template file easier to read.

Snippet in Cradle CMS code editor — Snippets can be edited in the code editor.

A typical reoccurring code snippet would be a article card that would be used for a blog section both on the index page and on the blog page. Whereas breaking out code for the header and footer would give an example of what would be broken out for decreasing the complexity of the main layout file theme.liquid.

Code reference for snippets

Components

The components folder holds the code for web components and is similar to snippets but intended to be rendered client side.

Reference components

Assets

Assets is a place to add CSS- and JS-files.

Media

All images uploaded in theme settings is saved in a media catalogue, this is not displayed in the code editor but will be exported.

Config

Themes comes with theme settings, where options for the theme is built in. These options can handle colors settings, uploading of logos and other website content, as well as, the structure of the site.

Working with theme settings

In the config folder the theme settings configuration file will determine the options in the settings and the data inserted is stored here as well.

The file settings.json will render the theme settings view which is customisable.

Reference for settings file

Add themes

Themes can be added by uploading a zip-file or installed from an URL.

Upload theme zip-file

In Themes admin view use the Import theme button located under the Unpublished themes heading to upload a zip-file stored locally in the computer. The uploaded theme will be added to the list of unpublished themes to the right.

Install theme from URL

Adding a theme from github with an URL

A URL from github can be used for adding a new theme. In the top right corder of the Themes view press Install theme and add the URL together with a name and a description.

Theme export

All themes can be exported from the Themes page in a zip-file.

The exported zip-file will include all files viewable in the code editor, as well as the media folder, where all the uploaded media is stored.

Theme updates

The themes we provide have continious updates for fixes, enhancements and to reflect feature updates on the software. As Cradle CMS & eCommerce is a self-hosted solution and there is theme code freedom the theme updates are in site owners control.

In a theme update the theme settings and media should be added from the old to the new theme

Steps to update the theme

Export old theme from the system.
Download new version of theme from Github.
In the new version add from old theme
1. Media folder and all the content
2. settings_data.json file in the config folder
Create a zip with the new theme and containing the content from the old theme
Upload the new theme to the system with Import theme (an imported theme will be added to the unpublished themes).
View the theme and publish when ready.

If the theme code was changed a diff is a good way to check to find the changes that should be added.