LocomotiveCMS

The Locomotive V4 Developer Hub

Welcome to the Locomotive V4 developer hub. You'll find comprehensive guides and documentation to help you start working with Locomotive V4 as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Definition

The definition of a section contains all the information regarding how your users will edit the content of your section.

Quick Example:

name: Hello world
icon: image_text
settings:
- id: title
  label: Title
  type: string
- id: background_image
  label: Background
  type: image_picker
blocks: []
{
  "name": "Hello world",
  "icon": "image_text",
    "settings": [
    {
      "id": "title",
      "label": "Title",
      "type": "string"
    },
    {
      "id": "background_image",
      "label": "Background",
      "type": "image_picker"
    }    
  ],
  "blocks": []
}

Section

Main attributes

In bold, the mandatory attributes.

Attribute

Description

name

Name of the section displayed in the back-office.

icon

Icon displayed in the back-office. Possible values: list, text, image_text, slide, header, footer.

class

The HTML code of a section is wrapped inside a DIV tag. class will be added in the list of CSS classes of the DIV.

keep_icon

Boolean to force the display of the icon in the editor instead of the first image setting. By default, false.

keep_name

Boolean to force the display of the section name instead of the first text setting. By default, false.

blocks_label

Label to display at the top of the blocks list in the editor.

settings

Array. See the settings chapter below.

blocks

Array. See the blocks chapter below.

presets

Only used if the section is aimed to be included in the sections_dropzone liquid tag.

default

Only used if the section is included thanks to the section liquid tag.

Settings

Settings are an array of objects with the following attributes (in bold, the mandatory attributes).

Attributes

Attribute

Description

id

Unique identifier of the setting. The id will be also used in the liquid template of the section in order to access this setting

label

Label to display in the editor

type

Type of the setting: text, image_picker, checkbox, select, url, radio, content_type, hint. See below for an explanation of each type.

default

Default value when the section is used as a global or stand-alone one.

only_if

Display the current setting only if the value of the field described by only_if is true.

Setting types

Type

Description

Options

text

Display a text input (simple or a rich text editor) in the back-office.

Texts can be edited with HTML by passing "html": true in the setting definition, this will enable severals format options in the editor.
You can choose
over

by using the "line_break": true option.
You can also choose the size of the text area as a number of rows: "nb_rows": 10

image_picker

Add an image picker to the editor.

You can add a cropper to let your users resize their image. To do so, add for instance "height": "100", "width": "100" to your settings to let the users crop images to any size with same aspect ratio (the image must be larger than 100x100).

We also implemented a new way of minimizing the weight of images. The process is done on the browser before sending the image to the server. To enable it, just add a compress attribute with the following allowed names: max_width (in px), max_height (in px) and quality (between 0 and 1).

checkbox

Display a checkbox in the editor. Values of the checkbox are true/false.

url

Add an url picker to the editor.

select

Add a select box to the editor.

radio

Display a radio button in the editor

content_type

Add a shortcut to the list of the entries of the content type specified by the id attribute of the setting.

hint

Use the label of the setting to display a help message to the users

Examples:

---
name: Kitchen Sink
settings:
- label: Title
  id: title
  type: text
---
<h1>{{ section.settings.title }}</h1>
---
name: Kitchen Sink
settings:
- label: Body
  id: body
  type: text
  html: true
---
<h1>Some text typed in a rich text editor</h1>
<div>{{ section.settings.body }}</div>
---
name: Kitchen Sink
settings:
- label: Image
  id: image
  type: image_picker
  compress:
    quality: 0.7
---
<h1>A cat?</h1>
<img src="{{ section.settings.image }}" />
<img src="{{ section.settings.image | resize: '60x60#' }}" />
---
name: Kitchen Sink
settings:
- label: Background image
  id: image
  type: image_picker
  height: '1920'
  width: '1240'
---
<div class="hero-with-banner" style="background-url: url({{ section.settings.image }})">
  <h1>My Hero</h1>
</div>
---
name: Kitchen Sink
settings:
- label: Call to action
  id: cta_link
  type: url
---
<a href="{{ section.settings.cta_link }} {{ section.settings.cta_link.new_window_attribute }}">Get started!</a>
---
name: Kitchen Sink
settings:
- label: Movie category
  id: movie_category
  type: select
  options:
  - label: Drama
    value: Drama
  - label: Fantastic
    value: Fantastic
  - label: Comedy
    value: Comedy
