开发 Discourse 插件 - 第 2 部分 - 连接到插件出口

上一教程:Developing Discourse Plugins - Part 1 - Create a basic plugin


入门:模板

Discourse 的客户端应用是使用 Ember.js JavaScript 框架编写的。Ember 使用 模板 来生成 HTML。该链接提供了对模板语言的精彩介绍,请务必仔细阅读。

问题:向 Discourse 用户界面添加元素

许多插件需要向 Discourse 网页界面添加或扩展内容。我们提供了一种称为“插件插槽(plugin outlets)”的机制,用于在 Handlebars 模板中实现这一功能。

如果你浏览 Discourse 的模板,经常会看到如下标记:

<PluginOutlet @name="edit-topic" />

这声明了一个名为“edit-topic”的插件插槽。它是模板中的一个扩展点,插件作者可以利用它添加自己的标记。

在编写插件时,请查看你想要修改的 Discourse 模板(.gjs 文件),寻找 <PluginOutlet />。如果没有,请直接联系我们进行扩展!如果你有合理的用例,我们会很乐意添加。如果你想让我们更轻松、快速地完成这项工作,请在 GitHub 上提交拉取请求!

:exclamation: 如果你想查看插件插槽存在的位置,可以在符合 POSIX 标准的 shell 中运行以下命令:

git grep -A 1 "<PluginOutlet" -- "*.gjs"

你还可以通过启用 Discourse 开发者工具栏 在 Discourse 站点上显示插件插槽。只需在 Discourse 论坛的浏览器控制台中输入 enableDevTools(),然后点击页面左侧出现的插头图标。

连接到插件插槽

找到你想要添加的插件插槽后,需要为其编写一个 connector(连接器)。连接器是一个 .gjs 组件,其文件名路径中包含 connectors/<插槽名称>

例如,如果 Discourse 模板中有:

<PluginOutlet @name="evil-trout" />

那么你在 connectors/evil-trout 目录下创建的任何 .gjs 文件都将被自动追加。因此,如果你创建了文件:

plugins/hello/assets/javascripts/discourse/connectors/evil-trout/hello.gjs

内容如下:

<template>
  <b>Hello World</b>
</template>

Discourse 将在模板的该位置插入 <b>Hello World</b>

请注意,我们将文件命名为 hello.gjs —— 文件名(与目录名不同)并不重要,但它在所有插件中必须唯一。建议将其命名为能描述你扩展功能的名称,这将有助于未来的调试。

故障排查

  • 仔细检查连接器的名称,确保其与插件名称完全匹配。

更多信息


系列更多内容

第 1 部分:插件基础
第 2 部分:本文主题
第 3 部分:站点设置
第 4 部分:git 设置
第 5 部分:管理界面
第 6 部分:验收测试
第 7 部分:发布你的插件


本文档已进行版本控制 - 建议更改请 在 GitHub 上提交

38 个赞

Is there a list of plugin outlets?

More specifically I would like to know if one could modify the “create topic” template?

1 个赞

In what way? Add new fields to the composer area (like the tagging plugin does)?

Yes, that’s what I am searching for.

I’d take a look at the tagging plugin then. It might have all you want!

2 个赞

@eviltrout is there a way to output directly to JSON.
basically creating a new API endpoint?

Ahhhhhhhh. new to this whole “ruby fad” :smiley:
I have a partial solution that i’ll detail in:

Hi Robin,

The plugin-outlet-locations plugin seems to declare all the connectors with a register_asset line in plugin.rb. Starting here: discourse-plugin-outlet-locations/plugin.rb at master · Mittineague/discourse-plugin-outlet-locations · GitHub

Is that a necessary step?

Nope - that’s not necessary. All .es6 and .hbs files are loaded automatically in plugins.

4 个赞

I am still trying to figure out how plugins in Discourse work and I could use a little help.

I would like to modify the timeline scroll bar (in the right side of each topic). Actually, what I need to do is add some stuff (image/banner) below the scroll bar.
What template should I edit? Is there an existing plugin-outlet for that?

Thank you,
Ilias

2018-4-28 work for me!

1. Plugin Outlet name

2. Code

3. Result

7 个赞

This guide is great! I had my plugin showing in the /admin/plugins quite easily.

I was wondering though, how do you delete items from a template?

For privacy reasons, I wanted to delete the export to csv button in the /admin/users/list/active as well as the show emails button. But I didn’t find a plugin outlet connector for those parts of the UI.

I was trying to overwrite the following templates

/users-list-show.hbs
/users-list.hbs

with my plugin outlet.

But creating these files
/var/www/discourse/plugins/[my-plugin]/assets/javascripts/admin/templates/users-list-show.hbs
/var/www/discourse/plugins/[my-plugin]/assets/javascripts/admin/templates/users-list.hbs
and making changes to them didnt seem to work. Even after deleting the /var/www/discourse/tmp folder and restarting the server.

Is this the correct way to delete those buttons from the UI? Using css display: none; isn’t an option.

I feel like I am missing something really simple, any ideas?

Not a direct technical answer to your question but why would you want to do that?

Only the admins can do this. They usually have full control of the server most likely anyway and could read the database, so hiding a button is a bit futile: emails will also show up in the Email logs and on your mail service logs. I’m afraid site admins are going to see a lot of email addresses!

Admins have full control, they see everything (except passwords presumably), so this is normal.

If you are an admin, get used to the responsibility which comes with knowing all of this!

My concern was that moderators can access some things in the admin dashboard.
They can navigate to the ‘users’ tab and see the Export and the Show Emails buttons
image

We don’t want our moderators to be able to grab bulk emails like this.
I understand that the emails are visible on users profiles, but we didn’t want an easy way to get this information.

So I was trying to create a plugin that hides these buttons.

Could be wrong, but this suggests it’s not an issue … have you Impersonated a Mod?

Yes, the screenshot I took was from impersonating a mod.

We have a similar setup as the link you provided (Moderators ability to see emails inconsistent).

I’m not requesting the Discourse team makes any changes though, this isn’t an issue with Discourse.

I am trying customize Discourse for our situation. I was hoping that using a plugin outlet and referencing the files within that plugin was the right way to overwrite a template in Discourse. I just wasn’t able to successfully overwrite these files:

/users-list-show.hbs
/users-list.hbs

My changes never showed up. So I thought this plugin outlet topic could help

1 个赞

Perhaps someone else can chime in, but I’ve always seen Outlets as additive. You may need an override technique instead (via javascript/Ember). I’m still learning this myself :).

2 个赞

I’m thinking that if overriding a template is the goal that it might be better to do this with a theme instead of a plugin.

I was thinking that as well, but I didn’t want a user to swap their theme and be able to get different functionality. So I figured a plugin outlet would do the trick

I think you can probably hide those with CSS.

2 个赞