Boxes Documentation

Appearance

YAML Schema ​

The following options are available in the YAML schema:

Full example ​

yaml
# full-example.yaml
handle: custom-partial
name: Your custom partial name
labelFrom: title
section: Custom Section
icon: /public/path/to/icon.svg
placeholderPreview: false

children: # or "true" to allow all partials as children
- allowed-child-context

spacing:
- general

eagerLoad:
- special_relation

contexts:
- default
- blog

assets:
    js:
    -   name: /plugins/acme/demo/assets/js/some.js
        bundle: false
        attributes:
            async: "async"
    css:
    -   name: /plugins/acme/demo/assets/css/some.css
        bundle: true

translatable:
- text
- subtitle

validation:
    rules:
        title:
        - required
        - "min:15"
    attributeNames:
        title: Title
    customMessages:
        title.min: "The title has to be at least 15 characters long"

components:
    myComponent:
        properties:
            id: 2
    myComponentWithAlias:
        component: myComponent
        addToLayout: true
        properties:
            id: 4
    myComponentWithMultipleInstances:
        uniqueAlias: true
        properties:
            id: 4

form:
    fields:
        title:
            label: My title input
    tabs:
        fields:
          [ ... ]
    secondaryTabs:
        fields:
          [ ... ]

handle ​

Required, a unique handle for this partial.

name ​

Optional, A human-readable name for this partial.

labelFrom ​

Optional, use this field's value as label in the Boxes Editor.

section ​

Optional, the selector section this partial should be displayed in. Defaults to Common.

icon ​

Optional, the icon to use in the selector.

placeholderPreview ​

Optional, set to false to not render a placeholder preview for this partial in the editor. Defaults to true.

children ​

Optional, set to true if this partial supports nested child partials.

Alternatively, specify an array of Contexts to allow only certain other partials as children.

spacing ​

Optional, use this to allow the end-user to select a pre-defined spacing (before/after a box) in the UI. See Spacing.

eagerLoad ​

Optional, defaults to [], defines which relations to eager load if a Box gets rendered in the context of a Page.

yaml
eagerLoad:
- category
- specs_file

Alternatively, extend the Box Models's $with property to always eager load a relation.

contexts ​

Optional, defaults to ['default'], defines which contexts this partial can be used in. The default context is used when editing a Box Page in the backend.

yaml
contexts:
- default   # Make this partial available when editing a Box Page in the backend.
- blog      # Make this partial also available in any blog context.

See Plugin and Tailor Integration for more information about contexts.

assets ​

Optional, array under js and css keys. This option allows you to define assets (JS/CSS) that are required in your partial. The plugin will include these assets on every page the partial is used on. If your partial is rendered multiple times on the same page, the assets will be included only once (keep this in mind while writing your code!).

The assets are included using October's asset pipeline. So for this to work you need to place the {% styles %} and {% scripts %} tags in your layout.

You can define the following keys for each asset:

  • name: Required, the path to the asset (as you would pass it to a ->addJs() method)
  • bundle: Boolean, if the asset should be combined with other assets or be included on its own
  • attributes: Dictionary, additional attributes for the HTML tag (as you would pass it to a ->addJs() method)
yaml
assets:
    js:
    -   name: /plugins/acme/demo/assets/js/some.js
        attributes:
            async: "async"
    css:
    -   name: /plugins/acme/demo/assets/css/some.css
        bundle: true

translatable ​

Optional, integration for RainLab.Translate < 2.0. An array of attributes that are translatable.

If you are running October CMS 3.1 or higher, you can use the Multisite Feature instead.

yaml
translatable:
- title
- content

validation ​

Optional, values for the $rules, $attributeNames and $customMessages properties of the Validation trait.

yaml
validation:
    rules:
        title:
        - required
        - "min:15"
    attributeNames:
        title: Title
    customMessages:
        title.min: "The title has to be at least 15 characters long"

components ​

Optional, adds the defined components to the controller. This allows you to call AJAX handlers of components from your custom partials.

yaml
components:
    aComponent:
        properties:
            id: 2
    aComponentWithAlias:
        component: aComponent
        addToLayout: true
        uniqueAlias: true
        properties:
            id: 4
    aVerySimpleComponentWithoutAliasOrProperties:

The uniqueAlias option appends the Box's unique ID to the component's alias. This allows you to use multiple instances of the same component on a single page.

See the docs on components for more information.

form ​

Required, an October CMS form definition. (Docs)

yaml
form:
    fields:
        title:
            label: My title input
    tabs:
        fields:
          [ ... ]
    secondaryTabs:
        fields:
          [ ... ]