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

يمكن أن يكون بناء إضافة (Plugin) في Discourse بسيطًا للغاية، بمجرد أن تتعرف على بعض التفاصيل الخاصة بالنظام. الهدف من هذا المنشور هو إنشاء هيكل أساسي للإضافة وتعريفك بالأساسيات.

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

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

plugin.rb

:tada: استخدم GitHub - discourse/discourse-plugin-skeleton: Template for Discourse plugins · GitHub لإنشاء هيكل أساسي كامل لإضافة في Discourse في مجلد الإضافات (plugins) الخاص بك :tada:

تم تضمين الهيكل الآن في نواة Discourse، الأمر rake plugin:create[plugin-name] سيقوم بإنشاء إضافة باستخدام الهيكل الأساسي

عند بدء تشغيل Discourse، يبحث في مجلد plugins عن المجلدات الفرعية التي تحتوي على ملف plugin.rb. لملف plugin.rb غرضان: فهو يعمل كقائمة تعريف (Manifest) لإضافتك مع المعلومات المطلوبة عنها، بما في ذلك اسمها، ومعلومات الاتصال بها، ووصفها. الغرض الثاني هو تهيئة أي كود 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

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

مسألة مهمة! (Gotcha)

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

لم يتم تطبيق تغييراتي! :warning:

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

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

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

إذا سارت كل الأمور على ما يرام، يجب أن ترى إضافتك في القائمة:

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

لنقم بإضافة بعض كود JavaScript

حاليًا، إضافتك لا تقوم بأي شيء. لنقم بإضافة ملف javascript يعرض صندوق تنبيه (alert box) عند تحميل 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. يتم تنفيذ ملفات JavaScript الموضوعة في assets/javascripts/discourse/initializers تلقائيًا عند تحميل تطبيق Discourse.

  2. هذا الملف المعين exports كائنًا واحدًا، يحتوي على خاصية name ودالة initialize.

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

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

تحميل البيانات مسبقًا للواجهة الأمامية (Frontend)

استخدم register_preloaded_data في plugin.rb لتضمين البيانات في استجابة HTML الأولية دون الحاجة إلى طلب إضافي:

after_initialize do
  register_preloaded_data("visibility") do |guardian|
    { can_access: guardian.authenticated? }
  end
end

تضيف النواة (Core) بادئة مفتاح البيانات إلى بيانات وصف الإضافة # name:. للإضافة basic-plugin أعلاه، اقرأ القيمة المحللة في مهيئ الواجهة الأمامية (frontend initializer) باستخدام:

import PreloadStore from "discourse/lib/preload-store";

const visibility = PreloadStore.get("basic-plugin:visibility");

يتم تنفيذ الكتلة (block) لكل تحميل صفحة يعرض تخطيط التطبيق، وتتلقى الـ Guardian الخاص بالطلب، وتعيد قيمة قابلة للترميز إلى JSON. هذه القيم منفصلة عن حمولة الموقع المخزنة مؤقتًا للزوار المجهولين (anonymous site payload). أعد nil لحذف مدخل من السجل؛ سيتم تضمين false. يتم تخطي كتل الإضافات المعطلة. قم بتقييد البيانات الحساسة للمستخدم الطالب من خلال الـ Guardian.

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


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

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


هذا المستند خاضع لإصدار التحكم بالإصدارات - اقترح التغييرات على GitHub.

