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 个目的:
- 存放插件的重要信息,比如:名字,联系方式,描述
- 插件运行所必要的初始化代码
在下面的例子里,我们不会添加 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.
再开启服务器。这样代码才会生效
重启后还是没有变化!
(My changes weren’t picked up!
)
有时候缓存会导致这个问题,解决方法是删掉 tmp
文件夹然后重启 Rails,
Mac 上一条命令搞定:rm -rf tmp; bundle exec rails s
确定插件的确载入成功了(Checking that your plugin was loaded)
重启 Rails 服务器之后可以访问 URL /admin/plugins
(确保你是管理员身份登录,只有管理员看得到)
如果一切正常,你应该会看到插件:
恭喜!你刚做了第一个插件!
加点 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!
这句话。
我们来回顾下工作原理:
-
assets/javascripts/discourse/initializers
里面的 Javascript 文件会在 Discourse 载入时执行 -
它 exports 一个对象,有一个 name(名字) 和一个初始化函数。
-
name 不能重名,这里直接叫
alert
-
initialize()
函数会在程序载入时执行,所以运行了里面唯一一行代码:alert()
你现在是一名正式的 Discourse 插件开发者了!
接下来阅读
Part 2: Plugin Outlets
Part 3: Site Settings
Part 4: git setup
Part 5: Admin interfaces
Part 6: Acceptance tests