Grav - Plugin Tutorials

Plugin is a piece of software that provides additional functionality which was not originally completed by Grav's core functionality.
In this article, we are going to display random page using the random plugin. Before using this plugin, we will see some important points of random plugin.

• You can use this plugin to display the random page by using URI as /random.
• Create the filter to make use of taxonomy specified in the pages. You can create as category : blog.
• You can display the random page by using filter option and it informs Grav to use the same content for displaying in random page.

Setup Plugin

You need to create basic setup for plugin before using the actual plugin.

• Create folder called random under the user/plugins folder.
• Under the user/plugins/random folder, create two files namely
• random.php used for plugin code
• random.yaml used for the configuration

Plugin Configuration

To use the random plugin, we need to have some configuration options. We will write the below lines under the random.yaml file.

enabled:true
route:/random
filters:
	category:blog

Random creates a route that you define. Based on taxonomy filters, it picks random item. The default value of the filter is 'category: blog' which is used for random selection.

Plugin Structure

The below code can be used in the plugin structure.

<?php
namespace Grav\Plugin;
use Grav\Common\Page\Collection;
use Grav\Common\Plugin;
use Grav\Common\Uri;
use Grav\Common\Taxonomy;
class RandomPlugin extends Plugin{
}

We are using bunch of classes in the plugin using use statements which makes more readable and saves the space. The namespace Grav\Plugin must be written at the top of the PHP file. The plugin name should be written in titlecase and should be extended using Plugin.
You can subscribe the function getSubscribedEvents() to the onPluginsInitialized event which determines which events the plugin is subscribed to. Like this you can use the event to subscribe to other events.

public static function getSubscribedEvents() {
    return [
        'onPluginsInitialized' => ['onPluginsInitialized', 0],
    ];
}

Next use onPluginInitialized event under RandomPlugin class used for routing the page which is configured in the random.yaml file.
The method onPluginInitialized() contains following code:

public function onPluginsInitialized()
    {
        $uri = $this->grav['uri'];
        $route = $this->config->get('plugins.random.route');
        if ($route && $route == $uri->path()) {
            $this->enable([
                'onPageInitialized' => ['onPageInitialized', 0]
            ]);
        }
    }

The Uri object includes current uri, information about route. The config object specifies the configuration value for routing the random plugin and stored in the route object.
Next we will compare the configured route with the current URI path which informs plugin to listen the onPageInitialized event.

Displaying Random Page

You can display the random page by using the code with the following method:

public function onPageInitialized()
{
    $taxonomy_map = $this->grav['taxonomy'];
    $filters = (array) $this->config->get('plugins.random.filters');
    $operator = $this->config->get('plugins.random.filter_combinator', 'and');
    if (count($filters)) {
        $collection = new Collection();
$collection->append($taxonomy_map->findTaxonomy($filters, $operator)->toArray());
        if (count($collection)) {
            unset($this->grav['page']);
            $this->grav['page'] = $collection->random()->current();
        }
    }
}

As shown in the code,

• Assign the taxonomy object to the variable $taxonomy_map.
• Get the array of filter which uses configured taxonomy from the plugin configuration using config object. We are using the item as category : blog.
• We are using collection to store the random page in the $collection. Append the page which matches the filter to $collection variable.
• Unset the current page object and set the current page to display as random page in the collection.

Finally we will see the complete code of plugin to display random page as shown below:

<?php
namespace Grav\Plugin;
use Grav\Common\Page\Collection;
use Grav\Common\Plugin;
use Grav\Common\Uri;
use Grav\Common\Taxonomy;

class RandomPlugin extends Plugin
{
    public static function getSubscribedEvents() {
        return [
            'onPluginsInitialized' => ['onPluginsInitialized', 0],
        ];
    }
    public function onPluginsInitialized()
    {
        $uri = $this->grav['uri'];
        $route = $this->config->get('plugins.random.route');
        if ($route && $route == $uri->path()) {
            $this->enable([
                'onPageInitialized' => ['onPageInitialized', 0]
            ]);
        }
    }
    public function onPageInitialized()
    {
        $taxonomy_map = $this->grav['taxonomy'];
        $filters = (array) $this->config->get('plugins.random.filters');
        $operator = $this->config->get('plugins.random.filter_combinator', 'and');
        if (count($filters)) {
            $collection = new Collection();
            $collection->append($taxonomy_map->findTaxonomy($filters, $operator)->toArray());
            if (count($collection)) {
                unset($this->grav['page']);
                $this->grav['page'] = $collection->random()->current();
            }
        }
    }
}

Open your browser and type localhost/folder_name/random to see the random page as shown in the below screen: