在 Discourse 中构建插件其实非常简单,只要你了解几个小窍门。本文的目标是创建一个骨架插件,并向你介绍基础知识。
你的开发环境
请确保你的计算机上运行着 Discourse 的开发环境。我建议使用合适的安装指南,完成后再回来。
plugin.rb
使用 GitHub - discourse/discourse-plugin-skeleton: Template for Discourse plugins · GitHub 在你的 plugins 目录中创建一个完整的 Discourse 插件骨架
骨架现已包含在 Discourse 核心中,
rake plugin:create[plugin-name]将使用骨架创建一个插件
当 Discourse 启动时,它会查找 plugins 目录中包含 plugin.rb 文件的子目录。plugin.rb 文件有两个用途:它是你插件的清单,包含关于你插件的必需信息,包括:名称、联系信息和描述。第二个目的是初始化运行你插件所需的任何 Ruby 代码。
在我们的例子中,我们不会添加任何 Ruby 代码,但我们仍然需要 plugin.rb。让我们创建一个名为 basic-plugin 的目录,在其中创建一个名为 plugin.rb 的文件,内容如下:
basic-plugin/plugin.rb
# name: basic-plugin
# about: 一个演示插件工作原理的超简单插件
# version: 0.0.1
# authors: Awesome Plugin Developer
# url: https://github.com/yourusername/basic-plugin
创建此文件后,你应该重启本地服务器,插件应该会被加载。
一个重要陷阱!
如果你习惯常规 Rails 开发,可能会注意到插件在重新加载方面表现不佳。通常,当你更改插件时,应按 Ctrl+C 停止服务器运行,然后使用 bin/dev 再次运行它。
我的更改未被识别! 
有时缓存未完全清除,特别是当你创建新文件或删除旧文件时。为解决此问题,请删除你的 tmp 文件夹并重新启动 Rails。在 Mac 上,你可以用一个命令完成:rm -rf tmp; bin/dev。
检查你的插件是否已加载
重启本地服务器后,访问 URL /admin/plugins(请确保你先以管理员账户登录,因为只有管理员才能看到插件注册表)。
如果一切正常,你应该在列表中看到你的插件:
恭喜,你刚刚创建了第一个插件!
让我们添加一些 JavaScript
目前你的插件什么也不做。让我们添加一个 JavaScript 文件,当 Discourse 加载时弹出一个警告框。这对任何用户来说都非常烦人,不建议作为实际插件使用,但它将展示如何向正在运行的应用程序中插入 JavaScript。
创建以下文件:
plugins/basic-plugin/assets/javascripts/discourse/initializers/alert.js
export default {
name: "alert",
initialize() {
alert("alert boxes are annoying!");
},
};
现在,如果你重启本地服务器,你应该会在屏幕上看到“alert boxes are annoying!”。(如果没有,请参阅上面的“我的更改未被识别”标题)。
让我们逐步分析这是如何工作的:
-
放置在
assets/javascripts/discourse/initializers中的 JavaScript 文件会在 Discourse 应用程序加载时自动执行。 -
此特定文件
export一个对象,该对象具有name和initialize函数。 -
name必须唯一,所以我只称它为alert。 -
当应用程序加载时会调用
initialize()函数。在我们的例子中,它只执行我们的alert()代码。
预加载前端数据
在 plugin.rb 中使用 register_preloaded_data 将数据包含在初始 HTML 响应中,而无需额外的请求:
after_initialize do
register_preloaded_data("visibility") do |guardian|
{ can_access: guardian.authenticated? }
end
end
核心会用插件的 # name: 元数据为键添加前缀。对于上面的 basic-plugin,请在前端初始化器中读取解析后的值,如下所示:
import PreloadStore from "discourse/lib/preload-store";
const visibility = PreloadStore.get("basic-plugin:visibility");
该代码块会在渲染应用程序布局的每次页面加载时运行,接收请求的 Guardian,并返回可序列化为 JSON 的值。这些值与缓存的匿名站点载荷分开。返回 nil 以省略条目;false 会被包含。被禁用的插件的代码块会被跳过。通过 Guardian 将敏感数据范围限定为请求用户。
你现在是一名官方的 Discourse 插件开发者了!
系列更多教程
第 1 部分:本主题
第 2 部分:Plugin Outlets(插件出口)
第 3 部分:Site Settings(站点设置)
第 4 部分:Git 设置
第 5 部分:管理界面
第 6 部分:验收测试
第 7 部分:发布你的插件
本文档受版本控制 - 请在 GitHub 上建议修改。

