為十月 CMS 開發自定義插件

已發表: 2022-03-10

快速總結 ↬如果您喜歡編寫面向對象且易於閱讀的代碼，那麼本文適合您。您將學習如何編寫自己的插件以及為什麼 10 月可能是您下一個項目的不錯選擇。

去年，我對 PHP 中的新 CMS 系統進行了一些研究，以找到 WordPress 的良好替代品。理想情況下，它必須是具有乾淨和現代代碼庫的開源解決方案。

其中一個引起了我的興趣：十月 CMS。我試過了，幾乎立刻就喜歡上了。代碼結構非常好，編寫自定義插件很容易。

本文旨在為您提供對該平台的期望的概述，並在您決定使用它之前讓您體驗一下。

為什麼選擇十月作為您的 CMS 平台？

我個人決定在我的項目中使用它有幾個主要原因。

由 Laravel 提供支持

October 建立在用於創建現代 Web 應用程序的最強大的 PHP 框架之上：Laravel。我可以很有信心地說這是最好的。它非常易於使用和理解，並且具有現代框架所需的所有功能，從路由、對象關係映射 (ORM)、授權、緩存以及許多其他提供良好且清晰的 MVC 結構的功能。由於由 Laravel 提供支持，October 繼承了它的老大哥的所有這些功能。

乾淨的代碼和文檔

與許多其他 CMS 解決方案不同，October 有一個非常乾淨且記錄良好的代碼庫。它是使用面向對象的範例編寫的。 October 使用 Twig 作為其模板引擎，而不是普通的舊 PHP，這為開發人員簡化了工作。技術文檔也寫得很好，可以幫助您快速找到大多數問題的答案。

大社區

儘管十月的社區還沒有那麼大，但它非常有幫助且反應迅速。您可以加入一個公共 Slack 頻道，在那裡您會找到樂於幫助您解決問題的開發人員。

大市場

與 WordPress 和其他 CMS 一樣，October 有一個主題和插件市場。即使沒有那麼多好的主題可供選擇，但現在有 700 多個插件，因此您很可能只需搜索並安裝其中一個即可添加功能。插件的一個重要功能是，如果您只需在管理儀表板中添加項目 ID，它們就可以在所有項目之間輕鬆同步。

跳躍後更多！繼續往下看↓

插件和組件

插件是向十月添加新功能的基礎。一個插件可以由多個文件和目錄組成，這些文件和目錄負責註冊自定義組件、模型、更新數據庫結構或添加翻譯。

插件通常在項目的plugins/目錄中創建。由於許多插件被提交到市場供其他人使用，每個插件都應該有一個自定義命名空間，通常以創建插件的公司或開發人員的名稱開頭。因此，例如，如果您的名字是Acme ，並且您創建了一個名為 Blog 的很棒的插件，那麼您的插件將位於Acme\Blog的命名空間下。

讓我向您展示插件目錄結構的外觀：

如您所見，還有一個名為plugin.php的文件負責在十月 CMS 中註冊插件及其所有組件。

另一件重要的事情是，並非上面列出的所有目錄都是插件運行所必需的。您的插件可以具有以下結構並且仍然可以正常工作：

大多數情況下，構建一個插件來僅添加一項功能。例如，“翻譯”插件旨在幫助您將網站上的內容翻譯成不同的語言，並為用戶提供多語言支持。

十月 CMS 有一個很棒的市場，您可以在其中找到您的需求。

與 WordPress 和其他流行的 CMS 不同，October 插件也可以有組件。根據 10 月份的文檔，組件是“可以附加到任何頁面、部分或佈局的可配置建築元素”。示例可能包括：聯繫表格、導航、常見問題解答列表及其答案；基本上任何可以作為一個構建塊捆綁在一起的有意義的東西，可以在多個頁面上重複使用。

組件是作為插件的一部分創建的，它們存在於components/子目錄中：

每個組件都有一個定義組件的 PHP 文件（如componentName.php ），以及組件部分的可選子目錄。組件部分文件夾必須與組件本身俱有相同的小寫名稱。

為了演示組件的功能，我們假設我們的組件負責顯示博客文章。

 namespace Acme\Blog\Components; class BlogPosts extends \Cms\Classes\ComponentBase { public function componentDetails() { return [ 'name' => 'Blog Posts', 'description' => 'Displays a collection of blog posts.' ]; } // This array becomes available on the page as {{ component.posts }} public function posts() { return ['First Post', 'Second Post', 'Third Post']; } }

如我們所見，該組件有兩個主要功能。第一個， componentDetails() ，向將在其網頁上添加和使用組件的管理員提供有關組件的信息。

第二個函數posts()返回可以在組件部分（ blogposts/default.htm文件）中使用的虛擬帖子，如下所示：

 url = "/blog" [blogPosts] == {% for post in blogPosts.posts %} {{ post }} {% endfor %}

為了讓十月 CMS 知道我們的組件存在，我們必須使用我們的主插件文件在名為registerComponents()的函數中註冊它：

 public function registerComponents() { return [ 'October\Demo\Components\Todo' => 'demoTodo' ]; }

創建自定義聯繫表單插件

我們將創建一個自定義聯繫表單插件。以下是關於插件應該如何工作的假設：

該表單將包含以下字段：名字、姓氏、電子郵件、消息。
數據將使用 Ajax 提交到服務器。
提交數據後，管理員將收到一封電子郵件，其中包含用戶發送的消息。

出於本教程的目的，我們將使用十月 CMS 的全新安裝：

讓我們通過在終端中運行將生成插件結構的命令開始創建我們的插件： php artisan create:plugin progmatiq.contactform

progmatiq.contactform參數包含作者姓名 (progmatiq) 和插件名稱 (contactform)。

現在我們需要打開我們的plugin.php文件並通過以下方法修改插件詳細信息：

 public function pluginDetails() { return [ 'name' => 'Contact Form', 'description' => 'A simple contact form plug-in', 'author' => 'progmatiq', 'icon' => 'icon-leaf' ]; }

以下是您應該查看的其他一些方法：

registerComponents()
在這裡，您可以定義插件提供的一組組件。
registerPermissions()
您可以註冊自定義權限，以後可以在應用程序的其他區域使用這些權限。
registerNavigation()
您可以將帶有 URL 的自定義菜單項添加到管理儀表板菜單。

現在讓我們創建我們的ContactForm組件：

在插件的根目錄中創建一個名為components/的新文件夾。
在components/文件夾中創建一個名為contactForm.php的文件。

粘貼以下代碼，告訴十月我們的組件做了什麼。我們可以通過在組件內部創建一個名為componentDetails()的方法來做到這一點。

 <?php namespace Progmatiq\Contactform\Components; use Cms\Classes\ComponentBase; class ContactForm extends ComponentBase { public function componentDetails() { return [ 'name' => 'Contact Form', 'description' => 'A simple contact form' ]; } }

現在我們需要在插件中註冊我們的組件。為此，我們修改registerComponents()方法：

 public function registerComponents() { return [ 'Progmatiq\Contactform\Components\ContactForm' => 'contactForm', ]; }

此函數返回我們插件提供的組件數組。組件的完整類名是此方法中的鍵，值是別名，我們將使用它來引用 Twig 模板中的組件。

一旦我們註冊了組件，我們就可以創建一個新的聯繫頁面並添加我們的組件（步驟中的數字參考截圖）：

在您的管理儀表板中，轉到CMS (1) >頁面(2)，然後單擊 +添加(3)。
為您的頁面命名和 URL (4)。
命名您的文件 (5) 並選擇默認佈局 (6)。

讓我們將新組件添加到頁面中：

單擊左側菜單 (1) 中的組件，然後選擇我們的“聯繫表”組件。一旦你點擊它 (2)，它就會被添加到頁面中。
我們需要放置一段代碼，為頁面提供標題，並使用{% component 'contactForm' %} Twig 指令呈現組件：

 <div class="container"> <h1> Contact </h1> {% component 'contactForm' %} </div>

如果您現在打開您的聯繫頁面，您將看到標題為“聯繫”，而沒有其他內容。

那是因為我們的聯繫表單沒有任何要呈現的 HTML。

我們需要在components/文件夾中創建一個contactform/default.htm文件。

向我們的組件添加一個 html 視圖 — 向我們的組件添加 HTML 視圖（大預覽）

並將以下 HTML 代碼添加到文件中：

 <form method="POST" data-request="onSend" data-request-validate data-request-success="this.reset(); alert('Thank you for submitting your inquiry')" > <div> <label for="first_name">First Name</label> <input type="text" name="first_name" class="form-control"> <p data-validate-for="first_name" class="text-danger"></p> </div> <div> <label for="last_name">Last Name</label> <input type="text" name="last_name" class="form-control"> <p data-validate-for="last_name" class="text-danger"></p> </div> <div> <label for="email">Email</label> <input type="text" name="email" class="form-control"> <p data-validate-for="email" class="text-danger"></p> </div> <div> <label for="content">Content</label> <textarea rows="6" cols="20" name="content" class="form-control"></textarea> <p data-validate-for="content" class="text-danger"></p> </div> <div> <button type="submit" class="btn btn-primary" data-attach-loading>Send</button> </div> </form>

大部分代碼都非常簡單。但是，它帶有特殊的 data-* 屬性，October 允許我們使用：

<form>標籤具有三個特殊屬性：
- data-request="onSend" 。這個屬性告訴October，當使用Ajax 提交表單時，必須調用來自我們組件（我們接下來要創建的）的onSend函數。
- 如果表單無效， data-request-validate將使用從服務器發送的錯誤來啟用表單 Ajax 驗證。
- data-request-success="this.reset(); alert('Thank you for submitting your inquiry')"清除表單，然後在請求成功且不存在驗證或服務器端錯誤時觸發警報消息。
每個輸入都有一個以下塊，負責顯示服務器為給定輸入返回的驗證錯誤：

 <p data-validate-for="content" class="text-danger"></p>

提交按鈕具有data-attach-loading屬性，該屬性將在服務器處理請求時添加一個微調器並禁用該按鈕。這樣做是為了防止用戶在前一個請求完成之前再次提交表單。

這是我們的頁面現在的樣子：

讓我們回到我們的contactForm.php組件並創建onSend()以及validate()輔助方法來負責處理表單提交：

 public function onSend() { // Get request data $data = \Input::only([ 'first_name', 'last_name', 'email', 'content' ]); // Validate request $this->validate($data); // Send email $receiver = '[email protected]'; \Mail::send('progmatiq.contact::contact', $data, function ($message) use ($receiver) { $message->to($receiver); }); } protected function validate(array $data) { // Validate request $rules = [ 'first_name' => 'required|min:3|max:255', 'last_name' => 'required|min:3|max:255', 'email' => 'required|email', 'content' => 'required', ]; $validator = \Validator::make($data, $rules); if ($validator->fails()) { throw new ValidationException($validator); } }

我們要做的第一件事是從請求中獲取數據並使用validate()輔助方法對其進行驗證。（您可以使用的所有可用驗證規則都可以在文檔中找到。）如果驗證失敗，則validate()方法將拋出ValidationException異常並且代碼執行將停止，服務器將響應狀態碼406和驗證消息。

如果驗證成功，那麼我們將向我們的管理員發送一封電子郵件。

注意：為簡單起見，我假設我們要將提交發送到的電子郵件是 [email protected]。 確保使用您自己的電子郵件！

這是您的contactForm.php插件的完整代碼：

 <?php namespace Progmatiq\Contactform\Components; use Cms\Classes\ComponentBase; use October\Rain\Exception\ValidationException; class ContactForm extends ComponentBase { public function componentDetails() { return [ 'name' => 'Contact Form', 'description' => 'A simple contact form' ]; } public function onSend() { // Get request data $data = \Input::only([ 'first_name', 'last_name', 'email', 'content' ]); // Validate request $this->validate($data); // Send email $receiver = '[email protected]'; \Mail::send('progmatiq.contact::contact', $data, function ($message) use ($receiver) { $message->to($receiver); }); } protected function validate(array $data) { // Validate request $rules = [ 'first_name' => 'required|min:3|max:255', 'last_name' => 'required|min:3|max:255', 'email' => 'required|email', 'content' => 'required', ]; $validator = \Validator::make($data, $rules); if ($validator->fails()) { throw new ValidationException($validator); } } }

如您所見， Mail::send()函數接受的第一個參數是將要為電子郵件正文呈現的電子郵件模板的名稱。我們需要在管理面板中創建它。轉到設置 > 郵件模板，然後單擊新建模板按鈕。然後填寫表格，如下面的屏幕所示：

這是我們將要使用的電子郵件的正文：

 You have received a new contact inquiry **First Name**: {{ first_name }} *** **Last Name**: {{ last_name }} *** **Email**: {{ email }} *** **Message**: {{ content }} ***

現在保存電子郵件模板。我們需要做的下一件事是配置將發送電子郵件的 SMTP 服務器。

轉到設置 > 郵件配置並填寫所有設置。