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.
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.
Defining the Box config inline New in 3.2 (Experimental)
By default, the Box config is defined in a separate YAML file. It is also possible to define the config inside the partial itself. This is especially useful for simple use-cases.
To do so, place your YAML structure at the beginning of the partial. There are two rules to follow:
- The
handle
property must be the first line of the file. - The partial must be stored in the
theme/<your-theme>/partials/boxes
directory.
twig
handle: single-file-box
name: 'Single File Box'
form:
fields:
title:
label: Title
type: text
==
<div>
<h1>{{ box.title }}</h1>
</div>
You can still use the PHP code section and place components on the partial.
twig
handle: single-file-box-with-component
name: 'Single file Box with Component and Code'
form:
fields:
title:
label: Title
type: text
[section related]
handle = "Blog\Post"
==
function onStart()
{
// Do something.
}
==
<div>
<h1>{{ box.title }}</h1>
{% for post in related.get() %}
...
{% endfor %}
</div>
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
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.
yaml
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.
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
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
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
.
yaml
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
.
yaml
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