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.
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.
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.
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 }}
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 }}
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.
{% 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 stringobj.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 %}
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.)
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 %}