Grav 外掛教程

本章我們將深入探討如何設定和配置外掛。此外，我們還將瞭解外掛的結構以及如何顯示隨機頁面。外掛是一段軟體，它提供Grav核心功能原本未包含的附加功能。

在本文中，我們將使用random外掛來顯示隨機頁面。在使用此外掛之前，我們將瞭解random外掛的一些重要點。

您可以使用此外掛透過URI /random 來顯示隨機頁面。
建立過濾器以利用頁面中指定的分類法。您可以建立如下分類：category : blog。
您可以使用過濾器選項顯示隨機頁面；這指示Grav使用要在隨機頁面中顯示的相同內容。

外掛設定

在使用實際外掛之前，請按照以下步驟建立外掛的基本設定。

在user/plugins資料夾下建立一個名為random的資料夾。
在user/plugins/random資料夾下，建立兩個檔案：
- random.php 用於外掛程式碼
- random.yaml 用於配置

外掛配置

要使用random外掛，我們需要一些配置選項。我們將在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語句在外掛中使用了一組類，這使得程式碼更易讀，也節省了空間。必須在PHP檔案的頂部編寫namespace Grav\Plugin。外掛名稱應使用標題大小寫編寫，並應使用Plugin擴充套件。

您可以將函式getSubscribedEvents()訂閱到onPluginsInitialized事件；這決定了外掛訂閱了哪些事件。這樣，您可以使用該事件訂閱其他事件。

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

現在讓我們在RandomPlugin類下使用onPluginInitialized事件，該類用於路由在random.yaml檔案中配置的頁面。

方法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物件指定random外掛路由的配置值，並將其儲存在route物件中。

現在我們將配置的路由與當前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以檢視隨機頁面，如下面的螢幕截圖所示：

列印頁面