تطوير إضافات Discourse - الجزء 2 - الاتصال بمنفذ إضافة

[Discourse]

البرنامج التعليمي السابق: Developing Discourse Plugins - Part 1 - Create a basic plugin

---

البدء: قوالب Handlebars

تمت كتابة تطبيق العميل الخاص بـ Discourse باستخدام إطار عمل Javascript Ember.js. يستخدم Ember Handlebars لجميع قوالب HTML. يوجد مقدمة ممتازة للغة القوالب في هذا الرابط، لذا تأكد من قراءتها بعناية.

المشكلة: إضافة عناصر إلى واجهة مستخدم Discourse

تحتاج العديد من الإضافات إلى إضافة وتوسيع واجهة الويب الخاصة بـ Discourse. نحن نوفر آلية للقيام بذلك تسمى “منافذ الإضافات” (plugin outlets) في قوالب Handlebars.

إذا تصفحت قوالب Handlebars الخاصة بـ Discourse، فسترى غالبًا ترميز HTML التالي:

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

هذا يعلن عن منفذ إضافة يسمى “edit-topic”. إنها نقطة توسيع في القالب يمكن لمؤلفي الإضافات الاستفادة منها لإضافة ترميز Handlebars الخاص بهم.

عند تأليف الإضافة الخاصة بك، ابحث في قوالب Handlebars الخاصة بـ Discourse (في ملفات .hbs) التي تريد تغييرها عن <PluginOutlet />. إذا لم يكن هناك واحد، فقط اطلب منا توسيعه! سنسعد بإضافتها إذا كان لديك حالة استخدام جيدة. إذا كنت تريد أن تجعل الأمر أسهل وأسرع بالنسبة لنا للقيام بذلك، يرجى إرسال طلب سحب (pull request) على github!

إذا كنت ترغب في رؤية بعض الأماكن التي توجد فيها منافذ الإضافات، يمكنك تشغيل الأمر التالي إذا كنت تستخدم OSX أو Linux:

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

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

الاتصال بمنفذ الإضافة

بمجرد العثور على منفذ الإضافة الذي تريد الإضافة إليه، يجب عليك كتابة “موصل” (connector) له. الموصل هو في الأساس قالب Handlebars يحتوي اسمه على connectors/<اسم المنفذ> فيه.

على سبيل المثال، إذا كان قالب Handlebars الخاص بـ Discourse يحتوي على:

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

فإن أي ملفات Handlebars تنشئها في الدليل connectors/evil-trout سيتم إلحاقها تلقائيًا. لذا، إذا أنشأت الملف:

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

بالمحتويات:

<b>Hello World</b>

سيقوم Discourse بإدراج <b>Hello World</b> في تلك النقطة في القالب.

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

استكشاف الأخطاء وإصلاحها

• تحقق مرتين من اسم الموصل وتأكد من مطابقته لاسم الإضافة تمامًا.

مزيد من المعلومات

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.