Grav - Plugin Tutorials


In this chapter, we will delve into how a plugin can be set up and configured. In addition, we will also understand the structure of a plugin and how to display a random page. 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 the random plugin.

Setup Plugin

Follow these steps to create a basic setup for plugin before using the actual plugin.

Plugin Configuration

To use the random plugin, we need to have some configuration options. We will write the following 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 a random item. The default value of the filter is 'category: blog' which is used for random selection.

Plugin Structure

The following 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 a bunch of classes in the plugin using the use statements which makes it more readable and saves on space too. 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; this 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],
   ];
}

Let us now use the onPluginInitialized event under the RandomPlugin class used for routing the page which is configured in the random.yaml file.

The method onPluginInitialized() contains the 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 the current uri, information about route. The config object specifies the configuration value for routing the random plugin and store it in the route object.

We will now compare the configured route with the current URI path which informs the plugin to listen to 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,

Finally, we will see the complete code of plugin to display a 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 following screenshot −

Grav Plugin Tutorials