Skip to content
On this page

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.

WARNING

It is important that you do not change the handle once the box is in use. If you do change it, referenced data can no longer be found.

Don't panic

Boxes will warn you if you use the same handle twice.

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.

yaml
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.

TIP

There is a small selection of pre-defined icons in the plugins/offline/boxes/assets/img/boxes directory for you to use.

yaml
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.

yaml
# _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:

yaml
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:

yaml
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.

yaml
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