Box Configs ​

Box configs are YAML files with the same name and location as a CMS Partial in your theme.

See YAML Schema for all available options.

Organisation ​

Folder structure ​

You can place your custom Box partials anywhere in your active theme's partials directory.

A best practice is to create a boxes sub-folder and place your partials there.

themes/your-theme
  partials/
    boxes/
      homepage/
        jumbotron.htm
        jumbotron.yaml
      generic/
        title-text-image.htm
        title-text-image.yaml
      _mixin_image.yaml
      _mixin_colors.yaml

Since every Box is referenced by its handle, you can move the files freely at any time.

Defining the Box config inline New in 3.2 (Experimental) ​

By default, the Box config is defined in a separate YAML file. It is also possible to define the config inside the partial itself. This is especially useful for simple use-cases.

To do so, place your YAML structure at the beginning of the partial. There are two rules to follow:

1. The handle property must be the first line of the file.
2. The partial must be stored in the theme/<your-theme>/partials/boxes directory.

handle: single-file-box
name: 'Single File Box'
form:
    fields:
        title:
            label: Title
            type: text
==
<div>
    <h1>{{ box.title }}</h1>
</div>

You can still use the PHP code section and place components on the partial.

handle: single-file-box-with-component
name: 'Single file Box with Component and Code'
form:
    fields:
        title:
            label: Title
            type: text

[section related]
handle = "Blog\Post"
==
function onStart()
{
    // Do something.
}
==
<div>
    <h1>{{ box.title }}</h1>

    {% for post in related.get() %}
        ...
    {% endfor %}
</div>

Handle ​

The handle property is the only required property of a Box config.

The handle has to be a unique string, other than that, there are no strict rules.

It is suggested to define handles in a homepage-jumbotron or homepage\jumbotron format, but you can use whatever fits your project's requirements.

Section ​

To group Boxes into sections (like Homepage, Text or Layout) a section key can be defined in the Box config.

Boxes with the same section are displayed together in the Box selector of the Boxes editor.

If no section is defined, Common will be used.

handle: jumbotron
section: Homepage

Dynamic Labels ​

You can specify a dynamic label using the labelFrom property.

If it is set, the Boxes Editor will use the value from the specified field as the label for this partial in the Structure section. This is useful on pages that use the same partial multiple times.

If the specified field is empty the partial's name will be used as fallback.

handle: box-with-dynamic-label

name: Default name
labelFrom: title # use the "title" as label in the Boxes Editor

form:
    fields:
        title:
            type: text
            label: Title # the value of this field will be used
                         # as the label for this partial in the
                         # Structure section

Icon ​

Use the icon property to define a custom icon for the Box selector in the backend.

The path to the icon needs to be relative to the site's base path.

handle: box-with-custom-icon
icon: /plugins/offline/boxes/assets/img/boxes/image.svg

Mixins ​

Mixins allow you to re-use common YAML structures in your Box configs.

The filename of a mixin has to start with _mixin but can be placed anywhere in the partials directory of your theme.

A mixin needs a handle and a mixin property, which holds the parts you want to re-use.

# _mixin_base_fields.yaml
handle: base-fields
mixin:
    font_size:
        label: Font size
        type: dropdown
        options:
            sm: Small
            md: Medium
            lg: Large
    color:
        label: Color
        type: colorpicker

You can then use the special mixin type anywhere in a Box config to include these shared structures:

handle: mixin-example
name: 'I am composed using mixins'
form:
    fields:
        base-fields: # this references the handle above
            type: mixin
        title:
            label: Titel
            type: text

This example would result in the following output:

handle: mixin-example
name: 'I am composed using mixins'
form:
    fields:
        font_size:
            label: Font size
            type: dropdown
            options:
                sm: Small
                md: Medium
                lg: Large
        color:
            label: Color
            type: colorpickere
        title:
            label: Titel
            type: text

Tab attribute for mixins ​

The tab attribute that is defined on a mixin will be applied to all fields of the mixin.

This allows you to use a mixin in different contexts without having to hard-code a tab name in the mixin.

handle: mixin-example
name: 'I am composed using mixins'
form:
    tabs:
        fields:
            base-fields:
                type: mixin
                tab: My Special Tab # will be applied to all fields in the base-field mixin

Placeholder Previews ​

When a user adds a new Box to a page, a preview of the Box is shown in the editor.

To disable the preview for a single Box, set the placeholderPreview property to false.

handle: box-without-placeholder-preview
name: 'I do not have a placeholder preview'
placeholderPreview: false
# ...

To disable the preview feature for all Boxes completely, set the BOXES_PLACEHOLDER_PREVIEWS_ENABLED configuration option to false.

Example Data ​

By default, the preview will display each field's label as "data". You can customize this by defining an example property on each field.

You also have access to the Faker library to generate random data. Pass any Faker formatter name as a string to the fake property and optionally define an array of arguments using the args property.

To opt-out of example data generation for a specific field, set the example property to false.

handle: example-data
name: 'I use example data'
form:
    fields:
        title:
            label: Title
            type: text
            example: 'An example title'
        text:
            label: Text
            type: textarea
            example: # translates to fake()->paragraphs(3)
              fake: paragraphs
              args: [3]
        ignore_me:
            label: Some optional field
            type: text
            example: false # Do not generate any example data for this field