Grav - 插件教程

在本章中，我们将深入研究如何设置和配置插件。此外，我们还将了解插件的结构以及如何显示随机页面。插件是一种提供额外功能的软件，该功能最初并非由 Grav 的核心功能完成。

在本文中，我们将使用随机插件显示随机页面。在使用此插件之前，我们将了解随机插件的一些要点。

您可以使用此插件通过使用 URI 作为 /random 来显示随机页面。
创建过滤器以利用页面中指定的分类法。您可以创建为 category : blog。
您可以使用过滤器选项显示随机页面；这会通知 Grav 使用与随机页面中显示的相同内容。

设置插件

在使用实际插件之前，请按照以下步骤创建插件的基本设置。

在 user/plugins 文件夹下创建名为 random 的文件夹。
在 user/plugins/random 文件夹下，创建两个文件，即 −
- random.php 用于插件代码
- random.yaml 用于配置

插件配置

要使用随机插件，我们需要有一些配置选项。我们将在 random.yaml 文件下写入以下几行。

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

Random 创建您定义的路线。根据分类过滤器，它会选择一个随机项目。过滤器的默认值为 'category: blog'，用于随机选择。

插件结构

以下代码可用于插件结构。

<?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 {
   }
?>

我们在插件中使用了一系列类，使用 use 语句，这使其更具可读性，也节省了空间。命名空间 Grav\Plugin 必须写在 PHP 文件的顶部。插件名称应以 titlecase 形式书写，并使用 Plugin 进行扩展。

您可以将函数 getSubscribedEvents() 订阅到 onPluginsInitialized 事件；这决定了插件订阅了哪些事件。这样，您可以使用该事件订阅其他事件。

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

现在让我们使用 random.yaml 文件中配置的用于路由页面的 RandomPlugin 类下的 onPluginInitialized 事件。

方法 onPluginInitialized() 包含以下代码 −

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

Uri 对象包含当前 uri、路由信息。config 对象指定路由随机插件的配置值并将其存储在路由对象中。

现在我们将配置的路由与当前 URI 路径进行比较，以通知插件监听 onPageInitialized 事件。

显示随机页面

您可以使用以下方法使用代码显示随机页面 −

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();
      }
   }
}

如代码所示，

将分类对象分配给变量 $taxonomy_map。
使用 config 对象从插件配置中获取使用已配置分类法的过滤器数组。我们使用的项目为 category : blog。
我们使用 collection 将随机页面存储在 $collection 中。将与过滤器匹配的页面附加到 $collection 变量。
取消设置当前页面对象，并将当前页面设置为在集合中显示为随机页面。

最后，我们将看到插件显示随机页面的完整代码，如下所示 −

<?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();
         }
      }
   }
}

打开浏览器并输入 localhost/folder_name/random 以查看随机页面，如以下屏幕截图所示 −