Nested Boxes

For more complex layouts, it can be useful to nest Boxes in each other.

Enable nested Boxes

To allow nested Boxes, add the children: true value to the Box config.

handle: container-with-nesting
name: Container
children: true # add this

An "Add child to this Box" action will now appear in the Boxes editor if you use this Box.

Allow only specific Boxes to be added as children

In certain use-cases, you don't want a Box to have any other Box as a child.

You can set the children property to an array of Contexts. The Boxes Editor will only show partials with this context in the selection Modal now when adding a child.

# parent.yaml
handle: only-allow-special-children
children:
- special-children

The configuration above would only allow Boxes as children that are configured like this:

# child.yaml
handle: special-child-partial
contexts:
- special-children # this matches the "children" from the parent

Render nested Boxes

Call the box.renderChildren(context) method in your partial to render all child Boxes.

{# container.htm #}
<div class="container">
    {{ box.renderChildren(context) | raw }}
</div>

Controlling the loop output

If you need to add special markup around each Box, it is also possible to render the children manually. The renderMergeContext method has to be used to pass in the new loop variable to the rendered child Box.

<div class="container">
    {% for child in box.children %}
        <div class="child">
            {{ child.renderMergeContext(context, { loop: loop }) | raw }}
        </div>
    {% endfor %}
</div>

Rendering a single child

Using the box.renderChild() method, you can render a single child Box. The second argument is the index of the Box (0 = the first child Box).

<div class="container">
    <div class="first-box">
        {{ box.renderChild(context, 0) | raw }}
    </div>
    <div class="second-box">
        {{ box.renderChild(context, 1) | raw }}
    </div>
</div>