Nesting

Bloqs 4.0 brings more control and structure to your bloqs by making them nestable. You can create a true heirarchial relationship between bloqs, and have them render as such in your templates. Your templates will remain largely the same. To start nesting just enable it on the field, and add an additional closing tag pair to each bloq as mentioned below.

Some basic nesting rules are also available that can be applied to each bloq.

  • Can be nested at any level

  • Can only be at the root

  • Can't be root and must be a child of another bloq

  • You can also define a bloq as must be a child of another bloq by selecting 1 or more possible parent bloqs

  • You can also define if a bloq is allowed to have child bloqs

While editing your bloqs you may see warning messages when one of these rules is violated, however, Bloqs will not stop an entry from saving if a nestable tree is invalid based on the rules you defined. It is up to the content editors to ensure the nesting is valid before saving an entry (no warning messages means it is valid). If an invalid bloq tree is saved, the bloqs will still be rendered in your templates, but they may not display as you expect them to based on nesting rules and the HTML and CSS defined for the bloq.

Enabling Nesting

All Bloqs fields default to the old sortable behavior. You must enable nesting on each field. If you want to use Bloqs, but don't need the nesting functionality, just don't enable the option and continue using Bloqs like you always have (you won't need the closing tag pair mentioned below).

Variables

If nesting is enabled, each bloq contains a few new variables:

{bloqs:parent:id}
{bloqs:parent:shortname}
{bloqs:children:total_bloqs} or {bloqs:children:total_rows}
{bloqs:siblings:total_bloqs} or {bloqs:siblings:total_rows}

Template Tags

When nesting is enabled, the templates expect that each bloq have its own closing tag. The contents of this tag will be moved to the appropriate location in the final template output to wrap child bloqs. If you create a "section" bloq that is the parent of several child bloqs, the closing content of the section bloq will be added after the child bloqs have been rendered to create a properly nested HTML structure. The closing tag is always the name of the bloq it is in, prefixed with "close:"

{bloqs_field}
{section_bloq}
<div class="section"}
<h1>{heading_atom}</h1>
{close:section_bloq}
</div>
{/close:section_bloq}
{/section_bloq}
{row_bloq}
<div class="row"}
{another_atom}
{close:row_bloq}
</div>
{/close:row_bloq}
{/row_bloq}
{/bloqs_field}

Bloq Variables

When a field is nestable, you have the option of prefixing your atom short names with bloq_var_. If an atom name has this prefix its value will be passed down to all child bloqs. The next bloq that contains the same atom at the same nesting depth, or higher, will have a new value, and thus pass it down to its children. In the example below the {bloq_var_columns} atom is defined on the Row bloq, which means its value is available in the Row bloq itself, and the Basic Content and CTA bloqs that are children of Row. Bloq variables only work with basic atom fieldtypes such as text, radio, or checkbox fields (or any fieldtype that outputs a simple string value). You can not use a Relationship field, or a 3rd party field such as Assets or Ansel as bloq variable.

If you use a bloq_var in a conditional, you will need to quote it, e.g. {if '{bloq_var_columns}' > 2}

Example Code

The following example code is used in this video demo.

{bloqs_field}
{section}
<div class="container">
<h1>{heading}</h1>
<p>{summary}</p>
{close:section}
</div>
{/close:section}
{/section}
{row}
<h2>{heading}</h2>
<div class="row">
{close:row}
<div class="col row-footer"><small>Some footer content at the end of each row</small></div>
</div>
{/close:row}
{/row}
{basic_content}
<div class="col col-{bloq_var_columns}">
<div class="basic-content">
<h3>{heading}</h3>
<p>{body}</p>
{close:basic_content}
</div>
</div>
{/close:basic_content}
{/basic_content}
{cta}
<div class="col col-{bloq_var_columns}">
<div class="cta">
<h4>{heading}</h4>
{close:cta}
</div>
</div>
{/close:cta}
{/cta}
{/bloqs_field}