110 إعجابات
Plugin API documentations?
How to create a new plugins?
Connecting to database with a plugin
Separating View from Data, Plugins, Modularity
Categories Topic Replies
Added custom initializer
Create fully custom header
Overwriting controllers in plugin
How can I add "dislike" button?
Developing Discourse Plugins - Part 2 - Connect to a plugin outlet
Which files can you override from a plugin?
Developing Discourse Plugins - Part 5 - Add an admin interface
How to transfer data from plugin to app/views templates?
Which is Better? Discourse or Flarum?
Hide features for non-admin users through plugin
Customizing handlebars templates
How to properly display jalali dates for Persian language
Topic Ratings Plugin
Enable Like-Button for not logged-in visitors
Why do I need a block storage?
Custom Field not working
Rails plugin generator
Why GNU License?
Code reading help. ES6, plugin-outlet `_connectorCache`, custom-html `_customizations`, appEvents
Customizing handlebars templates
Application Files after Digital Ocean Setup
Application Files after Digital Ocean Setup
Application Files after Digital Ocean Setup
Make an external http request from discourse
Specify user by external id
How can I make my own Discourse plugins?
Reputation and level on member profile
How to Change User Profile Picture
Something like shortcodes for Discourse?
Calendar plugin features to make it really useful for us
Plugin Documentation Style Guide
Any options for over-riding the username restrictions?
How would updating effect custom overrides?
I would like to change the template completely
Adding a second tag description
Rails plugin generator
Creating a plugin
Fatal: Not a git repository (or any parent up to mount point /discourse)
Fatal: Not a git repository (or any parent up to mount point /discourse)
Adding command line tools support for user api keys
Discourse Code Modification for personal use
Plugin routing problems
[PAID] Mentorship needed
Can You Restrict Signups Using `swot` Email Verification?
Plugin API documentations?
Insert tag based upon word match
Triggering account creation/login on external service when a user logs in on discourse
Place for total coding beginners to learn how to customise?
Add additional button post menu
Fetch third party data for topic list
The Ignore User feature (now in 2.3.0.beta7)
Help with a plugin
Create Custom APIs
Proper Development and Deployment
How to make only a group of users can send messages to staff
How might we better structure #howto?
Theme-Component v Plugin: What's the difference
Creating Parsing Extensions
How can I customized my own site
All latest images in posts from a category
(Ruby) Selecting only posts that are made by non-original posters
Hosting discourse on our infrastructure AWS
Display FullName instead of UserName in the Profile
Calling Python scripts w/ arguments on the backend via plugin?
Extend Existing Controller?
How to add custom fields to models
Extend Existing Controller?
Bot writer's tip: Processing every post
Add user to group after purchase
Support for proposed plug-in
Autocompletion for a user field at signup
Custom discourse with limited features
Overriding user_guardian.rb in a plugin (no fork necessary!)
Problems with git clone
Friendly user profile url
Website Integration
Discourse developement environment setup
How to show Full Name in Embeds
How to display full name in comments embeds
Rake task "assets:precompile" is failing due to JS Compilation issue
Change code does not work in VS Studio code editor
Edit Code
Discourse Chain Topics Plugin
Contributing to Discourse
How to edit topics/show.html.erb
Install Discourse on macOS for development
Developing Discourse Plugins - Part 3 - Add custom site settings
Developing Discourse Plugins - Part 4 - Setup git
Developing Discourse Plugins - Part 7 - Publish your plugin
Developing Discourse Plugins - Part 6 - Add acceptance tests
Learn how to start building stuff for Discourse if you're newbie (like myself)
How to disable updating username for admins & moderators?
Backend code
Backend code
Install Discourse on Ubuntu or Debian for Development
How to make changes on backend side of discourse application using rails
Introduction to Discourse Development
Discourse blog (article and comments)
How to learn more about Discourse back-end?
I want to learn how to program for Discourse
Discourse Audio Message
Create custom Automations
How can one add a toggle button to the post menu and implement an action for that toggle button in a Discourse plugin?
Content box
Create an advertising page
Discourse 有自定义插件模板吗,如何写自定义插件呢
Deploy custom Discourse repository via docker
Multiple custom fields for topics similar to custom userfields
How do I go about making a very customized theme?
How can I create a Discourse that's just like Stemaway.com?
Adding new columns to user lists in groups
How to pin a post within a topic?
Ruby script to send automatic welcome message to new users
:cn: Installing the Discourse development environment on Ubuntu 在 Ubuntu 上安装 Discourse 开发环境
Admin not accessible because of auto-minify for Cloudflare
Admin not accessible because of auto-minify for Cloudflare
Update Password Encryption Method
Store pdf and doc files as raw text in the database - Where to start?
How to turn off "Body seems unclear, is it a complete sentence?'
Hosting dynamic pages with discourse
Invisible way to force display order of tags?
Controllers and Routes
Learn about Discourse client-side flow?
How do you learn to build Discourse plugins?
How do you learn to build Discourse plugins?
Discourse 部署成功后如何接入小程序、APP?
I'm trying to run discourse app locally in production env without docker
Customizing CSS via plugin
About the Plugin category
Visual diagraming to add visual dimension to Conversations?
Custom Onebox engine
How can I install my own plugin written in Ruby?
Allow reply-to individual instead of topic/forum (mailing list feature)
Adapt github changes to my own site
Push to digital ocean from command line and rebuild
How to convince my university to use/install Discourse?
Hack to enable invitations for Trust level 1 users
Dropcaps in Discourse - cannot override span tag
Getting certain posts to Zapier
Plugin: add a menu icon (next to search)
Error When creating custom plugin
Error When creating custom plugin
IOTA as a currency for Discourse
New columns in directory (/users)
Bootstrap fails when plugin file specifies gem version range
Running my own discourse image
How to add a job to cron/anacron when creating Docker container

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?

إعجاب واحد (1)

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.

13 إعجابًا

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.

إعجاب واحد (1)

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

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.

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.

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?

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.

5 إعجابات

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

إعجاب واحد (1)

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

3 إعجابات

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.

4 إعجابات

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

إعجابَين (2)

Hopefully this will prevent others from making this mistake:

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

6 إعجابات

Hi,

Is this url correct? Shouldn’t this be ,

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

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


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

11 إعجابًا

@vinothkannans Thank you a lot for the explanation. :slight_smile:

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?

إعجابَين (2)

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.

إعجابَين (2)

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.

إعجابَين (2)

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

4 إعجابات