تطوير إضافات Discourse - الجزء الأول - إنشاء إضافة أساسية

[Discourse]

إنشاء إضافة في Discourse يمكن أن يكون أمرًا بسيطًا جدًا بمجرد أن تتعلم بعض التفاصيل الدقيقة. الهدف من هذا المنشور هو إنشاء هيكل أساسي لإضافة وتعريفك بالأساسيات.

بيئة التطوير الخاصة بك

تأكد من وجود بيئة تطوير لـ Discourse تعمل على جهاز الكمبيوتر الخاص بك. أنصحك باستخدام دليل الإعداد المناسب والعودة عندما تنتهي.

plugin.rb

استخدم GitHub - discourse/discourse-plugin-skeleton: Template for Discourse plugins · GitHub لإنشاء هيكل كامل لإضافة 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: إضافة بسيطة جدًا لتوضيح كيفية عمل الإضافات
# version: 0.0.1
# authors: مطور إضافات رائع
# url: https://github.com/yourusername/basic-plugin

بمجرد إنشاء هذا الملف، يجب عليك إعادة تشغيل الخادم المحلي الخاص بك، وسيتم تحميل الإضافة.

تحذير مهم!

إذا كنت معتادًا على تطوير Rails العادي، فقد تلاحظ أن الإضافات ليست بنفس السهولة عندما يتعلق الأمر بإعادة التحميل. بشكل عام، عند إجراء تغييرات على إضافتك، يجب عليك Ctrl+c لإيقاف تشغيل الخادم، ثم تشغيله مرة أخرى باستخدام bin/dev.

لم يتم التقاط التغييرات الخاصة بي!

أحيانًا لا يتم مسح ذاكرة التخزين المؤقت بالكامل، خاصة عند إنشاء ملفات جديدة أو حذف ملفات قديمة. للتغلب على هذه المشكلة، قم بإزالة مجلد tmp الخاص بك ثم ابدأ Rails مرة أخرى. على جهاز Mac، يمكنك القيام بذلك بأمر واحد: rm -rf tmp; bin/dev.

التحقق من تحميل إضافتك

بمجرد إعادة تشغيل الخادم المحلي الخاص بك، قم بزيارة الرابط /admin/plugins (تأكد من أنك تسجيل الدخول بحساب مدير أولاً، حيث يمكن للمديرين فقط رؤية سجل الإضافات).

إذا نجح كل شيء، فستظهر إضافتك في القائمة:

تهانينا، لقد أنشأت إضافتك الأولى!

دعنا نضيف بعض جافا سكريبت

حاليًا، إضافتك لا تفعل شيئًا. دعنا نضيف ملف جافا سكريبت سيظهر مربع تنبيه عند تحميل Discourse. سيكون هذا مزعجًا جدًا لأي مستخدم ولا يُنصح به كإضافة فعلية، لكنه سيوضح كيفية إدراج جافا سكريبت في تطبيقنا الجاري تشغيله.

أنشئ الملف التالي:

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

export default {
  name: "alert",
  initialize() {
    alert("مربعات التنبيه مزعجة!");
  },
};

الآن إذا قمت بإعادة تشغيل الخادم المحلي الخاص بك، يجب أن تظهر عبارة “مربعات التنبيه مزعجة!” على الشاشة. (إذا لم يحدث ذلك، راجع عنوان “لم يتم التقاط التغييرات الخاصة بي” أعلاه).

دعنا نتفحص كيفية عمل ذلك:

1. يتم تنفيذ ملفات جافا سكريبت الموجودة في assets/javascripts/discourse/initializers تلقائيًا عند تحميل تطبيق Discourse.

2. يقوم هذا الملف المحدد export بكائن واحد يحتوي على name ودالة initialize.

3. يجب أن يكون name فريدًا، لذا سميتُه ببساطة alert.

4. يتم استدعاء دالة initialize() عند تحميل التطبيق. في حالتنا، كل ما تفعله هو تنفيذ كود alert() الخاص بنا.

أنت الآن مطور إضافات رسمي لـ Discourse!

---

المزيد في السلسلة

الجزء 1: هذا الموضوع
الجزء 2: مخارج الإضافات
الجزء 3: إعدادات الموقع
الجزء 4: إعداد git
الجزء 5: واجهات الإدارة
الجزء 6: اختبارات القبول
الجزء 7: نشر إضافتك

---

هذا المستند خاضع للتحكم في الإصدارات - اقترح تغييرات على 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:

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.