يتضمن Discourse مئات منافذ الإضافات (Plugin Outlets) التي يمكن استخدامها لحقن محتوى جديد أو استبدال المحتوى الحالي في واجهة مستخدم Discourse. يتم توفير “مُعاملات المنافذ” (Outlet arguments) لتمكين تخصيص المحتوى بناءً على السياق.
اختيار منفذ
للعثور على اسم منفذ إضافة، ابحث في نواة Discourse عن “<PluginOutlet”، أو استخدم مكون السمة مواقع منافذ الإضافات. (مثل: topic-above-posts).
منافذ الغلاف
بعض المنافذ في النواة تبدو مثل <PluginOutlet @name="foo" />. تتيح لك هذه المنافذ حقن محتوى جديد. بينما تقوم منافذ أخرى بـ “تغليف” تنفيذ أساسي موجود على النحو التالي:
<PluginOutlet @name="foo">
التنفيذ الأساسي
</PluginOutlet>
سيؤدي تعريف مُوصِّل (connector) لهذا النوع من منافذ “الغلاف” إلى استبدال التنفيذ الأساسي. يمكن لسمة أو إضافة نشطة واحدة فقط المساهمة بمُوصِّل لمنفذ إضافة من نوع الغلاف.
بالنسبة لمنافذ إضافة الغلاف، يمكنك عرض التنفيذ الأساسي الأصلي باستخدام الكلمة المفتاحية {{yield}}. قد يكون هذا مفيدًا إذا كنت ترغب في استبدال التنفيذ الأساسي فقط تحت ظروف معينة، أو إذا كنت ترغب في تغليفه بشيء ما.
تعريف المُوصِّل
بمجرد اختيارك لمنفذ، حدد اسمًا لمُوصِّلك. يجب أن يكون هذا الاسم فريدًا عبر جميع السمات / الإضافات المثبتة في مجتمع معين. على سبيل المثال: brand-official-topics
في سمة / إضافة الخاص بك، عرّف مُوصِّلًا جديدًا بامتداد .gjs بمسار بتنسيق مثل هذا:
{theme}/javascripts/discourse/connectors/{outlet-name}/{connector-name}.gjs
{plugin}/assets/javascripts/discourse/connectors/{outlet-name}/{connector-name}.gjs
سيتم عرض محتوى هذه الملفات كمكون Ember. للحصول على معلومات عامة حول Ember وتنسيق .gjs، راجع أدلة Ember.
بالنسبة لمُوصِّل “المواضيع الرسمية للعلامة التجارية” الافتراضي لدينا، قد يبدو الملف كما يلي:
<template>
<div class="alert alert-info">
تم إنشاء هذا الموضوع بواسطة عضو في
<a href="https://discourse.org/team">فريق Discourse</a>
</div>
</template>
استخدام مُعاملات المنافذ
توفر منافذ الإضافات معلومات حول السياق المحيط عبر @outletArgs. تختلف المُعاملات الممررة إلى كل منفذ. طريقة سهلة لعرض المُعاملات هي إضافة التالي إلى قالبك:
{{log @outletArgs}}
سيؤدي هذا إلى تسجيل المُعاملات في وحدة تحكم المطور في متصفحك. ستظهر ككائن Proxy - لاستكشاف قائمة المُعاملات، قم بتوسيع [[Target]] الخاص بالـ Proxy.
في مثال topic-above-posts لدينا، يتوفر الموضوع المعروض تحت @outletArgs.model. لذا يمكننا إضافة اسم مستخدم عضو الفريق على النحو التالي:
<template>
<div class="alert alert-info">
تم إنشاء هذا الموضوع بواسطة
{{@outletArgs.model.details.created_by.username}}
(عضو في
<a href="https://discourse.org/team">فريق Discourse</a>)
</div>
</template>
إضافة منطق أكثر تعقيدًا
في بعض الأحيان، لا يكون القالب البسيط كافيًا. لإضافة منطق JavaScript إلى مُوصِّلك، قم بترقية ملف .gjs الخاص بك لتصدير مكون قائم على الفئة. يعمل هذا تمامًا مثل أي تعريف مكون آخر، ويمكن أن يتضمن حقن الخدمات.
في مثال topic-above-posts لدينا، قد نرغب في عرض المستخدم بشكل مختلف بناءً على إعداد الموقع “أولوية اسم المستخدم في واجهة المستخدم”. قد يبدو ملف .gjs على النحو التالي:
.../connectors/topic-above-posts/brand-official-topic.gjs:
import Component from "@glimmer/component";
import { service } from "@ember/service";
export default class BrandOfficialTopics extends Component {
@service siteSettings;
get displayName() {
const user = this.args.outletArgs.model.details.created_by;
if (this.siteSettings.prioritize_username_in_ux) {
return user.username;
} else {
return user.name;
}
}
<template>
<div class="alert alert-info">
تم إنشاء هذا الموضوع بواسطة
{{this.displayName}}
(عضو في
<a href="https://discourse.org/team">فريق Discourse</a>)
</div>
</template>
}
العرض الشرطي
إذا كنت ترغب في عرض محتواك فقط تحت ظروف معينة، فقد يكون الأمر كافيًا في كثير من الأحيان تغليف قالبك بكتلة Handlebars {{#if}}. إذا لم يكن ذلك كافيًا، فقد ترغب في استخدام خطاف shouldRender للتحكم في ما إذا كان سيتم عرض قالب مُوصِّلك على الإطلاق.
أولاً، تأكد من وجود مُوصِّل .gjs قائم على فئة كما هو موضح أعلاه. ثم، أضف دالة static shouldRender(). موسعًا مثالنا:
import Component from "@glimmer/component";
export default class BrandOfficialTopics extends Component {
static shouldRender(outletArgs, helper) {
const firstPost = outletArgs.model.postStream.posts[0];
return firstPost.primary_group_name === "team";
}
// ... (أي منطق آخر)
<template>{{! ... }}</template>
}
الآن سيتم عرض المُوصِّل فقط عندما يكون المنشور الأول للموضوع قد تم إنشاؤه بواسطة عضو في الفريق.
يتم تقييم shouldRender في سياق تتبع تلقائي (autotracking) لـ Glimmer. أي تغييرات مستقبلية في أي خصائص مرجعية (مثل outletArgs) ستؤدي إلى إعادة تقييم الدالة.
إدخال منافذ جديدة
إذا كنت بحاجة إلى منفذ غير موجود بعد، فلا تتردد في تقديم طلب سحب (pull request)، أو فتح موضوع في Development.
يتم التحكم في إصدار هذا المستند - اقترح التغييرات على GitHub.
