Grav is a fully extensible CMS. This important part is done, most of the time, by implementing a plugin.

This kind of extension can be considered as a small application which adds extra functionalities to Grav CMS, which are not implemented by default in the application core.

I've implemented myself several plugins to extend my website with new functionalities, which were not implemented by default in the application core. Some of them are:

  • Blog which adds blog functionalities to each Grav theme.
  • Cookies Policy which adds a banner to display the European Community Cookies Law Policy disclaimer.
  • Social buttons which adds the RRSSB (Ridiculously Responsive Social Sharing Buttons) social buttons.

Each plugin has its own configuration which defines the default behavior of the plugin itself. The most of the times we will need to change the default configuration to adapt the plugin to our needs.

When we fall in this need, we could be tempted to change those setting directly in the plugin. That's really a wrong approach because we will loose our changes when we will update the plugin, when a new release will be available.

Luckily, Grav gives us two options to properly configure plugins, outside the plugin itself.

The first option we have is to create a plugins.yaml file under the user configuration folder, user/config and copy its configuration inside that file.

So, if we want to configure the Cookies Policy to display a dialog instead of a banner, we can copy the default configuration to the plugins.yaml as follows:

cookiespolicy:
    enabled: true
    type: bar
    message: We use cookies to help us give you the best experience when using our website. Unless you change your settings, we'll assume that you agree for us to do this. However, you can change your settings at any time according with your browser.
    btn_privacy: 'Learn more'
    btn_close: 'Close'
    url: 'http://example.com/privacy-url'

and change the specific option as follows:

cookiespolicy:
    type: dialog
    [...]

As you may notice, we need to declare the plugin name as the top key and then add its configuration under it.

It is important to copy the whole plugin configuration and not only the setting to change, because it overrides the whole plugin configuration.

If we want to configure another plugin, let's say we want to hide the random section in the blog plugin, we can simply add the blog configuration as follows:

cookiespolicy:
    enabled: true
    type: dialog
    message: We use cookies to help us give you the best experience when using our website. Unless you change your settings, we'll assume that you agree for us to do this. However, you can change your settings at any time according with your browser.
    btn_privacy: 'Learn more'
    btn_close: 'Close'
    url: 'http://example.com/privacy-url'
blog:
    enabled: true
    sidebar:
        _simple_search: true
        _related_posts: true
        _random: false
        _taxonomy_list: true
        _archives: true
        _feed: true

The second option we have, is to copy the whole plugin configuration file under the user/config/plugins folder and then customize it.

That folder is not included in a Grav project, so you must create it by hand.

Which is the best option? Both of them works perfectly so it is a matter of taste. By myself, I prefer the second option because it gives me the feeling of having a better order in such things.

Next Post Previous Post

Related Posts