Skip to content

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:
          [ ... ]