Nesting

Nestable Bloqs

Bloqs 4.0 brings more control and structure to your blocks by making them nestable. You can now create a true heirarchial relationship between blocks, 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 block as mentioned below.

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

  • Can be nested at any level
  • Can only be at the root
  • Can't be root and must be a child of another block
  • You can also define a block as must be a child of another block by selecting 1 or more possible parent blocks
  • You can also define if a block is allowed to have child blocks

While editing your blocks 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 block tree is saved, the blocks 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 block.

nestable-blocks.png

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

nestable-img.png

New Variables

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

{blocks:parent:id}

{blocks:parent:shortname}

{blocks:children:total_blocks} or {blocks:children:total_rows}

{blocks:siblings:total_blocks} or {blocks:siblings:total_rows}

New Template Tags and Variables

When nesting is enabled, the templates expect that each block 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 blocks. If you create a "section" block that is the parent of several child blocks, the closing content of the section block will be added after the child blocks have been rendered to create a properly nested HTML structure. The closing tag is always the name of the block it is in, prefixed with "close:"

{bloqs_field}
    {section_block}
        <div class="section"}
            <h1>{heading_atom}</h1>
        {close:section_block}
        </div>
        {/close:section_block}
    {/section_block}

    {row_block}
        <div class="row"}
            {another_atom}
        {close:row_block}
        </div>
        {/close:row_block}
    {/row_block}
{/bloqs_field}

Block Variables

When a field is nestable, you have the option of prefixing your field atoms with "block_var_". If an atom has this prefix its value will be passed down to all child blocks. The next block 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 {block_var_columns} atom is defined on the Row block, and its value is available in the Basic Content and CTA blocks that are children of Row. Block 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  block variable.

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-{block_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-{block_var_columns}">
            <div class="cta">
                <h4>{heading}</h4>

        {close:cta}
            </div>
        </div>
        {/close:cta}
    {/cta}
{/bloqs_field}