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.

Sr.No. Properties & Description
1

name*

Mention the name of the resource.

2

version*

Specifies the version of the resource.

3

description*

Gives brief description about the resource. It should not exceed more than 200 characters.

4

icon*

Specifies an icons library for developing a new theme or plugin.

5

author.name*

Specifies the name of the developer.

6

author.email (optional)

Specifies the email address of the developer.

7

author.url (optional)

Specifies the URL homepage of developer.

8

homepage (optional)

Specifies the allocated Url for homepage for your resource.

9

docs (optional)

Specifies the documentation link which you have written for your resource.

10

demo (optional)

Specifies the link of demo resource.

11

guide (optional)

Specifies the link of how to guide or tutorials for your resource.

12

keywords (optional)

Specifies the list of keywords that are related to your resource.

13

bugs (optional)

Specifies the Url where issues or bugs can be reported.

14

license (optional)

Specifies your resource license i.e. MIT, GPL etc.

15

dependencies (optional)

Specifies the name of the dependencies that are required for plugins or themes.

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.

Sr.No. Field & Description
1

Type

Indicates the field type.

2

Size

Specifies the size of the field.

3

Label

Specifies label to the field.

4

Validate

It validates the type of the field and the minimum length entered in the field.

5

Default

Sets default fields.

6

Options

Specifies the list of options.

7

Classes

Specifies 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. The following table lists out the of available form fields −

Common form fields

Sr.No. Field & Description
1

Checkbox

Displays single checkbox.

2

Checkboxes

Displays a list of checkboxes.

3

Date

Contains date field.

4

Datetime

Contains date and time field.

5

Email

Contains an email address field with validation.

6

Password

Contains a password field which displays in dot format.

7

Hidden

Contains hidden input field.

8

Radio

Allows selecting only one option from the list.

9

Select

This field contains few options.

10

Spacer

Adds title, text or horizontal line to the form.

11

Text

Contains normal text field.

12

Textarea

Contains multiline text inputs.

Special form fields

Sr.No. Field & Description
1

Array

Adds multiple key value rows.

2

Ignore

Unused fields are removed.

3

Columns

Divides the form into multiple columns.

4

Column

Displays a single column.

5

Dateformat

Sets the date and time format.

6

Display

Displays text value without any input value.

7

Frontmatter

The page is displayed in raw format.

8

List

Displays a list of items without a key.

9

Markdown

Displays the markdown editor.

10

Pages

Displays the list of pages.

11

Section

The setting page is divided into sections and each section has a title.

12

Selectize

It is used to select boxes.

13

Tabs

Settings are divided into list of tabs.

14

Tab

The tabs field uses to provide a tab.

15

Taxonomy

It is a select preconfigured to select the taxonomy.

16

Toggle

It represents the toggle effect that specifies on or off type of input.

Advertisements