Grav: adding custom fields on pages

Custom fields are a really essential feature on CMSs. With Grav we can add custom fields on pages so that an user can edit them through the Admin Panel. We can do this using Grav’s blueprints.

1. Add a blueprint file in your theme

Given:

• A template file: /user/themes/[theme-name]/templates/page.html.twig
• A page file (that use such template): /user/pages/01.home/page.md

Add a bluprint file inside your theme, with the same name as the template file (that is page in the above example):

/user/themes/[theme-name]/blueprints/page.yaml

Within the blueprint file we’ll define custom fields for the page template.

2. Define custom fields

Inside the blueprint file page.yaml, add a content like this:

title: Page Content
@extends: 
  type: default
  context: blueprints://pages 

form:
  fields:
    tabs:
      type: tabs
      active: 1

      fields:
        content:
          type: tab

          #
          # Add your custom fields here.
          # These fields will be available in the page's Content tab
          # inside the Admin Panel.
          #
          fields:

            #
            # Custom text field
            #
            header.custom.textField:
              type: text
              label: Custom text field

            #
            # Cover image
            #
            header.custom.coverImage:
              type: file
              label: Cover image
              destination: 'self@'
              multiple: false
              accept:
                - image/*

Custom field anatomy

In the above example we added a Custom text field, made in this way:

header.custom.textField:
  type: text
  label: Custom text field

Field’s name

The first line is the field’s name: header.custom.textField. The field name defines where field’s values are stored (within the page’s header). If you change the field’s name you will lose all field’s values. The field name must start with header., then can be any name you want. We suggest you to add some namespace also, as custom. in above example, to avoid name conflicts.

Field’s type

The second line is the field’s type: text. You can find the list of available field types here:

• https://learn.getgrav.org/forms/blueprints/fields-available
• https://learn.getgrav.org/forms/forms/fields-available

Field’s label

The third line is the field’s label ("Custom text field") that will be showed in the Admin Panel just before the custom field.

References

https://learn.getgrav.org/forms/blueprints#pages
https://learn.getgrav.org/forms/blueprints/example-page-blueprint
https://learn.getgrav.org/forms/blueprints/fields-available
https://learn.getgrav.org/forms/forms/fields-available