开发 Discourse 插件 - 第一部分 - 创建一个基础插件

[Discourse]

在了解了一些特殊之处后，构建 Discourse 插件会非常简单。本文的目标是创建一个骨架插件并向您介绍基础知识。

您的开发环境

请确保您的计算机上运行着 Discourse 的开发环境。我建议您使用相应的设置指南，并在完成后再回来。

plugin.rb

使用 GitHub - discourse/discourse-plugin-skeleton: Template for Discourse plugins 在您的 plugins 目录中创建一个完整的 Discourse 插件骨架

该骨架现已捆绑在 Discourse 核心中，rake plugin:create[plugin-name] 将使用该骨架创建一个插件

当 Discourse 启动时，它会在 plugins 目录中查找包含 plugin.rb 文件的子目录。plugin.rb 文件有两个用途：它是插件的清单，包含有关插件的必要信息，包括：名称、联系信息和描述。第二个用途是初始化运行插件所需的任何 Ruby 代码。

在我们的例子中，我们不会添加任何 Ruby 代码，但仍然需要 plugin.rb。让我们创建目录 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
# url: https://github.com/yourusername/basic-plugin

创建此文件后，您应该重启本地服务器，插件就会被加载。

一个重要的陷阱！

如果您习惯于常规的 Rails 开发，您可能会注意到插件在重新加载方面并不那么方便。通常，当您对插件进行更改时，您应该按住 \u003ckbd\u003eCtrl\u003c/kbd\u003e+\u003ckbd\u003ec\u003c/kbd\u003e 停止服务器运行，然后使用 bin/ember-cli -u 再次运行它。

我的更改没有生效！

有时缓存不会完全清除，尤其是在您创建新文件或删除旧文件时。要解决此问题，请删除您的 tmp 文件夹并重新启动 Rails。在 Mac 上，您可以用一个命令完成：rm -rf tmp; bin/ember-cli -u。

检查插件是否已加载

重启本地服务器后，访问网址 /admin/plugins（请确保您以管理员帐户登录后，因为只有管理员才能看到插件注册表）。

如果一切正常，您应该会在列表中看到您的插件：

\u003cimg src="//assets-meta-cdck-prod-meta.s3.dualstack.us-west-1.amazonaws.com/original/3X/4/7/47a4b274553bd1fb0bba2d2df699ac136ad6a5cc.png" width="690" height="104"\u003e

恭喜，您刚刚创建了您的第一个插件！

让我们添加一些 Javascript

目前您的插件没有任何作用。让我们添加一个 Javascript 文件，它将在 Discourse 加载时弹出一个警告框。这对任何用户来说都非常烦人，不建议作为实际插件，但这将展示如何将 Javascript 插入到我们正在运行的应用程序中。

创建以下文件：

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

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

现在，如果您重启本地服务器，屏幕上应该会出现“alert boxes are annoying!”。（如果未出现，请参阅上面的“我的更改没有生效”标题）。

让我们逐步分析它是如何工作的：

1. 放置在 assets/javascripts/discourse/initializers 中的 Javascript 文件在 Discourse 应用程序加载时会自动执行。

2. 此特定文件 export 一个对象，该对象具有 name 和 initialize 函数。

3. name 必须是唯一的，所以我只是称它为 alert。

4. initialize() 函数在应用程序加载时被调用。在我们的例子中，它所做的只是执行我们的 alert() 代码。

您现在是一名官方的 Discourse 插件开发者了！

---

系列中的更多内容

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

---

\u003csmall\u003e本文档已版本控制 - 在 github 上 建议更改。\u003c/small\u003e

[Ishan_Dutta]

I am able to create plugin in development, it works fine. Thanks.
But I don’t see a way to install other’s plugin in development
So first question is how can I fork someone’s plugin in development and then build on top of that(hope copy paste that repo is not the recommended way)?
Second question is, it seems my created plugin is part of my repo, is there a way to create a separate github repo for the plugin automatically which others can directly use to install?

