Structuring blueprints

Only fields

The most simple setup of a blueprint is a form with just a few fields. For this setup, you can add fields using the fields keyword, then add your fields underneath with proper indentation:

title: My blueprint

fields:
  headline:
    label: Headline
    type: text
  text:
    label: Text
    type: textarea

For more sophisticated setups, you can use sections, columns and tabs to create nice layouts.

The fields keyword can be used on the top blueprint level like in the example above, but also in columns or tabs. However, once you want to mix sections and fields inside the same blueprint, column or tab, you need to wrap your fields inside a fields section. See examples below.

Sections

With the sections keyword you add one or more section types to your blueprint. When the sections keyword is used without being wrapped in columns, this will result in a single-column layout of stacked sections.

Here are some examples:

In this example we use multiple pages sections to separate drafts from published pages:

title: My blueprint

sections: # keyword that allows you to add multiple section types
  drafts:
    type: pages
    label: Drafts
    status: draft
  published:
    type: pages
    label: Published pages
    status: listed

In this example we have a pages section and a files section below each other

title: My blueprint

sections:
  pages:
    type: pages
    label: Pages
  files:
    type: files
    label: Files

You always need to create sections when you want to mix any type of section with fields. In that case, your fields need to be wrapped in a fields section

title: My blueprint

sections:
  pages:
    type: pages
    label: Pages
  fields:
    type: fields
    fields:
      text:
        type: text
      description:
        type: text

Columns

A single-column stacked layout like the above with only sections can sometimes be useful, in many cases you will, however, want to give more structure to your layout. That's where columns come into play.

A column can hold only fields, or different section types, the same rules for mixing fields and section apply as already outlined above.

Defining columns

Column definitions start with the columns keyword, followed by the individual column definitions. Columns can be defined in two ways:

title: My blueprint

columns:
  left:
    width: 2/3
    sections:
      # fields in the left column
  right:
    width: 1/3
    sections:
      # sections in the right column

You have to use named columns if you want to extend columns.

title: My blueprint

columns:
  - width: 2/3
    fields:
      # fields in the left column
  - width: 1/3
    sections:
      # sections in the right column

The following widths are available when defining columns:
1/2, 1/3, 1/4, 2/3, 2/4, 3/4

Adding fields and sections to columns

Just like a blueprint itself, a column can contain fields only:

title: My blueprint

columns:
  - width: 2/3
    fields:
      subtitle:
        type: text
      blocks:
        type: blocks
  - width: 1/3
    fields:
      published:
        type: date
      author:
        type: users
        max: 1

You can also add sections to a column. If you want to mix fields with sections inside a single column, sections are mandatory.

title: My blueprint

columns:
  # main
  main:
    width: 2/3
    sections:

      # a simple form
      content:
        type: fields
        fields:
          headline:
            label: Headline
            type: text
          text:
            label: Text
            type: textarea

  # sidebar
  sidebar:
    width: 1/3
    sections:

      # a list of subpages
      pages:
        type: pages
        label: Subpages

      # a list of files
      files:
        type: files
        label: Files

Two-column layout with sidebar on the right (pages and files sections) and form fields on the left.

You can probably already see how flexible this is. By slightly changing the columns, we can change the interface drastically.

title: My blueprint

columns:

  # sidebar
  sidebar:
    width: 1/3
    sections:

      # a list of subpages
      pages:
        type: pages
        label: Subpages

      # a list of files
      files:
        type: files
        label: Files

  # main
  main:
    width: 2/3
    fields:
      headline:
        label: Headline
        type: text
      text:
        label: Text
        type: textarea

Two-column layout with sidebar on the left (pages and files sections) and form fields on the right.

Two Sidebars

title: My blueprint

columns:

  # sidebar left
  left:
    width: 1/4
    sections:

      # a list of subpages
      pages:
        type: pages
        label: Subpages
        template: default

  # main
  main:
    width: 1/2
    sections:

      # a simple form
      content:
        type: fields
        fields:
          headline:
            label: Headline
            type: text
          text:
            label: Text
            type: textarea

  # sidebar right
  right:
    width: 1/4
    sections:
      # a list of files
      files:
        type: files
        label: Files

Three-column layout with sidebars on the right (pages section) and on the left (files section) and form fields in the middle.

Sticky columns

You can make an entire column sticky. This can be handy for a setup with a smaller sidebar that should always be available, even when you scroll.

columns:
  - width: 1/3
    sticky: true
    sections:
      # sections in the sticky column

Adapt all to your needs

Kirby gives you the flexibility to set up the Panel so that it adapts to the needs of every single page/template. Use the layout possibilities to create the structure that works best for you:

title: My blueprint

columns:
  gallery:
    width: 1/1
    sections:
      gallery:
        type: files
        layout: card
        ...

  review:
    width: 1/2
    sections:
      drafts:
        type: pages
        status: draft
        ...
      review:
        type: pages
        status: unlisted
        ...

  published:
    width: 1/2
    sections:
      published:
        type: pages
        status: listed
        ...

If this isn't yet enough ways and space for you to structure your sections and fields, move on with…

Tabs

When your blueprints get more complex, splitting up your view into multiple tabs helps to keep them organized. Tabs are basically wrappers around regular blueprint layouts. Check out how to create layouts before you get started with tabs.

Like the blueprint itself, a tab can contain

only fields
one or more sections
columns with fields and section

Defining tabs

A tab definition has three options:

label
columns
icon

The icon is optional. Please check out the list of available icons. You can also use an emoji by pasting it directly into the blueprint.

title: My blueprint

tabs:
  content:
    label: Content
    icon: text
    columns:
      # layout
  seo:
    label: SEO
    icon: search
    columns:
      # layout

Full example

title: My blueprint

tabs:

  # content tab
  content:
    label: Content
    icon: text
    columns:

      # main
      main:
        width: 2/3
        sections:

          # a simple form
          content:
            type: fields
            fields:
              headline:
                label: Headline
                type: text
              text:
                label: Text
                type: textarea

      # sidebar
      sidebar:
        width: 1/3
        sections:

          # a list of subpages
          pages:
            type: pages
            label: Subpages

          # a list of files
          files:
            type: files
            label: Files

  # seo tab
  seo:
    label: SEO
    icon: search
    fields:
      seoTitle:
        label: SEO Title
        type: text
      seoDescription:
        label: SEO Description
        type: text