开发 Discourse 插件 - 第五部分 - 添加管理界面

上一个教程:Developing Discourse Plugins - Part 4 - Setup git


有时站点设置不足以满足插件所需的管理界面。例如,如果你安装了 discourse-akismet 插件,你可能会注意到它在你的 Discourse 的管理插件部分添加了一个导航项:

在本教程中,我们将向你展示如何为你的插件添加一个管理界面。为了纪念我最喜欢的电脑游戏之一,我将我的插件命名为 purple-tentacle。说真的,我真的很喜欢那个游戏

设置管理路由

让我们从像前几部分教程中那样添加一个 plugin.rb 开始。

plugin.rb

# name: purple-tentacle
# about: A sample plugin showing how to add a plugin route
# version: 0.1
# authors: Robin Ward
# url: https://github.com/discourse/purple-tentacle

add_admin_route 'purple_tentacle.title', 'purple-tentacle'

Discourse::Application.routes.append do
  get '/admin/plugins/purple-tentacle' => 'admin/plugins#index', constraints: StaffConstraint.new
end

add_admin_route 这一行告诉 Discourse 此插件需要在 /admin/plugins 页面上有一个链接。它的标题将是来自我们的 i18n 翻译文件中的 purple_tentacle.title,它将链接到 purple-tentacle 路由。

下面的几行代码设置了我们插件路由的服务器端映射。Discourse 做的一个假设是,前端几乎每一个路由都有一个提供数据的服务器端路由。对于这个示例插件,我们实际上不需要任何后端数据,但我们需要告诉 Discourse 在用户直接访问 /admin/plugins/purple-tentacle 时提供一些内容。这一行只是告诉它:“嘿,如果用户直接在服务器端访问该 URL,就提供默认的插件内容!”

(如果这让你感到困惑,不用太担心,我们将在未来的教程中回到这个问题,届时我们将处理服务器端操作。)

接下来,我们将添加一个模板,当用户访问 /admin/plugins/purple-tentacle 路径时将显示该模板。它将只是一个按钮,当用户点击该按钮时,会显示一个紫色触手的动画 gif:

assets/javascripts/discourse/templates/admin/plugins-purple-tentacle.hbs