[eviltrout (Robin Ward)]

I have a preferred method to do this. First, I have a ~/code directory where I have all my git projects. So I check out discourse and the plugin in that directory so it’s something like this:

~/code

discourse
discourse-some-plugin

Then, within the ~/code/discourse/plugins folder I create a symlink to the plugin:

$ cd ~/code/discourse/plugins
$ ln -s ~/code/discourse-some-plugin .

Then for good measure:

$ cd ~/code/discourse
$ rm -rf tmp
$ bundle exec rails server

Now you can fork the plugin in ~/code/discourse-some-plugin, make pull requests or whatever you want. It’ll be used by discourse.

[Jithin_Krishnan]

What is the best way to render ajax response inside a widget?
I was able to console.log the ajax response, but it is not rendering inside the widget.

Tried to call this.scheduleRerender() after getting ajax response but both results in an infinite loop.

[Jithin_Krishnan]

I am getting following error when trying to load a helper module inside my widget

Could you please help me to resolve this error?
Thanks

[eviltrout (Robin Ward)]

@Jithin_Krishnan

What is the best way to render ajax response inside a widget?

You should make sure your widget can contain state. After the ajax request, set it on the state object and trigger a this.scheduleRerender and it should appear. For an example look at how the post menu shows who liked something.

@Jithin_Krishnan

I am getting following error when trying to load a helper module inside my widget

Looks like you have the wrong path to your helper. One way to see all the paths that Discourse has resolved is by typing require._eak_seen in your console. Look for the correct path name.

[Jithin_Krishnan]

Thanks Robin Ward for your help. I was able to load my module after investigating with require._eak_seen.

Below is the code for my widget. The problem is that this.scheduleRerender() is causing an infinite loop. The div always shows loading animation (even without this.scheduleRerender) which seems this.state.loading is not being set.

import { createWidget } from 'discourse/widgets/widget';
import { getTopic } from 'discourse/plugins/my-plugin/discourse/helpers/topics';
import { ajax } from 'discourse/lib/ajax';
import { h } from 'virtual-dom';

export default createWidget('topic-widget', {
  tagName: 'div.my-topics',
  defaultState() {
    return { loading: false};
  },

  refreshTopic() {
    if (this.state.loading) { return; }
    this.state.loading = true;
    this.state.topic = 'empty';
    getTopic(this).then((result) => {
      console.log(result);
      this.state.topic = result;
      this.state.loading = false;
      this.scheduleRerender();
    });
  },

  html(attrs, state) {
    if (!state.topic) {
      this.refreshTopic();
    }
    const result = [];
    if (state.loading) {
      result.push(h('div.spinner-container', h('div.spinner')));
    } else if (state.topic !== 'empty') {
      result.push(state.topic);
    } else {
      result.push(h('div.no-messages', 'No topic.'))
    }

    return result;
  },
});

Could you help to resolve this error?

[eviltrout (Robin Ward)]

Your code looks mostly fine, however, all widgets that deal with state require a key attribute. You should have seen a warning about this, although maybe the warning only appears when running tests?

Try adding a buildKey function like buildKey: () => 'topic-widget'.

That should probably fix it. Also, a much less serious issue is you might want to add topic: null to your state object. Javascript is much faster when it knows the shape of the object in advance.

[Jithin_Krishnan]

Thanks Robin Ward.
Adding buildKey function worked fine for me.

[tgxworld (Alan Tan)]

@Jithin_Krishnan

The problem is that this.scheduleRerender() is causing an infinite loop.

@eviltrout

Your code looks mostly fine, however, all widgets that deal with state require a key attribute. You should have seen a warning about this, although maybe the warning only appears when running tests?

@eviltrout I got bitten by this in development and didn’t get a warning about setting a key attribute.

[eviltrout (Robin Ward)]

Ah, it only warns in Ember.testing:

