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

Following few properties are optional and some are required to use to give your identity and resource.

Properties	Description
name*	Mention the name of the resource.
version*	Specifies the version of the resource.
description*	Gives brief description about the resource. It should not exceed more than 200 characters.
icon*	Specifies an icons library for developing a new theme or plugin.
author.name*	Specify the name of the developer.
author.email (optional)	Specify the email address of the developer.
author.url (optional)	Specify the URL homepage of developer.
homepage (optional)	Specify the allocated Url for homepage for your resource.
docs (optional)	Specify the documentation link which you have written for your resource.
demo (optional)	Specify the link of demo resource.
guide (optional)	Specify the link of how to guide or tutorials for your resource.
keywords (optional)	Specify the list of keywords that are related to your resource.
bugs (optional)	Specify the Url where issues or bugs can be reported.
license (optional)	Specify your resource license i.e. MIT, GPL etc.
dependencies (optional)	Specify the name of the dependencies that are required for plugins or themes.

Here is a small and simple example of 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 admin interface. The part of the resource can be configured via Admin Plugin is defined by Forms metadata.
Below is an example of 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 /user/config/plugins/archives.yaml folder and make the changes. You can provide the archives.yaml file correctly; and can allow to change the settings from 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 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 presents 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 name. 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 nested options. There are many field types that can be used in plugins/admin/themes/grav/templates/forms/fields. As we can see in archive.yaml file the form validation is set to strict. When validation is set as strict, then for all options you have to add 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 two fields to admin interface.

Following are brief explaination of fields of above form elements.

Fields	Description
Type	Indicates the field type.
Size	Specify the size of the field.
Label	Specifies label to the field.
Validate	It validates the type of the field and the minimum length entered in the field.
Default	Sets default fields.
Options	Specify the list of options.
Classes	Specify the class for the field.

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. Following are the list of available form fields:

Common form fields

Fields	Description
Checkbox	Displays single checkbox.
Checkboxes	Displays a list of checkboxes.
Date	Contains date field.
Datetime	Contains date and time field.
Email	Contains an email address field with validation.
Password	Contains a password field which displays in dot format.
Hidden	Contains hidden input field.
Radio	Allows selecting only one option from the list.
Select	This field contains few options.
Spacer	Adds title, text or horizontal line to the form.
Text	Contains normal text field.
Textarea	Contains multiline text inputs.

Special form fields

Fields	Description
Array	Add multiple key value rows.
Ignore	Unused fields are removed.
Columns	Divides the form into multiple columns.
Column	Displays a single column.
Dateformat	Sets the date and time format.
Display	Displays text value without any input value.
Frontmatter	The page is displayed in raw format.
List	Displays a list of items without a key.
Markdown	Displays the markdown editor.
Pages	Displays the list of pages.
Section	The setting page is divided into sections and each section has a title.
Selectize	It is used to select boxes.
Tabs	Settings are divided into list of tabs.
Tab	The tabs field uses to provide a tab.
Taxonomy	It is a select preconfigured to select the taxonomy.
Toggle	It represents toggle effect that specify on or off type of input.