assign

Description

Used to assign a value to a variable.

Syntax

{% assign <variable_name> = <value> %}

Example

{% assign article = contents.news.first %}
{{ article.title }}
{{ article.body }}

block

Description

Blocks are regions of content that you may want to override in children pages. Their names are used to define the tabs in the backend and segment editable regions.

🚧

block are required for editable_* tags

editable_* tags (e.g. editable_text) must be contained within a block in order for them to work.

1080

Syntax

{% block <name> %}{% endblock %}

🚧

Use only letters and underscores in your block name

Using dashes or other symbols will break functionality.

Examples

Click file tabs to see how nesting of blocks works.

<div class="container">
  {% block 'main' %}
    <div class="left">
      {% block 'sidebar', priority: 1, short_name: true %}
        Sidebar content
      {% endblock %}
    </div>
    <div class="right">
      {% block 'container', priority: 2, short_name: true %}
        Container content
      {% endblock %}
    </div>
  {% endblock %}
</div>
{% extends 'index' %}

{% block 'main/container' %}
	I just want to override the container block in page2, thanks.
{% endblock %}

Options

NameTypeDescription
short_nameBooleanIn the back-office, use just the name and skip the name of the nested blocks.
default: false
priorityIntegerallow blocks to be displayed before others. Higher the priority is, higher the position in the select box is.
default: 0

capture

Description

Combine a number of strings into a single string and save it to a variable.

Syntax

{% capture <name> %}<text>{% endcapture %}

Example

{% capture full_name %}{{ person.first_name }} {{ person.last_name }}{% endcapture %}
{{ full_name }}

consume

Description

Read an external datasource (either JSON or XML), cache the content and allow you to iterate over the objects.

Syntax

{% consume <variable_name> from <url>(, <options>) %}
...
{% endconsume %}

Example

<p>
  {% consume api from "http://ip.jsontest.com/" %}
  My ip address is: {{ api.ip }}
  {% endconsume %}
</p>
{% consume blog from 'http://blog.locomotivecms.com/api/read/json?num=3&amp;type=text', expires_in: 3000 %}
{% if blog == null %}
  the Tumblr API seems to be broken now.
  {% else %}
    {% for article in blog.posts %}
      {{ article.title }}
    {% endfor %}
  {% endif %}
{% endconsume %}

caching

For the caching, the LocomotiveCMS engine uses the default Rails caching.

πŸ“˜

If you want to use the Redis cache store, please read this blog article.

Options

NameTypeDescription
expires_inIntegerDelay in seconds during the content will be cached. 0 means no cache.
usernameStringusername if the external API requires an HTTP authentication.
passwordStringpassword if the external API requires an HTTP authentication.

csrf_meta

Description

The csrf_meta tag gives the information the javascript code has to include for each AJAX POST request in order to prevent Cross-Site Request Forgery (CSRF) attacks.

By default, that protection is disabled in order to keep backwards compatibility with the existing public forms.

If you want to enable it, open your config/initializers/locomotive.rb file and toggle the csrf property on.

config.csrf_protection = true

Syntax

{% csrf_meta %}

Example

<html>
  <head>
  {% csrf_meta %}
  </head>
  ...
</html>

csrf_param

Description

Forms inside the Liquid templates, such as a contact form for instance, can be protected from Cross-Site Request Forgery (CSRF) attacks.

By default, that protection is disabled in order to keep backwards compatibility with the existing public forms.

If you want to enable it, open your config/initializers/locomotive.rb file and toggle the csrf property on.

config.csrf_protection = true

πŸ“˜

For AJAX requests, please consider the csrf_meta tag.

Syntax

{% csrf_param %}

Example

<form action="/contact">
{% csrf_param %}
...
</form>

cycle

Description

Output the next option in a group on each call.

Syntax

{% cycle <group>: <value_1>, ..., <value_n> %}

Examples

{% cycle 'group 1': 'blue', 'green', 'red' %}
{% cycle 'group 1': 'blue', 'green', 'red' %}
{% cycle 'group 2': 'blue', 'green', 'red' %}
{% cycle 'group 1': 'blue', 'green', 'red' %}
blue
green
blue
red

editable_control

Description

Editable areas contain content you want a user to be able to change. The content within the tag will be the default one.

In the back-office, the editable element will be found under the tab corresponding to the block wrapping it. It is possible to associate the element to another block.

The input field in the back-office used to edit the content is a select field.

An element can be inherited by children, each page keeping its own version of the content. However, in some cases, it may be a requirement to have the element to be editable in one place. If so, just set the "fixed" option to true.

Syntax

{% editable_control <name>(, <options>) %}<default value>{% endeditable_control %}

Example

{% capture menu_enabled %}{% editable_control "menu", options: 'true=Yes,false=No', hint: "Tell if the menu is displayed or not", priority: 1 %}
  false
{% endeditable_control %}{% endcapture %}