{{#if tentacleVisible}}
  <div class="tentacle">
    <img src="https://eviltrout.com/images/tentacle.gif" />
  </div>
{{/if}}

<div class="buttons">
  <DButton
    @label="purple_tentacle.show"
    @action={{action "showTentacle"}}
    @icon="eye"
    @id="show-tentacle"
  />
</div>

如果你已经学习了 handlebars 的基础知识,这个模板应该很容易理解。 <DButton /> 是 Discourse 中的一个组件,我们用它来显示一个带有标签和图标的按钮。

为了连接我们的新模板,我们需要创建一个路由映射:

assets/javascripts/discourse/purple-tentacle-route-map.js

export default {
  resource: "admin.adminPlugins",
  path: "/plugins",
  map() {
    this.route("purple-tentacle");
  },
};

路由映射是我们添加到 discourse 中的一个东西,它使得插件可以向 ember 应用程序添加路由。map() 中的语法与 Ember 的路由器非常相似。在这个例子中,我们的路由映射非常简单,它只是在 /admin/plugins 下声明了一个名为 purple-tentacle 的路由。

最后,让我们添加我们的翻译字符串:

config/locales/client.en.yml

en:
  js:
    purple_tentacle:
      title: "Purple Tentacle"
      show: "Show Purple Tentacle"

如果你重启开发服务器,你应该能够在 /admin/plugins 看到我们的链接!如果点击它,你会看到一个显示我们紫色触手的按钮:

不幸的是,当你点击按钮时,什么也没发生 :frowning:

如果你查看开发者控制台,你应该会看到一个提供线索的错误,说明了原因:

Uncaught Error: Nothing handled the action 'showTentacle'

啊,是的,原因是我们的 handlebars 模板依赖于两件事:

  1. 用户点击按钮时,会调用 showTentacle
  2. showTentacle 应该将属性 tentacleVisible 设置为 true,以便图像显示出来。

如果你还没有阅读 Ember 关于控制器 的指南,现在是阅读的好时机,因为我们将为我们的 purple-tentacle 模板实现一个控制器来处理这个逻辑。

创建以下文件:

assets/javascripts/discourse/controllers/admin-plugins-purple-tentacle.js

import Controller from "@ember/controller";
import { action } from "@ember/object";
import { tracked } from "@glimmer/tracking";

export default class AdminPluginsPurpleTentacleController extends Controller {
  @tracked tentacleVisible = false;

  @action
  showTentacle() {
    this.tentacleVisible = true;
  }
}

现在当我们刷新页面时,点击按钮就会显示我们的动画角色!

我把添加一个点击时隐藏触手的按钮留给读者作为额外的练习 :smile:

如果你在让这个插件的你的版本正常工作时遇到困难,我已经把它推到了 github


系列中的更多内容

第 1 部分:插件基础知识
第 2 部分:插件插槽
第 3 部分:站点设置
第 4 部分:Git 设置
第 5 部分:本主题
第 6 部分:验收测试
第 7 部分:发布你的插件


本文档已版本控制 - 在 github 上建议更改。

28 个赞

Hm, doesn’t seem to work on my local side… did anyone face the same problem?

What’s the problem? If you install the purple tentacle plugin does it not work?

edit: issue resolved. it works!

@eviltrout nope, it doesn’t work. I believe @ladydanger is also facing the same problem.
nothing appears in the site settings or plugins tabs.
I tried both following the instructions as well as symlink-ing your plugin (dl-ed from github).
I then tried to create server.en.yml, client.en.yml, settings.yml following the format of other plugins, but the image wouldn’t render anyhow.

probably something wrong with the …route-map.js.es6 or config files.

interestingly enough, akismet’s plugin does work for me.


One issue that keeps on biting me is that I still need to do

rm -fr /tmp/cache

To kick away some odd caching we have in some cases.

1 个赞

@eviltrout

oh now this is an interesting finding - apparently our ad plugins were interfering with the purple-tentacle plugin. or the other way round. it works now, after having removed the ad plugin files.

  • it now works with our ad plugins! possibly some minor bug yesterday. all is good!

@sam, what’s the difference between rm -rf tmp and rm -fr /tmp/cache

I usually only delete the cache directory, no need to nuke the entire tmp directory.

2 个赞

Are you sure it was a plugin conflict?

I copied it into my localhost plugin folder and started up the VM without removing the temp folder and got the same results as you posted.

I was puzzled to see the route in object dot notation but ignored that.

I then started up the VM and did remove the temp folder and all was OK

1 个赞

Actually, sometimes you need just cache, and sometimes you need the whole tmp directory.

Maybe we could have an initializer that checks the timestamps on the plugin folders and nukes tmp if they were updated (dev only).

3 个赞

One thing I really should have warned you about is I started raising errors on ember deprecations. We are really working towards upgrading our version of Ember soon and I wanted to make sure developers caught them. It’s possible your plugin has a deprecation or two and is now raising an error with the latest version of Discourse.

If you can’t figure out how to fix the deprecation, it’s okay to temporarily disable it in the Discourse working directory you are using. Try removing these two lines.

2 个赞

No clue what I’m doing wrong here, but it shows up like this:

It must be the /config/locales/en.yml not loading, but why?

I put this file structure in the root of the plugin directory. Verified it’s there, nuked the tmp, restart rails.

en:
  js:
    purple_tentacle:
      title: "Purple Tentacle"
      show: "Show Purple Tentacle"
1 个赞

I was a bit surprised to see the file named “en.yml” but figured either eviltrout knew something I didn’t (which I’m sure he does … anyway) or that maybe something had changed the way things worked.

I’m guessing that what Robin meant was client,en.yml because that works for me.

the file goes in the plugins config/locales folder

4 个赞

Thanks I’ll try that after I get my dev environment setup on the xeon, went through hell getting ubuntu 16.04 to work right with my hardware. Turned out it wasn’t the server mobo, but the new nvidia card.

Yea I meant I put all the directories listed hierarchically starting with the plugins folder. Was wondering if for some reason that last file went elsewhere.

Same thing.

I tried naming the file client,en.yml, client.en.yml, and creating a client folder placing en.yml inside it.

Same result

Did you stop vagrant, clear the cache
$> rm -rf tmp
and restart vagrant?

I’m not using vagrant, yes I nuked tmp, restart rails.

This is a bit too annoying, and not a big deal. I’m going to move forward, but thanks for the efforts.

I have a feeling you may have the folder structure wrong, or maybe the naming. Mine is like

/discourse
../plugins
..../{yourpluginname}
......plugin.rb
....../config
........settings.yml
......../locales
..........client.en.yml
..........server.en.yml
....../assets
......../javascripts
........../discourse
............{yourpluginname}-route-map.js.es6
............/controllers
..............admin-plugins-{yourpluginname}.js.es6
............/templates
............../admin
................plugins-{yourpluginname}.hbs
1 个赞

That’s the file structure I have.

I don’t see a point in getting stuck on this, already hacked together a couple of rails sites and trying to absorb as much as possible.

Just going to leave this as some simple error on my part that I’ll come look back at later on and probably realize right away what it was.

Thanks, thou

Another mistake of mine! I’ve updated the OP, thanks.

2 个赞

Is there any way I can change a global plugin setting, say, a siteSetting, from here?
I need admins to be able to use this interface to add data into a global array.