Grav - Blueprints

Blueprints are metadata information about the resource (source of information). It serves two purposes −

• First is the resource identity itself.
• Second is regarding the forms.

This complete information is saved in the blueprints.yaml file present in each plugin or theme.

Resource Identity

In blueprints.yaml file identity is defined for each themes and plugins. Resource will not be added in Grav repository until blueprints are not formatted and compiled perfectly.

Blueprints Example

name: plugin name
version: 0.6.0
description: Adds an advanced plugin to manage your site
icon: empire
author:
   name: Team Grav
   email: devs@getGrav.org
   url: http://getGrav.org
homepage: https://github.com/getGrav/Grav-plugin-assets
keywords: assets, plugin, manager, panel
bugs: https://github.com/getGrav/Grav-plugin-assets/issues
readme: https://github.com/getGrav/Grav-plugin-assets/blob/develop/README.md
license: MIT

dependencies:
   - form
   - email
   - login

form:
   validation: loose
   fields:
      Basics:
         type: section
         title: Basics
         underline: false
      enabled:
         type: hidden
         label: Plugin status
         highlight: 1
         default: 0
         options:
            1: Enabled
            0: Disabled
         validate:
            type: bool

The following few properties are optional and some are used to give your identity and resource.

The following is an example of the login plugin blueprint −

name: Login
version: 0.3.3
description: Enables user authentication and login screen.
icon: sign-in
author:
   name: Team Grav
   email: devs@getGrav.org
   url: http://getGrav.org
keywords: admin, plugin, login
homepage: https://github.com/getGrav/Grav-plugin-login
keywords: login, authentication, admin, security
bugs: https://github.com/Getgrav/Grav-plugin-login/issues
license: MIT

Forms

You can fill the blueprints.yaml file with forms if you want themes or plugins to have options directly configurable from the admin interface. The part of this resource can be configured via the Admin Plugin, which is defined by the Forms metadata.

The following is an example of the Archives Plugin archives.yaml file.

enabled: true
built_in_css: true
date_display_format: 'F Y'
show_count: true
limit: 12
order:
   by: date
   dir: desc
filter_combinator: and
filters:
   category: blog

These are the plugin's default settings. To configure them without the use of Admin plugin the user has to copy this file in the /user/config/plugins/archives.yaml folder and make the changes. You can provide the archives.yaml file correctly; you can choose to change the settings in the admin interface from the users.

After saving the changes, it will automatically get written to <your_folder_name>/user/config/plugins/archives.yaml.

The blueprint.yaml file of the Archives Plugin contains the structure as shown below −

name: Archives
version: 1.3.0
description: The **Archives** plugin creates links for pages grouped by month/year
icon: university
author:
   name: Team Grav
   email: devs@getGrav.org
   url: http://getGrav.org
homepage: https://github.com/getGrav/Grav-plugin-archives
demo: http://demo.getGrav.org/blog-skeleton
keywords: archives, plugin, blog, month, year, date, navigation, history
bugs: https://github.com/getGrav/Grav-plugin-archives/issues
license: MIT

form:
   validation: strict
   fields:
      enabled:
         type: toggle
         label: Plugin status
         highlight: 1
         default: 1
         options:
            1: Enabled
            0: Disabled
         validate:
            type: bool

      date_display_format:
         type: select
         size: medium
         classes: fancy
         label: Date Format
         default: 'jS M Y'
         options:
            'F jS Y': "January 1st 2014"
            'l jS of F': "Monday 1st of January"
            'D, m M Y': "Mon, 01 Jan 2014"
            'd-m-y': "01-01-14"
            'jS M Y': "10th Feb 2014"

      limit:
         type: text
         size: x-small
         label: Count Limit
         validate:
            type: number
            min: 1

      order.dir:
         type: toggle
         label: Order Direction
         highlight: asc
         default: desc
         options:
            asc: Ascending
            desc: Descending

Following are the form elements present in the archive.yaml.

Toggle

enabled:
   type: toggle
   label: Plugin status
   highlight: 1
   default: 1
   options:
      1: Enabled
      0: Disabled
   validate:
      type: bool

Select

date_display_format:
   type: select
   size: medium
   classes: fancy
   label: Date Format
   default: 'jS M Y'
   options:
      'F jS Y': "January 1st 2014"
      'l jS of F': "Monday 1st of January"
      'D, m M Y': "Mon, 01 Jan 2014"
      'd-m-y': "01-01-14"
      'jS M Y': "10th Feb 2014"

Text

limit:
   type: text
   size: x-small
   label: Count Limit
   validate:
      type: number
      min: 1

The root element Enabled, date_display_format and limit are the options. The field present in this root element determines the type, size, label, default and options. Depending upon the field type, the other fields can change; for example, the select field requires options list.

Order direction

order.dir:
   type: toggle
   label: Order Direction
   highlight: asc
   default: desc
   options:
      asc: Ascending
      desc: Descending

This field consists of the nested options. There are many field types that can be used in plugins/admin/themes/Grav/templates/forms/fields. As we can see in the archive.yaml file, the form validation is set to strict. When validation is set as strict, then for all the options you have to add the blueprints form, otherwise it will pop up an error while saving. The form.validation can be set as loose when you want to customize only the two fields to admin interface.

The following table gives a brief explanation of the fields relating to the above form elements.

Form Fields available in the admin

There are many built-in-form fields available which are used by plugins and themes or can create their own form fields. The following table lists out the of available form fields −

Common form fields

Special form fields