Appearance
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