Sections
Display a section
We offer three ways to display a section which should cover all the different cases.
Global Sections
Global Sections are used to display the same content across an entire site and are useful for elements like header, footer and nav elements.
Any section can be used as a Global Section by use of the global_section Liquid tag. Global Sections are best used on layout pages that other pages inherit from. The content of a Global Section will be shared across all pages that contain the global_section tag (or inherit from a page that contains the global_section tag).
Example
```liquid,liquid index.liquid {% global_section nav %}
{% sections_dropzone %}
{% global_section footer %}
Global Sections will be displayed on all relevant pages (pages on which the global_section tag has been placed or pages that inherit from such pages) in the Back Office page editor. An update to a Global Section on any of these pages will automatically apply to all pages that include that Global Section.
By default, Global Sections will appear at the top of the list of sections in the Back Office page editor. This behaviour can be changed via the placement parameter which is set on the global_section tag.
Example
<pre class="liquid"><p class="not-prose text-sm mb-2 font-medium text-gray-500 dark:text-gray-400">index.liquid</p><code class="block overflow-x-auto w-full"><span style="color: #8ec07c">{%</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #fb4934">global_section</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #fbf1c7;background-color: #282828">nav</span><span style="color: #fbf1c7">,</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #b8bb26">placement</span><span style="color: #fbf1c7">:</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #b8bb26;font-style: italic">'top'</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #8ec07c">%}</span>
<span style="color: #8ec07c">{%</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #fb4934">sections_dropzone</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #8ec07c">%}</span>
<span style="color: #8ec07c">{%</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #fb4934">global_section</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #fbf1c7;background-color: #282828">footer</span><span style="color: #fbf1c7">,</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #b8bb26">placement</span><span style="color: #fbf1c7">:</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #b8bb26;font-style: italic">'bottom'</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #8ec07c">%}</span>
</code></pre>
<div class="border-l-4 p-4 border-yellow-400 bg-yellow-50 dark:bg-transparent mb-4"><div class="flex"><div class="shrink-0 -translate-y-0.5"><i class="fa-solid fa-exclamation-triangle text-yellow-400"></i></div><div class="ml-3 text-sm text-zinc-900 dark:text-white dark:text-white prose-p:my-0"><p><strong>The <code>placement</code> parameter controls the display position of a Global Section in the Back Office</strong></p><p>It may seem unintuitive to control the position of a section in the Back Office via a Liquid tag parameter on a page. However, remember that the same section can be used as a Global Section <strong>and</strong> a Standalone Section <strong>and</strong> a Section in a DropZone.<br>
Setting the <code>placement</code> parameter on the <code>global_section</code> Liquid tag (as opposed to defining placement in the section definition) means that it only affects the instances of the section that are being used globally.</p></div></div></div>
Defining content in Wagon
The content comes from the global_content property in your section definition. global_content is an alias for the default property.\ <br/>
<hr/>
Standalone sections
Sometimes, because of how the design of the site has been thought, it doesn't really make sense to let the users add or remove sections.
That's why we provide the section Liquid tag.
Example
<div class="left-column">
{% section photo_gallery %}
</div>
<div class="right-column">
{% section text_image %}
{% section form %}
</div></code></pre>
<div class="border-l-4 p-4 border-blue-400 bg-blue-50 dark:bg-transparent mb-4"><div class="flex"><div class="shrink-0 -translate-y-0.5"><i class="fa-solid fa-info-circle text-blue-400"></i></div><div class="ml-3 text-sm text-zinc-900 dark:text-white dark:text-white prose-p:my-0"><p><strong>You can call the same section multiple times in a page</strong></p><p>Just simply pass an unique identifier to the <code>section</code> tag. Ex.: <code>{% section gallery, id: 'another_gallery' %}</code></p></div></div></div>
### Defining content in Wagon
In the YAML part of your page, just add the `sections_content` property. This property stores the content of your standalone sections in a JSON object. The keys are the ids of your sections.
<!-- tabs#0 -->
<hr/>
## Sections in a dropzone
Here lies the true power of sections!
To let your users add, remove, update and re-order sections in a page, just add the `sections_dropzone` Liquid tag in the template of your page.
In the editor UI, this will display a widget allowing your users to easily manage the sections.
<div class="border-l-4 p-4 border-yellow-400 bg-yellow-50 dark:bg-transparent mb-4"><div class="flex"><div class="shrink-0 -translate-y-0.5"><i class="fa-solid fa-exclamation-triangle text-yellow-400"></i></div><div class="ml-3 text-sm text-zinc-900 dark:text-white dark:text-white prose-p:my-0"><p><strong>Only sections which own a presets attribute will be available within the sections_dropzone</strong></p><p><code>dropzone_presets</code> is an alias for <code>presets</code>.</p></div></div></div>
### Example
<pre class="liquid"><p class="not-prose text-sm mb-2 font-medium text-gray-500 dark:text-gray-400">inner_page.liquid</p><code class="block overflow-x-auto w-full"><div class="page-sections">
<span style="color: #8ec07c">{%</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #fb4934">sections_dropzone</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #8ec07c">%}</span>
</div>
</code></pre>
### Defining content in Wagon
If there is no `sections_dropzone_content` property in your YAML header, no sections will be displayed within your `sections_dropzone` Liquid tag.
The **sections_dropzone_content** YAML attribute is a JSON array of objects. Each object owns 3 attributes: type, settings and blocks.
<!-- tabs#1 -->
<hr/>
## Section wrapping
LocomotiveCMS wraps sections when rendering the HTML. Depending on which Liquid tag you use to display your sections, LocomotiveCMS will use different strategies to wrap them.
In case of the `sections_dropzone` tag, two layers of DIV elements will be rendered:
* A single outer DIV will wrap all sections and will have `locomotive-sections` applied as the value in its class attribute.
* Within this, each section will be wrapped in its own individual DIV tag with `locomotive-section` applied as the value in its class attribute, as well as any values provided in the `class` attribute in the section definition. The id attribute of the DIV will be rendered `locomotive-section-dropzone-`with name of the section (or its id) appended. A data attribute, `data-locomotive-section-type`, will also be applied to this element.
Standalone and global section tags will only be wrapped within the individual DIV tag described above, with `locomotive-section` applied as the value in its class attribute, as well as any values provided in the `class` attribute in the section definition. The id attribute of the DIV will be rendered `locomotive-section-` with name of the section (or its id) appended.
<!-- tabs#2 -->
<div class="border-l-4 p-4 border-blue-400 bg-blue-50 dark:bg-transparent mb-4"><div class="flex"><div class="shrink-0 -translate-y-0.5"><i class="fa-solid fa-info-circle text-blue-400"></i></div><div class="ml-3 text-sm text-zinc-900 dark:text-white dark:text-white prose-p:my-0"><p><strong>Overriding section DIV elements</strong></p><p>It is possible to override the automatically generated individual DIV wrapper by including it in the section Liquid template. In this case, you must provide the necessary id, class and data attributes. For example:</p><pre><code><section id="{{ section.anchor_id }}" class="{{ section.css_class }}" {{ section.locomotive_attributes }}>
</code></pre><p><strong>Note:</strong> In this example the DIV element has been replaced with a SECTION element. The id, class and data attributes have been provided via the <code>{{ section.anchor_id }}</code>, <code>{{ section.css_class }}</code> and <code>{{ section.locomotive_attributes }}</code> tags, respectively. Additional values could be applied to the class attribute if desired.</p></div></div></div>
<br/>
<hr/>
## Block Nesting
Section blocks can be nested when the attribute `blocks_display` is set to `tree` and attribute `block_max_length` is set above the default `0`.
LocomotiveCMS will automatically handle the UI of block nesting in the **back-office** editor. Blocks can be nested simply by dragging a block to the right and dropping it under an intended parent block.
Section Liquid templates, on the other hand, require specific setup to display nested blocks. The default `for block in section.blocks` must be replaced with `for block in section.blocks_as_tree` and conditional statements must be added to check whether a block `has_leaves?`, i.e. whether the block has other blocks nested beneath it.
A picture paints a thousand words, but in this case, code...
### Example
<pre class="liquid"><p class="not-prose text-sm mb-2 font-medium text-gray-500 dark:text-gray-400">section_definition.liquid</p><code class="block overflow-x-auto w-full"><span style="color: #8ec07c">{%</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #fb4934">for</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #fbf1c7;background-color: #282828">block</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #fb4934">in</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #fbf1c7;background-color: #282828">section</span><span style="color: #fbf1c7">.</span><span style="color: #fbf1c7;background-color: #282828">blocks_as_tree</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #8ec07c">%}</span>
<span style="color: #8ec07c">{%</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #fb4934">if</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #fbf1c7;background-color: #282828">block</span><span style="color: #fbf1c7">.</span><span style="color: #fbf1c7;background-color: #282828">type</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #fbf1c7">==</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #b8bb26;font-style: italic">'container'</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #8ec07c">%}</span>
<div class="flex-container">
<span style="color: #8ec07c">{%</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #fb4934">if</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #fbf1c7;background-color: #282828">block</span><span style="color: #fbf1c7">.</span>has_leaves?<span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #8ec07c">%}</span>
<span style="color: #8ec07c">{%</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #fb4934">for</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #fbf1c7;background-color: #282828">_block</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #fb4934">in</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #fbf1c7;background-color: #282828">block</span><span style="color: #fbf1c7">.</span><span style="color: #fbf1c7;background-color: #282828">leaves</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #8ec07c">%}</span>
<span style="color: #8ec07c">{%</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #fb4934">if</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #fbf1c7;background-color: #282828">_block</span><span style="color: #fbf1c7">.</span><span style="color: #fbf1c7;background-color: #282828">type</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #fbf1c7">==</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #b8bb26;font-style: italic">'item'</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #8ec07c">%}</span>
<div class="flex-item">
<span style="color: #8ec07c">{%</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #fb4934">if</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #fbf1c7;background-color: #282828">_block</span><span style="color: #fbf1c7">.</span>has_leaves?<span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #8ec07c">%}</span>
<span style="color: #8ec07c">{%</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #fb4934">for</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #fbf1c7;background-color: #282828">__block</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #fb4934">in</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #fbf1c7;background-color: #282828">_block</span><span style="color: #fbf1c7">.</span><span style="color: #fbf1c7;background-color: #282828">leaves</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #8ec07c">%}</span>
<!-- etc, etc -->
<span style="color: #8ec07c">{%</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #fb4934">endfor</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #8ec07c">%}</span>
<span style="color: #8ec07c">{%</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #fb4934">endif</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #8ec07c">%}</span>
</div>
<span style="color: #8ec07c">{%</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #fb4934">endif</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #8ec07c">%}</span>
<span style="color: #8ec07c">{%</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #fb4934">endfor</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #8ec07c">%}</span>
<span style="color: #8ec07c">{%</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #fb4934">endif</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #8ec07c">%}</span>
</div>
<span style="color: #8ec07c">{%</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #fb4934">endif</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #8ec07c">%}</span>
<span style="color: #8ec07c">{%</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #fb4934">endfor</span><span style="color: #fbf1c7;background-color: #282828"> </span><span style="color: #8ec07c">%}</span>
</code></pre>
The above example is a very simple one. In practice, it will likely be more managable to use snippets for each block type. Snippets can be used recursively if blocks are passed using the `with` parameter, e.g. `{% include 'block-item' with: block: _block %}`.