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.

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.

handle: jumbotron
section: Homepage

Order

The order property can be used to define the order in which the partials are displayed in the selector.

By default, partials are ordered by their name/handle.

handle: jumbotron
section: Homepage
order: 100 # the higher the number, the later the partial is displayed

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.

You can use Phosphor Icons by specifying the icon name (starting with ph-).

handle: box-with-phosphor-icon
icon: ph-image

Alternatively, you can use a custom SVG icon. 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