Components

A Box partial might need to include an external component.

You can place the component directly on the partial as you would in a standard October CMS theme. Unfortunately, with this method, some Life Cycle Limitations apply.

To circumvent this problem, Boxes allows you to place components directly on the CMS page or layout that renders the Box.

Adding components

To add a component to a Box, use the components key in your Box config.

components:
    aComponent:
        properties:
            id: 2
    aComponentWithAlias:
        component: aComponent
        properties:
            id: 4
    aComponentThatSupportsMultipleInstances:
        uniqueAlias: true
    aComponentOnTheLayout:
        addToLayout: true
        properties:
            id: 4
    aVerySimpleComponentWithoutAliasOrProperties: # The key itself is enough!

Using components

You can use registered components in your Box partials without any special code:

<h1>Team</h1>

{% component 'teamOverview' %}

Using multiple instances of the same component

In some cases, a component will be rendered multiple times in multiple boxes on the same page. In these cases, you need to make sure that the component's alias is unique.

By setting the uniqueAlias option to true, Boxes will add the Box's unique ID to the component's alias. The result will look like this:

contactForm8cxaFaDt

If the uniqueAlias option is enabled, you need to use the uniqueComponentAlias helper method on the box variable to get the correct alias when including the component in your partial.

Full example

YAML config for a component with a unique alias:

name: 'Contact Form Popup'
handle: contact-form-popup
components:
    contactForm:
        uniqueAlias: true

The component has to be included like this:

{% component box.uniqueComponentAlias('contactForm') %}

{# results in: #}
{# component 'contactForm8cxaFaDt' #}

Accessing Boxes inside the component

The Boxes plugin adds the two dynamic methods getBoxesPage and getBoxesBox to your component. You can use these inside the component's PHP code to access the Boxes models.

<?php namespace YourVendor\YourPlugin\Components;

use Cms\Classes\ComponentBase;

class SomeComponent extends ComponentBase
{
    public function onRun()
    {
        // Access the Boxes page where the component is rendered on.
        if ($this->methodExists('getBoxesPage')) {
            $boxesPage = $this->getBoxesPage();
        }

        // Access the Boxes Box where the component is rendered on.
        if ($this->methodExists('getBoxesBox')) {
            $boxesBox = $this->getBoxesBox();

            // Do something with the information, like overriding a property
            // only if the Component is rendered inside a Box.
            $this->setProperty('category_id', $boxesBox->some_selected_category_id);
        }

        $this->category = Category::findOrFail($this->property('category_id'));
    }
}

Note on ìnit()

The getBoxesPage and getBoxesBox methods will never be available in the init() method since October initializes the component before Boxes has a chance to add these methods.

To circumvent this problem, you can add an additional boxesInit() method to your component. This method is called right after October's native init() method but with the getBoxesPage and getBoxesBox methods attached.