---
<p>Movie category: {{ section.settings.category }}</p>
---
name: Kitchen Sink
settings:
- label: Display title?
  id: has_title
  type: checkbox
---
{% if section.settings.has_title %}
<h1>My awesome site</h1>
{% endif %}
---
name: Kitchen Sink
settings:
- label: Season
  id: season
  type: radio
  options:
  - label: Winter
    value: winter
  - label: Spring
    value: spring
  - label: Summer
    value: summer
  - label: Autumn
    value: autumn
---
<p>
  {% case section.settings.season %}
    {% when 'winter' %}
    <img src="/samples/winter.png" />
  {% when 'spring' %}
    <img src="/samples/spring.png" />
  {% when 'summer' %}
    <img src="/samples/summer.png" />
  {% when 'autumn' %}
    <img src="/samples/autumn.png" />
  {% endcase %}
</p>
---
name: Kitchen Sink
settings:
- label: List of projects
  id: projects
  type: content_type
---
<h1>Nothing displayed, just a shortcut in the editor to the screen managing the projects</h1>
---
name: Kitchen Sink
settings:
- label: Title
  id: title
  type: text
  html: true
  line_break: true
---
<h1>{{ section.settings.title }}</h1>
---
name: Kitchen Sink
settings:
- label: Here is a help displayed in the editor
  id: some_help
  type: hint
---
<h1>Nothing displayed</h1>

Blocks

The blocks attribute of a section is an array of objects. Each object represents a different type of block.
In the editor, the users are able to fully manage the list of blocks: add, update, re-order, remove.

attributes

Attribute

Description

name

Name of the section. Not used in the editor

type

Type of the block. It's up to the developer to pick a meaning name. For instance, if blocks are aimed to display a slider, image_slide would be a good name for a block representing an image.

settings

Array of settings. See above the description of a setting.

Screenshot

Example

blocks:
- name: Menu item
  type: menu_item
  settings:
  - label: Title
    id: title
    type: text
    default: Item
  - label: Url
    id: url
    type: url
    default: "#"
{
     "blocks": [
    {
      "name": "Menu item",
      "type": "menu_item",
      "settings": [
        {
          "label": "Title",
          "id": "title",
          "type": "text",
          "default": "Item"
        },
        {
          "label": "Url",
          "id": "url",
          "type": "url",
          "default": "#"
        }
      ]
    }
  ]
}

Dropzone presets

LocomotiveCMS needs the presets to build the library of sections available for the sections_dropzone liquid tag.
You can also use the presets to define different versions of the section. The versions only differ by the content they offer.

🚧

In order to enable a section for the dropzone, the dropzone_presets (or presets) attribute is absolutely required.

Without this, you won't see your section among the list of available sections.

Attributes

The mandatory attributes are in bold.

Attribute

Description

name

Name displayed in the gallery of sections

category

A simple string. Sections have to be grouped inside categories.

settings

Basically an object whose keys are the setting ids and values are the content.

blocks

An array of objects. An object has 2 properties: type (based on the block types defined in the sections) and settings (identical as the settings attribute right above).

Example

dropzone_presets:
- name: Mixed slider
  category: Marketing
  settings:
    title: My slider!
  blocks:
  - type: image_slide
    settings:
      title: 'Slide #1'
      description: Lorem ipsummm
      image: "/samples/bg.png"
  - type: video_slide
    settings:
      title: 'Slide #2'
      video: "//youtube/cat.mov"
{
  "dropzone_presets": [
    {
      "name": "Mixed slider",
      "category": "Marketing",
      "settings": {
        "title": "My slider!"
      },
      "blocks": [
        {
          "type": "image_slide",
          "settings": {
            "title": "Slide #1",
            "description": "Lorem ipsummm",
            "image": "/samples/bg.png"
          }
        },
        {
          "type": "video_slide",
          "settings": {
            "title": "Slide #2",
            "video": "//youtube/cat.mov"
          }
        }
      ]
    }
  ]
}

🚧

Additional Notes

  • Only sections which contain a dropzone_presets attribute will be available within the sections_dropzone

  • dropzone_presets is an alias for presets

Default

If your section is standalone or global, it is recommended to add a default attribute to the section definition. Default is an object that can override settings' default and define some blocks to start with like the presets described above.

Example:

default:
  settings:
    title: Hero title goes here
    description: A description of the hero
  blocks: []
{
  "default": {
    "settings": {
      "title": "Hero title goes here",
      "description": "A description of the hero"
    },
    "blocks": []
  }
}

Updated about a year ago

Definition


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.