يتضمن Discourse مئات من منافذ المكونات الإضافية (Plugin Outlets) التي يمكن استخدامها لحقن محتوى جديد أو استبدال المحتوى الموجود في واجهة مستخدم Discourse. تتوفر “وسائط منفذ المكون الإضافي” (Outlet arguments) بحيث يمكن تخصيص المحتوى بناءً على السياق.
اختيار منفذ
للعثور على اسم منفذ المكون الإضافي، ابحث في نواة Discourse عن “<PluginOutlet”، أو استخدم مكون السمة مواقع منافذ المكونات الإضافية. (على سبيل المثال: topic-above-posts).
منافذ التغليف (Wrapper outlets)
تبدو بعض المنافذ في النواة كالتالي: <PluginOutlet @name="foo" />. تتيح لك هذه المنافذ حقن محتوى جديد. ستقوم منافذ أخرى “بتغليف” تطبيق أساسي موجود بالشكل التالي:
<PluginOutlet @name="foo">
core implementation
</PluginOutlet>
يؤدي تعريف موصل (connector) لهذا النوع من منافذ المكونات الإضافية “التغليفية” إلى استبدال التطبيق الأساسي. يمكن لمكون سمة/إضافة واحد نشط فقط المساهمة بموصل لمنفذ مكون إضافي تغليفي.
بالنسبة لمنافذ المكونات الإضافية التغليفية، يمكنك عرض تطبيق النواة الأصلي باستخدام الكلمة المفتاحية {{yield}}. قد يكون هذا مفيدًا إذا كنت تريد فقط استبدال تطبيق النواة في ظل ظروف معينة، أو إذا كنت ترغب في تغليفه بشيء ما.
تعريف القالب
بمجرد اختيار منفذ، حدد اسمًا للموصل الخاص بك. يجب أن يكون هذا الاسم فريدًا عبر جميع السمات/المكونات الإضافية المثبتة في مجتمع معين. على سبيل المثال: brand-official-topics
في السمة/المكون الإضافي الخاص بك، قم بتعريف قالب handlebars جديد بمسار منسق بهذا الشكل:
{theme}/javascripts/discourse/connectors/{outlet-name}/{connector-name}.hbs
{plugin}/assets/javascripts/discourse/connectors/{outlet-name}/{connector-name}.hbs
سيتم عرض محتوى هذه الملفات كمكون Ember. للحصول على معلومات عامة حول Ember / Handlebars، راجع أدلة Ember.
بالنسبة لموصل “مواضيع الفريق الرسمية” الافتراضي لدينا، قد يبدو القالب كما يلي:
<div class="alert alert-info">
This topic was created by a member of the
<a href="https://discourse.org/team">Discourse Team</a>
</div>
ستقوم بعض منافذ المكونات الإضافية بتغليف المحتوى الخاص بك تلقائيًا في عنصر HTML. يتم تعريف نوع العنصر بواسطة @connectorTagName على <PluginOutlet>.
استخدام وسائط المنفذ
توفر منافذ المكونات الإضافية معلومات حول السياق المحيط عبر @outletArgs. تختلف الوسائط الممررة إلى كل منفذ. طريقة سهلة لعرض الوسائط هي إضافة هذا إلى القالب الخاص بك:
{{log @outletArgs}}
سيؤدي هذا إلى تسجيل الوسائط في وحدة تحكم مطور المتصفح لديك. ستظهر ككائن Proxy - لاستكشاف قائمة الوسائط، قم بتوسيع [[Target]] الوكيل.
في مثالنا topic-above-posts، يكون الموضوع المعروض متاحًا ضمن @outletArgs.model. لذلك يمكننا إضافة اسم المستخدم للعضو في الفريق كما يلي:
<div class="alert alert-info">
This topic was created by
{{@outletArgs.model.details.created_by.username}}
(a member of the
<a href="https://discourse.org/team">Discourse Team</a>)
</div>
إضافة منطق أكثر تعقيدًا
في بعض الأحيان، لا يكون قالب handlebars بسيط كافيًا. لإضافة منطق Javascript إلى الموصل الخاص بك، يمكنك تعريف ملف Javascript مجاور لقالب handlebars الخاص بك. يجب أن يقوم هذا الملف بتصدير تعريف مكون. يعمل هذا تمامًا مثل أي تعريف مكون آخر، ويمكن أن يتضمن حقن الخدمة.
يؤدي تعريف مكون بهذه الطريقة إلى إزالة عنصر التغليف التلقائي connectorTagName، لذلك قد ترغب في إعادة تقديم عنصر من نفس النوع في ملف hbs الخاص بك.
في مثالنا topic-above-posts، قد نرغب في عرض المستخدم بشكل مختلف بناءً على إعداد الموقع “تحديد أولوية اسم المستخدم في تجربة المستخدم”. قد يبدو تعريف المكون لذلك شيئًا كهذا:
.../connectors/topic-above-posts/brand-official-topic.js:
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;
}
}
}
يمكننا بعد ذلك تحديث القالب للإشارة إلى المُحَصِّل الجديد:
<div class="alert alert-info">
This topic was created by
{{this.displayName}}
(a member of the
<a href="https://discourse.org/team">Discourse Team</a>)
</div>
العرض الشرطي
إذا كنت تريد عرض المحتوى الخاص بك فقط في ظل ظروف معينة، فغالبًا ما يكون من الكافي تغليف القالب الخاص بك باستخدام كتلة {{#if}} في handlebars. إذا لم يكن ذلك كافيًا، فقد ترغب في استخدام الخطاف shouldRender للتحكم فيما إذا كان سيتم عرض قالب الموصل الخاص بك على الإطلاق.
أولاً، تأكد من أن لديك تعريف موصل .js كما هو موضح أعلاه. ثم، أضف دالة ثابتة static shouldRender(). بتوسيع مثالنا:
import Component from "@glimmer/component";
import { getOwner } from "discourse-common/lib/get-owner";
export default class BrandOfficialTopics extends Component {
static shouldRender(outletArgs, helper) {
const firstPost = outletArgs.model.postStream.posts[0];
return firstPost.primary_group_name === "team";
}
// ... (أي منطق آخر)
}
الآن سيتم عرض الموصل فقط عندما يكون المنشور الأول في الموضوع قد تم إنشاؤه بواسطة عضو في الفريق.
يتم تقييم shouldRender في سياق التتبع التلقائي لـ Glimmer. ستؤدي التغييرات المستقبلية في أي خصائص مشار إليها (على سبيل المثال، outletArgs) إلى إعادة تقييم الدالة.
تقديم منافذ جديدة
إذا كنت بحاجة إلى منفذ غير موجود بعد، فلا تتردد في تقديم طلب سحب (pull request)، أو فتح موضوع في Dev.
يتم التحكم في إصدار هذه الوثيقة - اقترح تغييرات على github.
