Example: Page Blueprints
Page Blueprints extend from the default page, and give you the ability to add options. Basically, custom pages can come to life by using page blueprints. With a page blueprint, you can 100% configure the editing form for a page as it appears in the Admin.
A first example
If you want to use the default page form, and just add a couple of select boxes for example, you can extend from the default page.
This will use the default page form, and append a text field to the Advanced tab, under the Overrides section:
1title: Gallery
2extends@:
3 type: default
4 context: blueprints://pages
5
6form:
7 fields:
8 tabs:
9 type: tabs
10 active: 1
11
12 fields:
13 advanced:
14 fields:
15 overrides:
16 fields:
17 header.an_example_text_field:
18 type: text
19 label: Add a number
20 default: 5
21 validate:
22 required: true
23 type: int
This will instead add a new tab, called Gallery, with some fields in it.
1title: Gallery
2'@extends':
3 type: default
4 context: blueprints://pages
5
6form:
7 fields:
8 tabs:
9 type: tabs
10 active: 1
11
12 fields:
13 gallery:
14 type: tab
15 title: Gallery
16
17 fields:
18 header.an_example_text_field:
19 type: text
20 label: Add a number
21 default: 5
22 validate:
23 required: true
24 type: int
25
26 header.an_example_select_box:
27 type: select
28 label: Select one of the following
29 default: one
30 options:
31 one: One
32 two: Two
33 three: Three
The fields types you can add are listed in Available form fields for use in the admin
How to name fields
It's important that fields use the header.* structure, so field content is saved to the Page Header when saved.
Create a completely custom page form
You can avoid extending from the default form, and create a page form that is completely unique.
For example:
1title: Gallery
2
3form:
4 fields:
5 tabs:
6 type: tabs
7 active: 1
8
9 fields:
10 gallery:
11 type: tab
12 title: Gallery
13
14 fields:
15 header.an_example_text_field:
16 type: text
17 label: Add a number
18 default: 5
19 validate:
20 required: true
21 type: int
22
23 header.an_example_select_box:
24 type: select
25 label: Select one of the following
26 default: one
27 options:
28 one: One
29 two: Two
30 three: Three
31
32 route:
33 type: parents
34 label: PLUGIN_ADMIN.PARENT
35 classes: fancy
Caution
WARNING: route field has changed in Grav 1.7. Please update your existing blueprints to use the new type: parents.
A note for Expert mode
When editing pages in Expert mode, the Blueprint is not read, and the page form is the same across all pages. This is because in Expert mode you edit the page fields directly in the Frontmatter field, and there is no need to have a customized presentation.
Where to put the Page Blueprints
In order for the Admin Plugin to pick up the blueprints, and thus show the new Page types, you need to put the blueprints in the correct place.
In the User Blueprints folder
Put them in user/blueprints/pages/. This is a good place to put them when you simply want your blueprints to be present in your site.
In the Theme
Put them in user/themes/YOURTHEME/blueprints/. This is best when you also intend to distribute your theme: the theme will provide the page blueprints and it will be easier to use.
In the Data folder
If you are using a Gantry5 based theme, the best location is user/data/gantry5/themes/YOURTHEME/blueprints/, otherwise your files may be lost during a theme update.
In a Plugin
Put them in user/plugins/YOURPLUGIN/blueprints/. This is the place where to put them if you define and add custom pages in the plugin.
Then subscribe to the onGetPageBlueprints event and add them to Grav. The following example adds the blueprints from the blueprints/ folder.
1public static function getSubscribedEvents()
2{
3 return [
4 'onGetPageBlueprints' => ['onGetPageBlueprints', 0]
5
6 ];
7}
8
9public function onGetPageBlueprints($event)
10{
11 $types = $event->types;
12 $types->scanBlueprints('plugins://' . $this->name . '/blueprints');
13}