https://github.com/discourse/discourse/blob/master/app/assets/javascripts/discourse/widgets/widget.js.es6#L153

We might want to just raise an error if that happens now? It is pretty dangerous for Widgets to do that.

[tgxworld (Alan Tan)]

for raising an error instead. Maybe we can extend that to development too?

[eviltrout (Robin Ward)]

Hopefully this will prevent others from making this mistake:

Raise an error if a widget doesn't have a key but uses state

[Sudaraka (Sudaraka Jayathilaka)]

Hi,

@eviltrout

but will show how to insert Javascript into our running application.

Create the following file:

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

Is this url correct? Shouldn’t this be ,

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

I’m new here. please correct me if im wrong

[vinothkannans (Vinoth Kannan)]

In Discourse, mainly there are two big JavaScript sections “discourse” and “admin”. Also you can see few more in https://github.com/discourse/discourse/tree/master/app/assets/javascripts.

In plugins, to differentiate admin & normal user section JavaScript files we use “discourse” and “admin” keywords in between like below

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

---

@Sudaraka

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

Also it will just work even without identification keywords like you mentioned

[Sudaraka (Sudaraka Jayathilaka)]

@vinothkannans Thank you a lot for the explanation.

[pacharanero (Marcus Baw)]

@clay

I was having trouble with Discourse seeing the plugin when I used a symlink (on MacOS High Sierra). I deleted the symlink and moved the plugin folder into the Discourse hierarchy and everything worked as expected. Maybe this will help others who run into a similar issue.

I’m experiencing the same issue with getting symlinks to work (I’m on Linux) - the ln -s appears to work, but from inside the docker container the path is inaccessible. The plugin works when it is directly copied into the plugins folder, but I like the symlink workflow as it enables a more sensible Git arrangment.

This SO question appears to suggest that symlinks won’t work this way unless we also add the linked-to plugin volume to the docker run command https://stackoverflow.com/questions/38485607/mount-host-directory-with-a-symbolic-link-inside-in-docker-container

Anyone any thoughts on this? What are the pro plugin developers doing for a sensible Git workflow?

[merefield (Robert)]

I’m using symlinks but my dev setup is Docker-frei.

Symlinks are a really nice way of being able to include or exclude plugins on a ‘build’ very quickly without disturbing the codebase.

[pacharanero (Marcus Baw)]

@pacharanero

I’m experiencing the same issue with getting symlinks to work (I’m on Linux) - the ln -s appears to work, but from inside the docker container the path is inaccessible. The plugin works when it is directly copied into the plugins folder, but I like the symlink workflow as it enables a more sensible Git arrangment.

Here’s what I’ve had to do in order to preserve a similar workflow to using symlinks (softlinks):

I edited /bin/docker/boot_dev in Discourse (outside the container) so that the plugin I want to work on is added as a volume and mounted in the /src/plugins/ directory (inside the container).

In my case it looks like this:

docker run -d -p 9405:9405 -p 1080:1080 -p 3000:3000 -p 9292:9292 \
-v "$DATA_DIR:/shared/postgres_data:delegated" \
-v "$SOURCE_DIR:/src:delegated" \ 
-v "/home/marcus/code/discourse/discourse-reflective-learning-plugin:/src/plugins/discourse-reflective-learning-plugin" \
$ENV_ARGS --hostname=discourse --name=discourse_dev --restart=always \
discourse/discourse_dev:release /sbin/boot

I’ve used absolute paths because I couldn’t be bothered to get into relative paths inside Docker and $SOURCE_DIR environment variables, but I’m sure there’s a cleverer way to do this, so that perhaps all your plugins could be in directories at the same level as discourse and it would automagically include them all. Hope this helps someone.

[sam (Sam Saffron)]

@pacharanero

I edited /bin/docker/boot_dev in Discourse

I am totally open to a PR that automatically follows symlinks in plugins/ dir and then smart mounts volumes.