{% if menu_enabled == 'true' %}
  DISPLAYED
{% endif %}

Options

NameTypeDescription
optionsStringoptions are separated by comma and value/label by a the "equals" sign. Ex: v1=l1,v2=l2,v3=l3,..etc.
blockStringassociate the element with a block other than the current one.
fixedBooleanmake the element editable in one place. The default value is false.
hintStringtext displayed in the back-office just below the select field.
priorityIntegerused to position the file field in the back-office. Elements with the highest priority are displayed first.

editable_file

Description

Editable areas contain content you want a user to be able to change. The content within the tag will be the default one.

In the back-office, the editable element will be found under the tab corresponding to the block wrapping it. It is possible to associate the element to another block.

The input field in the back-office used to edit the content is a file field.

An element can be inherited by children, each page keeping its own version of the content. However, in some cases, it may be a requirement to have the element to be editable in one place. If so, just set the "fixed" option to true.

Syntax

{% editable_file <name>(, <options>) %}<default value>{% endeditable_file %}

Example

{% editable_file "banner", hint: "Upload a banner (perfect size: 300px by 100px)", priority: 1 %}
http://placehold.it/300x100
{% endeditable_file %}

Options

NameTypeDescription
blockStringassociate the element with a block other than the current one.
fixedBooleanmake the element editable in one place. The default value is false.
hintStringtext displayed in the back-office just below the file field.
priorityIntegerused to position the file field in the back-office. Elements with the highest priority are displayed first.
resizeStringif the file is an image, apply a transformation. See the resize liquid filter for more examples, and more supported options (like JPEG compression).

How to use editable image with a default value?

If you want to use a theme image as the default value of your editable file, you might be tempted to do this:

{% editable_file 'banner' %}{{ 'banner.png' | theme_image_url }}{% endeditable_file %}

Which won't work: editable tags can't include another Liquid tag.

So you need to pass the relative path of an image located in the public/samples directory of your Wagon site.

{% editable_file 'banner' %}/samples/banner.png{% endeditable_file %}

If you want to resize the image, the code should be as follows:

{% editable_file 'banner', resize: '2500x>' %}/samples/banner.png{% endeditable_file %}

editable_model

Description

The editable_model tags are used to display a short link to the content entries they reference in the live editing sidebar as described in this example:

1118

{% editable_model <model_name>(, <options>) %}
...
{% endeditable_model %}

Example

{% editable_model products, hint: 'some text' %}
  <ul>
  {% for product in contents.products %}
    <li><a href="{% path_to product %}">{{ product.name }}</a></li>
  {% endfor %}
  </ul>
{% endeditable_model %}

Options

NameTypeDescription
blockStringassociate the element with a block other than the current one. This determines what tab this tag's textarea appears under in the back-office.
hintStringtext displayed in the back-office right after the label of the content type.

editable_text

Description

The editable_text tags are placeholders for content that you want users to be able to edit through the back-office. They replaced the now deprecated editable_short_text and editable_long_text tags.

Users can change the content of an editable_text tag by going to the pages section of the back office, selecting the page on which the tag appears, and then selecting the tab which corresponds to the name of the block wrapping the tag. Each editable_text tag is represented by a textarea labled with the editable_text's name. When no text has been entered into the back-office, the content within the tags is displayed by default.

If a block containing an editable_text tags is inherited by child pages, these child pages each store its own version of content and can be edited separately. For cases requring a single version of the content to be used on all pages and editable in only one location (such as text in the header or footer of a site), make use of the fixed option described below.

{% editable_text <name>(, <options>) %}<default value>{% endeditable_text %}

Example

{% editable_text "sample_title", hint: "Description of this area." %}
Default Content
{% endeditable_text %}

Options

NameTypeDescription
slugStringSlug of the editable text.
By default, use the underscored version of the first param .
labelStringLabel of the editable text as displayed in the back-office.
By default, use a humanized version (no underscore, no hyphen, ...etc) of the first param.
blockStringassociate the element with a block other than the current one. This determines what tab this tag's textarea appears under in the back-office.
fixedBooleanmakes the element editable in one place. The default value is false.
formatStringaccepted values are html, markdown and raw. If set to html, content is not escaped and will be rendered as html. If set to raw, any html content will be escaped and rendered as text. The default value is html.
hintStringtext displayed in the back-office just below the textarea.
line_breakBooleanif true, the text is ouput inside <div> tags, which are displayed as blocks in HTML and will consequently be separate line from surrounding elements. If false, the text is output inside tags, which are displayed inline (so the text will not break to a new line). The default value is true.
priorityIntegerused to position the textarea in the back-office. Elements with the highest priority are displayed first.
rowsIntegerdetermines the height of textarea in the back-office, measured in rows of text. The default value is 10.

