Nesting

With Bloqs you can create true heirarchial relationships with your content, and have them render as such in your templates. 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

• Set a bloq as must be a child of another bloq by selecting 1 or more possible parent bloqs

• Set a bloq is allowed to have child bloqs

• Set a bloq as having a minimum, maximum, or exact number of 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.

When nesting is enabled you can choose to add a new bloq as an immediate child of the current bloq. Use the "Add bloq as child" to avoid excessive drag and drop of bloqs to build a nested structure. When nesting rules are applied, the menu respects those rules and will not let you insert a bloq where it does not belong.

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 {bloqs:children} tag. This tag will render all child bloqs of the current bloq recursively.

{bloqs_field}
    {section_bloq}
        <div class="section"}
            <h1>{heading_atom}</h1>
            {bloqs:children}
        </div>
    {/section_bloq}

    {row_bloq}
        <div class="row"}
            {another_atom}
            {bloqs:children}
        </div>
    {/row_bloq}
{/bloqs_field}

The following documentation about the {close:*}{/close:*} tag pairs is deprecated as of version 4.6.0, and completely removed in version 5.0. It will still work in future versions, but it will eventually be removed from the Bloqs codebase. For this reason, it is suggested to start using the new {bloqs:children} syntax noted above.

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>

            {bloqs:children}
        </div>
    {/section}
    {row}
        <h2>{heading}</h2>
        <div class="row">

            <div class="col row-footer"><small>Some footer content at the end of each row</small></div>
            {bloqs:children}
        </div>
    {/row}
    {basic_content}
        <div class="col col-{bloq_var_columns}">
            <div class="basic-content">
                <h3>{heading}</h3>
                <p>{body}</p>

                {bloqs:children}
            </div>
        </div>
    {/basic_content}
    {cta}
        <div class="col col-{bloq_var_columns}">
            <div class="cta">
                <h4>{heading}</h4>

                {bloqs:children}
            </div>
        </div>
    {/cta}
{/bloqs_field}

Another option to display child bloqs that was introduced in verison 5.0, is to use the {bloqs:child:[my_bloq_name]} tags instead of {bloqs:children}, which automatically iterates all the child bloqs and renders them. This is useful for when you need the output of children bloqs to display in a certain way, regardless of the order in which the children appear when editing the entry in the publish page. For example, the above code could also be the following:

{bloqs_field}
    {section}
        <div class="container">
            <div class="ctas">
                {bloqs:child:cta}
            </div>
            
            <h1>{heading}</h1>
            <p>{summary}</p>

            {bloqs:child:basic_content}
        </div>
    {/section}
    {row}
        <h2>{heading}</h2>
        <div class="row">

            <div class="col row-footer"><small>Some footer content at the end of each row</small></div>
            {bloqs:children}
        </div>
    {/row}
    {basic_content}
        <div class="col col-{bloq_var_columns}">
            <div class="basic-content">
                <h3>{heading}</h3>
                <p>{body}</p>

                {bloqs:children}
            </div>
        </div>
    {/basic_content}
    {cta}
        <div class="col col-{bloq_var_columns}">
            <div class="cta">
                <h4>{heading}</h4>

                {bloqs:children}
            </div>
        </div>
    {/cta}
{/bloqs_field}