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

[Discourse]

Previous tutorial: Developing Discourse Plugins - Part 1 - Create a basic plugin

---

入门：Handlebars 模板

Discourse 的客户端应用程序是使用 Ember.js Javascript 框架编写的。Ember 在所有 HTML 模板中使用 Handlebars。该链接提供了对模板语言的出色介绍，因此请务必仔细阅读。

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

许多插件需要添加和扩展 Discourse Web 界面。我们提供了一种称为“插件插口”（plugin outlets）的机制来实现此目的，该机制存在于 Handlebars 模板中。

如果您浏览 Discourse Handlebars 模板，您会经常看到以下标记：

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

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

在编写插件时，请在您想要修改的 Discourse Handlebars 模板（在 .hbs 文件中）中查找 <PluginOutlet />。如果没有，请告诉我们进行扩展！如果您有好的用例，我们将很乐意添加它们。如果您想让我们做得更容易、更快，请在 github 上提交一个 pull request！

如果您想查看插件插口存在的一些位置，如果您使用的是 OSX 或 Linux，可以运行以下命令：

git grep "<PluginOutlet" -- "*.hbs"

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

连接到插件插口

找到要添加到的插件插口后，您必须为其编写一个 connector。Connector 实际上只是一个 Handlebars 模板，其文件名中包含 connectors/<outlet name>。

例如，如果 Discourse Handlebars 模板包含：

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

那么您在 connectors/evil-trout 目录中创建的任何 Handlebars 文件都将自动追加到此处。因此，如果您创建了文件：

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

内容如下：

<b>Hello World</b>

Discourse 会将 <b>Hello World</b> 插入到模板中的该位置。

请注意，我们将文件命名为 hello.hbs——文件名的最后一部分并不重要，但它在所有插件中必须是唯一的。将其命名为描述您要扩展的功能的内容会很有用。这将使将来调试更容易。

故障排除

• 仔细检查 connector 的名称，确保它与插件名称完全匹配。

更多信息

Using Plugin Outlet Connectors from a Theme or Plugin

Discourse includes hundreds of Plugin Outlets which can be used to inject new content or replace existing contend in the Discourse UI. ‘Outlet arguments’ are made available so that content can be customized based on the context. Choosing an outlet To find the name of a plugin outlet, search Discourse core for “<PluginOutlet”, or use the plugin outlet locations theme component. (e.g. topic-above-posts). Wrapper outlets Some outlets in core look like <PluginOutlet @name="foo" />. These allow you…

---

系列中的更多内容

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

---

此文档是版本控制的 - 在 github 上建议更改。

[kennym (Kenny Meyer)]

Is there a list of plugin outlets?

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

[cpradio]

@kennym

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

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

[kennym (Kenny Meyer)]

Yes, that’s what I am searching for.

[eviltrout (Robin Ward)]

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

[Andrew_Byrne]

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

[Andrew_Byrne]

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

Multiple topics in single API request

Using the Discourse API is pretty cool and I’ve used it to provide a number of custom interrogations in related sites. One thing that has caused me some issues is the fact I need to make single requests on each topic via: GET discourse.foo/t/topicID/1234.json for most Discourse systems this is cool but I am blending results, ie requesting multiple topics and adding them to a single post feed. when the number increases the requests become… annoying. I’m looking for a solution something along t…

[andrewroth]

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?

[eviltrout (Robin Ward)]

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

[kourou (Ilias)]

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

[1c7 (Cheng Zheng)]

2018-4-28 work for me!

1. Plugin Outlet name

2. Code

3. Result

[sarahann (Sarah)]

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?

[merefield (Robert)]

@sarahann

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.

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!

[sarahann (Sarah)]

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

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.

[merefield (Robert)]

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

[sarahann (Sarah)]

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

[merefield (Robert)]

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 :).

[Mittineague]

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.

[sarahann (Sarah)]

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

[pfaffman (Jay Pfaffman)]

I think you can probably hide those with CSS.