Page Templates Pro Feature

Boxes allows you to define pre-defined compositions of your Box Partials as page templates.

When creating a page, the user can choose a template from a list of available options. The Boxes defined in the template will automatically be added to the newly created page.

Defining a Page Template

To define a page template, you need to create a boxes.yaml file in your theme's root directory.

In the file, you can define a list of templates with their boxes. Each template requires to have at least a handle property.

# /themes/your-theme/boxes.yaml
templates:
-   name: Empty page
    handle: empty
    boxes: []

# A product page, the "hero" cannot be modified at all,
# the "intro" is locked in-place, but the data is
# modifiable by the user, see "Locking" below.
-   name: Product page
    handle: product
    boxes:
    - partial: hero
      locked: true
    - partial: intro
      locked: ['position', 'deletion']
      data: # Use the data property to define default values for the Box.
          title: Default Title
          text: Default Text
    - partial: text
    - partial: container
      children: # nested boxes are supported as well.
        - partial: hero
        - partial: text


# This template has a special "context" defined. This means
# it will not be available in the Boxes Editor by default.
-   name: Blog
    handle: blog
    contexts:
    - blog
    boxes:
    - partial: blog-hero
      locked: true
    - partial: blog-header
      locked: true

Locking

You can lock Boxes in a template to prevent the user from modifying them (see example above).

There are the following options available:

• position - The Box cannot be moved
• deletion - The Box cannot be deleted
• data - The Box cannot be modified

You can also set locked to true to lock all options.

Inserting References

In certain use-cases, you want to add a Reference to an existing Box on another page. The special built-in Boxes\Internal\Reference partial allows you to do this.

Use the following syntax to reference the partial my-partial on a page with the code my-page:

templates:
- name: Page with reference to an existing Box
  handle: reference
  boxes:
  - partial: 'Boxes\Internal\Reference@my-page:my-partial

Applying Page Templates when using Boxes in custom plugins

See the Usage in Plugins section for more information.