πŸ“˜

Using editable_text inside a html tag needs a work-around

Use {{ page.editable_elements.<your block path>.text }} inside your html tags and define the editable_text outside in a capture tag.

{% capture text %}
   {% editable_text "text", line_break: false, format: 'raw', rows: 1 %}
      Text
   {% endeditable_text %}
{% endcapture %}

<a href="{% path_to page %}" title="{{ page.editable_elements.<your block path>.text }}">
   {{ text }}
</a>

🚧

Using editable_text inside snippets

Although it may be tempting to use editable_text or any other editable elements within snippets, it is highly recommended to not doing it because it makes the content rendered by the engine not reliable. Make sure it is wrapped inside a block tag if you doing so.

extends

Description

🚧

The extends tag must ALWAYS be the first statement.

Set the layout of the current page. A page can be a layout for another page. The tag needs a single parameter which can take two values:

  • parent the layout for the parent url
  • some/page/path a specific pages layout

πŸ“˜

You do not need to close this tag.

Syntax

{% extends <fullpath_or_parent> %}

Examples

{% extends parent %}
{% extends 'support/index' %}

include

Description

Include sections of content you would like to repeat across the website. The optional with clause lets you specify a value which is bound to the snippet's name within the snippet's context.

The snippets are declared in the app/views/snippets directory, the snippet slug is the filename.

Syntax

{% include <name_of_the_snippet> %}
{% include <name_of_the_snippet> with <name_1>: <value_1>, ...<name_n>: <value_n> %}
{% include <name_of_the_snippet> with <object> %}

Examples

{% include 'footer' %}
{% include 'sidebar' with foo: 'bar' %}
{% include 'product_information' with product %}

link_to

Description

Return a html anchor to a given page or a content entry if the content entry owns a templatized page. The page is identified by its handle.

Syntax

{% link_to <object_or_page_handle> %}
{% link_to <object_or_page_handle> %}
<HTML>
{% endlink_to %}

Example

{% link_to some-page %}
{% link_to about-us %}
  <i class="icon-info-sign"></i> {{ target.title }}
{% endlink_to %}
<a href="/path/to/some-page">Some page title</a>
<a href="/path/to/about-us">
  <i class="icon-info-sign"></i> About us
</a>

locale_switcher

Description

Display the links to change the locale of the current page. The links are wrapped inside a DIV tag.

The link to the current locale owns the class current which makes it possible to customize through CSS.

πŸ“˜

Nothing will be displayed if you do not select at least 2 locales for your site.

Syntax

{% locale_switcher <options> %}

Example

{% locale_switcher label: 'locale', sep: ' - ' %}

Options

NameTypeDescription
labelStringtakes one of the following options: iso (de, fr, en, ...etc), locale (Deutsch, Français, English, ...etc), title (page title). By default, "iso".
sepStringpiece of html code separating 2 locales. By default, " | ".

model_form

Description

Display the form html tag with the appropriate hidden fields in order to create a content entry from a public site. It handles callbacks, csrf and target url out of the box.

Syntax

{% model_form <your model>, <options> %}<your html form>{% endmodel_form %}

Examples

{% model_form 'newsletter_addresses' %}
  <input type='text' name='content[email]' />
  <input type='submit' value='Add' />
{% endmodel_form %}
{% model_form 'newsletter_addresses', class: 'a-css-class', success: '/welcome', error: '/error' %}
  <input type='text' name='content[email]' />
  <input type='submit' value='Add' />
{% endform_form %}

nav

Description

Render a list of links pointing to your pages. You can specify a context from where the pages will be pulled out. The context takes the following values: site, parent or page.

Moreover, it is also possible to include the nested pages.

🚧

Your pages must fill 2 conditions to be part of the navigation: be published and be listed.

πŸ“˜

The order is based on the one you specify in your LocomotiveCMS back-office.

Syntax

{% nav <origin>(, <options>) %}

Examples

{% nav 'parent', depth: 1, no_wrapper: false, exclude: nil, icon: false %}
{% nav site, exclude: '\.*\-bottom', depth: 2, snippet: menu_entry %}
{% block misc_properties %}
  {% editable_text menu_teaser %}{% endeditable_text %}
  {% editable_file menu_image %}{% endeditable_file %}
{% endblock %}

[With a snippet]

nav tag in the page

{{ page.menu_teaser }}
{{ page.menu_image }}

snippet named "menu-entry"

Options

NameTypeDescription
depthIntegerhow many levels of children to display. 1 by default.
snippetStringname of the snippet which will be used to render a page entry. Optional.
no_wrapperBooleando not output the nav and ul wrapper tags. false by default.
excludeStringregexp string of slugs to be ignored.
iconStringouput a span to be used as an icon.
idStringcss unique identifier for the nav tag. "nav" by default.
classStringclass of the nav tag.
active_classStringname of the css class when the current page is the one in the menu.
bootstrapBooleanuse the twitter bootstrap classes. false by default

