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 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 format, but you can use whatever fits your project's requirements.
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.
Boxes will warn you if you use the same handle twice.
To group Boxes into sections (like
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.
section is defined,
Common will be used.
handle: jumbotron section: Homepage
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.
There is a small selection of pre-defined icons in the
plugins/offline/boxes/assets/img/boxes directory for you to use.
handle: box-with-custom-icon icon: /plugins/offline/boxes/assets/img/boxes/image.svg
You can place your custom Box partials anywhere in your active theme's
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 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
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