Skip to content

Kirby 3.9.8

Using blueprints in the frontend

Being able to query the blueprints that define the Panel layout gives you endless possibilities for control structures in your front-end––from simple field queries to building your front-end forms.

This recipe introduces you to the Blueprint class and its convenient methods. If you want to dig deeper, checkout the source code of the Kirby\Cms\Blueprint class.

Every setting of a blueprint is available via the blueprint() method. It is available for the Site object, for Page, Image, and User objects.

The method returns a huge array with every setting. You can examine this array if you put the following code into one of your templates:

$blueprint = $page->blueprint();
dump($blueprint);

Get the name of the blueprint

$blueprintName = $page->blueprint()->name();
dump($blueprintName);

Get the title of the blueprint

$blueprintTitle = $page->blueprint()->title();
dump($blueprintTitle);

Get the fields

With

$fields = $page->blueprint()->fields();
dump($fields);

You get an array with all fields with their names as keys and their attributes as the value.

Get a single field by field name

You can query a single field by name like this:

$field = $page->blueprint()->field('text');
dump($field);

Get the parent object model

$model = $page->blueprint()->model();
dump($model);

With a page blueprint, this will return the Page object.

Get a section by name

$section = $page->blueprint()->section('images');
dump($section);

This returns a Kirby\Cms\Section object, which you can further query.

Custom blueprint options

Apart from the blueprint settings described in the documentation, you can also use custom attributes in your blueprints.

For example, you could introduce an autoPublish option:

title: My blueprint title

options:
  changeSlug: false
  delete: true
  autoPublish: true

Now, you can query this option, for example in a hook that auto-publishes the page after creation if you have set the autoPublish option to true:

return [
  'hooks' => [
    'page.create:after' => function ($page) {
      $autoPublish = $page->blueprint()->options()['autoPublish'] ?? false;
      if($autoPublish) {
        $page->changeStatus('listed');
      }
    }
  ]

This is just a basic example. Instead of setting this option to true/false, you can use any other strings, for example to define that the hook should publish a page to a listed or unlisted state.

title: My blueprint title

options:
  changeSlug: false
  delete: true
  autoPublish: listed
return [
  'hooks' => [
    'page.create:after' => function ($page) {
      $autoPublish = $page->blueprint()->options()['autoPublish'] ?? false;
      if($autoPublish) {
        $page->changeStatus($autoPublish);
      }
    }
  ]

Instead of adding a new option to the options array, you can use custom attributes anywhere in your blueprint. Just make sure they don't interfere with Kirby's default blueprint settings. To be on the safe side, you can prefix your custom options.