Discourse 插件新手开发指南 - 第1部分(Beginner’s Guide to Creating Discourse Plugins - Part 1)


(Cheng Zheng) #1

原文地址请点击这里

1. 说明

这里是边读边翻,纯属个人爱好,
不保证太多东西(比如 part1 到 part6 全部翻译完)
翻译采取意译为主。以阅读流畅,意思准确为主。


Discourse 插件新手开发指南 - 第1部分

(Beginner’s Guide to Creating Discourse Plugins - Part 1)

给 Discourse 制作插件非常简单。
本帖目的是做一个基本结构出来,给你介绍基础。

你的开发环境(Your development environment)

先在本地机跑起来 Discourse。建议阅读 这篇文章
等本地跑起来了再往下继续读。

plugin.rb

Discourse 启动时,会看 plugins/ 目录,
看里面哪些子文件夹有 plugin.rb 文件。

plugin.rb 文件有 2 个目的:

  1. 存放插件的重要信息,比如:名字,联系方式,描述
  2. 插件运行所必要的初始化代码

在下面的例子里,我们不会添加 Ruby 代码,不过依然要 plugin.rb 文件。

首先在 discourse/plugins/ 创建 basic-plugin 文件夹。
文件夹里新建一个 plugin.rb 文件,内容如下:

basic-plugin/plugin.rb

# name: basic-plugin
# about: A super simple plugin to demonstrate how plugins work
# version: 0.0.1
# authors: Awesome Plugin Developer

弄好后重启 rails 服务器,插件就载入了。

重要说明(An important Gotcha!)

如果你习惯了 Ruby on Rails 开发,你会注意到插件开发不太一样.
每次对插件代码做了修改,你应该 Ctrl+C 停止服务器,
然后 bundle exec rails server. 再开启服务器。这样代码才会生效

重启后还是没有变化! :warning:(My changes weren’t picked up! :warning:

有时候缓存会导致这个问题,解决方法是删掉 tmp 文件夹然后重启 Rails,
Mac 上一条命令搞定:rm -rf tmp; bundle exec rails s

确定插件的确载入成功了(Checking that your plugin was loaded)

重启 Rails 服务器之后可以访问 URL /admin/plugins
(确保你是管理员身份登录,只有管理员看得到)

如果一切正常,你应该会看到插件:
image

恭喜!你刚做了第一个插件!

加点 Javasciprt(Let’s add some Javascript)

现在你的插件什么都没做。
我们来加一个 Javascript 文件,在 discourse 载入时弹一个框出来。
注意:不建议实际环境中用这样的插件。会很烦人。这里只是演示。

创建如下文件:

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

export default {
  name: 'alert',
  initialize() {
    alert('alert boxes are annoying!');
  }
};

现在重启服务器,再次访问首页应该会看到 alert boxes are annoying! 这句话。

我们来回顾下工作原理:

  1. assets/javascripts/discourse/initializers 里面的 Javascript 文件会在 Discourse 载入时执行

  2. 它 exports 一个对象,有一个 name(名字) 和一个初始化函数。

  3. name 不能重名,这里直接叫 alert

  4. initialize() 函数会在程序载入时执行,所以运行了里面唯一一行代码:alert()

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

接下来阅读

Part 2: Plugin Outlets
Part 3: Site Settings
Part 4: git setup
Part 5: Admin interfaces
Part 6: Acceptance tests