Example: Plugin Configuration

We saw in the previous example how to define a blueprint for a plugin and/or theme.

Now, let's see how to offer configuration options for a plugin or theme, that will be shown by the Admin Plugin.

If you want your plugin (or theme) to have options directly configurable from the admin interface, you need to fill the blueprints.yaml file with forms.

For example, here is the Archives plugin's archives.yaml file:

 1enabled: true
 2built_in_css: true
 3date_display_format: 'F Y'
 4show_count: true
 5limit: 12
 6order:
 7    by: date
 8    dir: desc
 9filter_combinator: and
10filters:
11    category: blog

Those are the default settings of the plugin. Without the Admin plugin to configure those settings, the user needs to copy this file in the /user/config/plugins/ folder and them there.

By providing a correctly-formatted blueprints.yaml file, you can allow the user to change the settings from the Admin interface. When the settings are saved, they're automatically written to /user/config/plugins/archives.yaml (or under config/themes, if it's a theme). The structure starts as follows:

 1name: Archives
 2version: 1.3.0
 3description: The **Archives** plugin creates links for pages grouped by month/year
 4icon: university
 5author:
 6  name: Team Grav
 7  email: d[email protected]
 8  url: https://getgrav.org
 9homepage: https://github.com/getgrav/grav-plugin-archives
10demo: http://demo.getgrav.org/blog-skeleton
11keywords: archives, plugin, blog, month, year, date, navigation, history
12bugs: https://github.com/getgrav/grav-plugin-archives/issues
13license: MIT
14
15form:
16  validation: strict
17  fields:

Here comes the part that we need. Every field in the archives.yaml file needs a corresponding form element, for example:

Toggle

 1enabled:
 2  type: toggle
 3  label: Plugin status
 4  highlight: 1
 5  default: 1
 6  options:
 7      1: Enabled
 8      0: Disabled
 9  validate:
10       type: bool

Select

 1date_display_format:
 2  type: select
 3  size: medium
 4  classes: fancy
 5  label: Date Format
 6  default: 'jS M Y'
 7  options:
 8    'F jS Y': "January 1st 2014"
 9    'l jS of F': "Monday 1st of January"
10    'D, m M Y': "Mon, 01 Jan 2014"
11    'd-m-y': "01-01-14"
12    'jS M Y': "10th Feb 2014"

Text

 1limit:
 2  type: text
 3  size: x-small
 4  label: Count Limit
 5  validate:
 6    type: number
 7    min: 1

The root element (in those examples enabled, date_display_format, limit) is the name of the option. The additional components of each field determines how this field is displayed. For example, its type (type), its size (size), the label shown (label) and an optional helpful tooltip that appears on hover (help). default and placeholder let you create some defaults and improve how the fields renders to the user.

The rest of the fields can change depending on the field type. For example the select field type requires and options list.

Nested options are reachable via dot notation (e.g. order.dir)

 1order.dir:
 2  type: toggle
 3  label: Order Direction
 4  highlight: asc
 5  default: desc
 6  options:
 7    asc: Ascending
 8    desc: Descending

The Admin plugin defines many other field types that can be used, in plugins/admin/themes/grav/templates/forms/fields.

It's important to note that when form.validation is set to strict, like in the Archives plugin example, you need to add form blueprints for all the options, otherwise an error will pop up on save. If you instead want to just allow to customize a couple of fields to the Admin interface, not all of them, set form.validation as loose.