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.

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

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

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.

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