Rendering CMS Content Using Liquid Templates

The features described here are an optional part of Rails Connector versions up to 6.9.1. If you wish to continue to use these features in later versions of the Rails Connector, you can find the corresponding source code in a Git-repository.

What is Liquid?

Liquid is a template language written in Ruby with a focus on security and robustness. Developing templates with Liquid is simpler than with ERB, leading often to a quicker implementation with less danger of errors occurring. In contrast to ERB, Liquid silently handles errors caused by missing custom fields or nil values, thus ensuring a graceful degradation.

The basics of writing templates in Liquid can be found on http://wiki.shopify.com/UsingLiquid, for example.

The Rails Connector expands upon Liquid's basic syntax in order to better handle displaying CMS content.

Displaying Content and Using Sub-Templates

The following Liquid code renders the title and main content for the current CMS object (represented by obj) and then invokes a sub-template:

<h1>{{ obj.title }}</h1>
{{ obj.body }}
{% template 'toclist' %}

obj is a Drop, which encapsulates an instance of the CMS object and controls access to the instance's methods and fields. The Drop automatically converts text to its HTML representation, resolves links, and inserts edit markers where applicable.

The following template renders a list of the subfolders and subdocuments (toclist) of a CMS object, if it is a folder. Each list element is displayed with its thumbnail image and its title as a link:

<ul>
{% for object in obj.toclist %}    
  <li>{{ object.thumbnail | image_tag }}
  {{ object.title | link_to: object }}</li>
{% endfor %}
</ul>

In this example, thumbnail images are referenced via a one-element link list named thumbnail and then displayed by the filter image_tag. The filter link_to is used to render an HTML link that points to the target CMS object.

Iterating over link lists can be done as follows:

<ul>
{% for link in obj.related_links %}
  <li>{{ link | link_to }}</li>
{% endfor %}
</ul>

If a link title has been specified, the link_to filter uses it as the text to be linked. If the link has no title, the filter uses the title of the target object if the link is internal. For external links, the URL is used.

Single links from a link list can also be accessed by their index:

{{ "A custom link text" | link_to: obj.related_links[2] }}

In the example above, the default link text is replaced with a custom link text.

Rendering Edit Markers Automatically

In general, editing elements are only displayed if the Rails application was configured for running in the editor mode, which should be the case if it is used as the CMS preview application. When using Liquid templates, the edit markers can be set either manually or automatically.

The standard practice is to enable edit markers by default. When the following code example is rendered in the preview, an edit marker appears automatically:

{{ obj.title }}

To provide for cases where for specific objects an edit marker is not desired, the filter editmarker can be used as follows:

{{ obj.title | editmarker: false }}

Rendering Edit Markers Manually

To deactivate edit markers globally for a Rails application, write the following in the application's configuration:

RailsConnector::Configuration.auto_liquid_editmarkers = false

This results in the following code no longer displaying an edit marker:

{{ obj.title }}

Yet again, the default behavior can be bypassed manually by using the editmarker filter as follows:

{{ obj.title | editmarker }}

Generating URLs for Content

The url filter can be used to retrieve the URL for a given CMS object.

external:{{ object | url }}

This is useful if a CMS object needs to be embedded into a page as Flash content or as a Java Applet.

Determining whether an Object Field has a Value

{% if obj.my_field != blank %}
  My field has the value {{ obj.my_field }}.
{% else %}
  My field has no value.
{% endif %}

In the above code, the else segment is evaluated if:

  • obj.my_field contains an empty string
  • obj.my_field == nil
  • obj doesn't have a field named my_field

For this reason, obj.my_field != blank is the best way to protect against empty field values.

A similar syntax, empty, can be used to explicitly check for empty strings and nil values:

{% if obj.my_field == empty %}
  My field contains an empty string.
{% endif %}

{% if !obj.mein_feld %}
  My field doesn't exist (== nil).
{% endif %}

Rendering Formatted Dates and Times

Date and time values can be formatted using the date filter (see http://wiki.shopify.com/FilterReference#date.28input.2C_format.29):

{{ obj.ip_eventStart | date: "%d.%m.%Y" }}

The following Liquid statement retrieves the object referenced by the named link my_name and returns its title:

{{ named_object["my_name"].title }}

In the CMS, named links can be stored in the relatedLinks field of a CMS file to which the NamedLink file format was assigned. With Rails Connector, the target object of a link in this link list can be referenced by specifying the title of the link.)

Providing Action Markers

Action markers can be used to offer access to menu commands and wizards in the inline preview. Using Liquid, an action marker that opens an image editing wizard, for example, could be provided as follows:

{% actionmarker obj.some_image editImageWizard %}
  [edit image]
{% endactionmarker %}