paginate

Description

The paginate tag is responsible for pagination within the LocomotiveCMS engine. It is currently applicable to the entries of content types.

It can be combined with the with_scope tag.

Syntax

{% paginate contents.projects by 10 %}
<loop>
{% endpaginate %}

Example

{% paginate contents.projects by 10 %}
  {% for project in paginate.collection %}
    {{ project.title }}
  {% endfor %}
{% endpaginate %}

Properties of the paginate object

NameTypeDescription
collectionArraylist of elements
current_pageIntegerthe index of the current page
previous_pageIntegerthe index of the previous page. Nil if there is no previous page
next_pageIntegerthe index of the next page. Nil if there is no next page
total_entriesIntegertotal number of entries
per_pageIntegernumber of entries per page
total_pagesIntegertotal number of pages
partsArraylist of all the parts which make up a good navigation for this pagination. Each element will have any of these three elements: title (String), url (String), is_link (Boolean).
previousStringurl to the previous page. Nil if there is no previous page
nextStringurl to the next page. Nil if there is no next page

path_to

Description

Return the link to a given page or a content entry if the content entry owns a templatized page. The page is identified by its handle.

Syntax

{% path_to <object_or_page_handle>(, locale: [fr|de|...], with: <page_handle>) %}

Examples

The path to my about us page: {% path_to about-us %}
The path to my about us page: /corporate/about-us
The path to my about us page: {% path_to about-us, locale: fr %}
The path to my about us page: /fr/corporate/a-notre-sujet
The path to my product with a page (fullpath: /featured-products/*) used as a template {% path_to product, with: 'featured-product-template' %}
The path to my product with a page (fullpath: /featured-products/*) used as a template /featured-products/slug-of-my-product

seo

Description

Output the meta tags and associated content for keywords and description. Depending on the current page, the following fallback is applied:

  • if the page is "templatized", check first for the keywords / description of the related content entry.
  • if the keywords / description of the page are filled up, use them.
  • finally, use those of the site if the previous objects failed to return non-blank keywords / description.

Alternatively, you can access the keywords and description directly from an object among those: site, page, content_entry.

{{ site.keywords }}
{{ site.description }}

{{ page.meta_keywords }}
{{ page.meta_description }}

{{ content_entry.meta_keywords }}
{{ content_entry.meta_description }}

Syntax

{% seo %}

Example

{% seo %}

session_assign

Description

Used to store in the session a key and its value.

Syntax

{% session_assign <key> = <value> %}

Examples

{% session_assign player_email = '[email protected]' %}
E-mail: {{ session.player_email }}
{% session_assign player_email = nil %}

with_scope

Description

The with_scope tag is used to filter a list of entries. The filter is applied directly to the MongoDB request which makes it very performant.

Syntax

{% with_scope <field_1>: <value_1>, ... <field_n>: <value_n> %}
<CODE>
{% endwith_scope %}

Examples

{% with_scope author: 'John Doe' %}
  {% for post in contents.posts %}
    {{ post.title }}
  {% endfor %}
{% endwith_scope %}
{% with_scope active: true %}
  {% paginate contents.projects by 10 %}
    {% for project in paginate.collection %}
      {{ project.title }}
    {% endfor %}
  {% endpaginate %}
{% endwith_scope %}
{% with_scope date.gt: today %}
  {% for event in contents.events %}
  ...
  {% endfor %}
{%endwith_scope %}
{% with_scope posted_at.gte: '2012/01/01', posted_at.lte: '2012/02/01' %}
  {% for post in contents.posts %}
    {{ post.title }}
  {% endfor %}
{% endwith_scope %}
{% with_scope price.lt: 42.0 %}
  {% for product in contents.products %}
    {{ product.name }}
  {% endfor %}
{% endwith_scope %}

{% with_scope price.lt: params.min_price %}
  {% for product in contents.products %}
    {{ product.name }}
  {% endfor %}
{% endwith_scope %}
{% with_scope started_at.lte: now, city: params.city, won: false, order_by: 'started_at.desc' %}
  {% assign prize = contents.prizes.first %}
{% endwith_scope %}
{% with_scope item: "fruit" %}
  {% for product in contents.products %}
    <li>
      {{product.name}}
    </li>
  {% endfor %}
{% endwith_scope%}

πŸ“˜

Pagination

If you need to paginate your results you'll need to wrap your pagination inside the with_scope tag.

{% with_scope item: "fruit" %}
  {% paginate contents.products by 10 %}
    {% for product in paginate.collection %}
      {{product.name}}
    {% endfor %}
  {% endpaginate %}
{% endwith_scope%}