Quick Links

  • [assign](🔗)

  • [block](🔗)

  • [capture](🔗)

  • [consume](🔗)

  • [csrf_meta](🔗)

  • [csrf_param](🔗)

  • [cycle](🔗)

  • [editable_control](🔗)

  • [editable_file](🔗)

  • [editable_model](🔗)

  • [editable_text](🔗)

  • [extends](🔗)

  • [google_analytics](🔗)

  • [include](🔗)

  • [link_to](🔗)

  • [locale_switcher](🔗)

  • [model_form](🔗)

  • [nav](🔗)

  • [paginate](🔗)

  • [path_to](🔗)

  • [seo](🔗)

  • [session_assign](🔗)

  • [with_scope](🔗)

## assign

## Description

Used to assign a value to a variable.

## Syntax



## Example



## 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.

1080


## Syntax



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.



## 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



## Example



## consume

## Description

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

## Syntax



## Example



## 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.



## Syntax



## Example



## 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.





For AJAX requests, please consider the [csrf_meta tag](🔗).

## Syntax



## Example



## cycle

## Description

Output the next option in a group on each call.

## Syntax



## Examples



## 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



## Example



## 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



## Example



## 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 an transformation. See the resize liquid filter for more examples.

## 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:



**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.



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



## 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



## Example



## 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.



## Example



## 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 <span> 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.



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



## Examples



## google_analytics

## Description

It is simply a helper tag which includes the snippet code that it is asked by Google Analytics to enable traffic analytics.

Just provide your Google account id.



Put your google_analytics tag just before the closing BODY tag.

## Syntax



## Example



## 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



## Examples



## 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



## Example



## 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



## Example



## 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



## Examples



## 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



## Examples



**[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



## Example



## 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



## Examples





## 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.



## Syntax



## Example



## session_assign

## Description

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

## Syntax



## Examples



## 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



## Examples