Power Mode

Introduction to Liquid

If you want full control over the layout of your TwentyThree site and styling using CSS and JavaScript simply is not enough, you can edit the HTML markup generated for your video site directly using the Liquid templating language.

Liquid is a simple and fast templating language originally created by Shopify as an easy-to-learn and safe templating language. A lot of popular templating languages share a similar syntax, so if you have worked with templating languages before, you should feel right at home using Liquid.

Basic syntax

Liquid markup is written just like regular HTML markup with a few additions. The language offers two kinds of special markup: output blocks and tag blocks.

An output block is surrounded by two sets of curly braces and renders variables or constants into the HTML markup:

    {{ output block }}

A tag block is surrounded by a set of curly braces and percentage symbols and executes logic within the template:

    {% tag block %}

There are no restrictions as to where Liquid markup blocks can be put within HTML markup, but be wary of the possibility of inline JavaScript resulting in Liquid interpretation errors. It is generally recommended to keep all JavaScript in the site wide JavaScript file editable under Site Designer → CSS and JavaScript on your video site.

Output blocks

Output blocks render variables or constants into the HTML markup. Simple examples of output blocks are:

    Hello {{ name }}
    Hello {{ user.name }}
    Hello {{ "you" }}

Constants are basically variables written directly into the template like strings, numbers and booleans. In the example above, the string "you" is a string constant, which can also be written as "you". 23 and 23.0 are number constants. Boolean constants can have a value of either true or false.

Filters

Variables and constants can be manipulated using so-called filters. Filters are simple methods that takes the output on the left side of the filter and transforms it to a new value. If multiple filters are used, the return value of the previous filter will be used as the input value for the next filter until all filters have been applied. The final value is output to your markup.

For example, the following code:

    The word "video" in upper case: {{ "video" | upcase }}.
    The word "video" has {{ "video" | size }} letters.
    Change "hello, world" to "HI, WORLD": {{ "hello, world" | replace: "hello", "hi" | upcase }}.
    The date today is {{ "now" | date: "%Y %b %d" }}.

will result in this output: 

    The word "video" in upper case: VIDEO.
    The word "video" has 5 letters.
    Change "hello, world" to "HI, WORLD": HI, WORLD.
    The date today is 2012 Jan 05.

You can find a full list of filters in Liquid Filters.

Tag blocks

Tag blocks are logical blocks in your template. You can use tags to execute conditional logic, iterate through an array, assign new variables etc.

A full list of tags can be found in Liquid Tags.

Include templates

TwentyThree allows you to set up generic snippets of liquid called include templates. A template is simply a chunk of liquid code complete with variables, tags, and filters that can be included into floating layout blocks and static pages as needed. For example:

    {% for photo in photos %}
        {% include 'photo-thumbnail' %}
   {% endfor %}

Implementation details

Because Liquid was originally written entirely in Ruby, we have built a library to integrate Liquid with our own application framework. The result is an open-sourced, generic C++ library, open liquid, which currently offers simplistic bindings for Tcl. It can however easily be extended to be used with any variety of languages and runtimes like Python and node.js, although the current version of the library requires a POSIX compliant platform to be compiled.

The full source code along with documentation and a complete test suite is available on GitHub.

Can't find what you're looking for?