Discourse 플러그인 개발 - 1부 - 기본 플러그인 만들기

[Discourse]

Discourse에서 플러그인을 만드는 것은 몇 가지 특이한 점을 익히면 정말 간단할 수 있습니다. 이 글의 목표는 스켈레톤 플러그인을 생성하고 기본 개념을 소개하는 것입니다.

개발 환경

컴퓨터에서 Discourse 개발 환경이 실행 중인지 확인하세요. 해당 설정 가이드를 사용하는 것을 권장하며, 완료 후 다시 돌아오시기 바랍니다.

plugin.rb

https://github.com/discourse/discourse-plugin-skeleton을 사용하여 플러그인 디렉터리에서 완전한 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 개발에 익숙하다면, 플러그인은 리로딩(reloading) 측면에서 다소 불편할 수 있다는 점을 알게 될 것입니다. 일반적으로 플러그인에 변경 사항을 적용한 후에는 Ctrl+c를 눌러 서버를 중지한 후, bin/dev를 사용하여 다시 실행해야 합니다.

변경 사항이 반영되지 않았습니다!

때로는 캐시가 완전히 정리되지 않을 수 있으며, 특히 새 파일을 생성하거나 기존 파일을 삭제할 때 그렇습니다. 이 문제를 해결하려면 tmp 폴더를 삭제하고 rails를 다시 시작하세요. Mac에서는 한 명령어로 수행할 수 있습니다: rm -rf tmp; bin/dev.

플러그인이 로드되었는지 확인하기

로컬 서버를 재시작한 후 /admin/plugins URL을 방문하세요(플러그인 레지스트리는 관리자만 볼 수 있으므로 먼저 관리자 계정으로 로그인했는지 확인하세요).

모든 것이 정상적으로 작동했다면 목록에서 플러그인을 볼 수 있어야 합니다:

축하합니다, 이제 첫 번째 플러그인을 만든 것입니다!

자바스크립트 추가하기

현재 플러그인은 아무것도 하지 않습니다. Discourse가 로드될 때 알림(alert) 상자를 표시하는 자바스크립트 파일을 추가해 보겠습니다. 이는 사용자에게 매우 귀찮을 수 있으며 실제 플러그인으로는 권장되지 않지만, 실행 중인 애플리케이션에 자바스크립트를 삽입하는 방법을 보여줍니다.

다음 파일을 생성하세요:

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에 배치된 자바스크립트 파일은 Discourse 애플리케이션이 로드될 때 자동으로 실행됩니다.

2. 이 특정 파일은 name과 initialize 함수를 가진 하나의 객체를 export합니다.

3. name은 고유해야 하므로 alert라고 이름 붙였습니다.

4. initialize() 함수는 애플리케이션이 로드될 때 호출됩니다. 우리의 경우, 이 함수는 단순히 우리의 alert() 코드를 실행할 뿐입니다.

이제 공식적인 Discourse 플러그인 개발자가 되었습니다!

---

시리즈의 나머지 부분

Part 1: 이 주제
Part 2: Plugin Outlets
Part 3: Site Settings
Part 4: git setup
Part 5: Admin interfaces
Part 6: Acceptance tests
Part 7: Publish your plugin

---

이 문서는 버전 관리되고 있습니다 - 변경 사항을 github에서 제안할 수 있습니다.

[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:

https://github.com/discourse/discourse/commit/d4bbdcd7d63ddbf20239c95d1ba1cee9030d7e95

[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.