如何为discourse社区开发一个插件

开发 Discourse 插件 - 第一部分 - 创建一个基本插件

在 Discourse 中构建插件非常简单,只要你了解一些技巧。本文的目标是创建一个骨架插件,并向你介绍一些基础知识。

你的开发环境

确保你的计算机上运行着一个 Discourse 的开发环境。我建议你使用适当的设置指南,并在完成后再回到这里。

plugin.rb

:tada: 使用 GitHub - discourse/discourse-plugin-skeleton: Template for Discourse plugins 在你的插件目录中创建一个完整的 Discourse 插件骨架 :tada:

该骨架现在已捆绑在 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: 优秀插件开发者
# url: https://github.com/yourusername/basic-plugin

一旦你创建了这个文件,你应该重启你的本地服务器,插件应该会被加载。

一个重要的注意事项!

如果你习惯了常规的 Rails 开发,你可能会注意到插件在重新加载方面并不是那么友好。通常,当你对插件进行更改时,你应该使用 Ctrl+c 停止服务器运行,然后使用 bin/ember-cli -u 再次运行它。

我的更改没有被采纳! :warning:

有时缓存没有完全清除,特别是在你创建新文件或删除旧文件时。要解决这个问题,请删除你的 tmp 文件夹并重新启动 Rails。在 Mac 上,你可以用一个命令完成:rm -rf tmp; bin/ember-cli -u

检查你的插件是否已加载

一旦你重启了你的本地服务器,访问 URL /admin/plugins (确保你首先以管理员账户登录,因为只有管理员才能看到插件注册表)。

如果一切正常,你应该在列表中看到你的插件:

恭喜你,你刚刚创建了你的第一个插件!

让我们添加一些 JavaScript

现在你的插件没有任何作用。让我们添加一个 JavaScript 文件,在 Discourse 加载时弹出一个警告框。这对任何用户来说都会非常烦人,不建议将其作为实际插件使用,但这将展示如何将 JavaScript 插入到我们运行的应用程序中。

创建以下文件:

plugins/basic-plugin/assets/javascripts/discourse/initializers/alert.js

export default {
  name: 'alert',
  initialize() {
    alert('警告框很烦人!');
  }
};

现在,如果你重启你的本地服务器,你应该会在屏幕上看到“警告框很烦人!”的提示。(如果你没有看到,请参阅上面的“我的更改没有被采纳”标题)。

让我们逐步了解这是如何工作的:

  1. 放置在 assets/javascripts/discourse/initializers 中的 JavaScript 文件会在 Discourse 应用程序加载时自动执行。
  2. 这个特定的文件 export 一个对象,该对象具有 name 和一个 initialize 函数。
  3. name 必须是唯一的,所以我只是把它叫做 alert
  4. 当应用程序加载时,会调用 initialize() 函数。在我们的例子中,它所做的只是执行我们的 alert() 代码。

你现在是一名正式的 Discourse 插件开发人员了!


系列中的更多内容

第一部分:本主题
第二部分:插件出口
第三部分:站点设置
第四部分:git 设置
第五部分:管理界面
第六部分:验收测试
第七部分:发布你的插件