استخدام موصلات مخرج الإضافات (Plugin Outlet Connectors) من سمة أو إضافة

[Discourse]

يتضمن 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>.

ℹ️ إزالة عنصر التغليف التلقائي

تعرض منافذ المكونات الإضافية الحديثة (مع defaultGlimmer=true) الموصلات كـ “مكونات glimmer للقالب فقط”، وهي أسرع بكثير في العرض وليس لها عنصر تغليف. في النهاية، سيتم استخدام هذا في كل مكان.

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

import templateOnly from "@ember/component/template-only";
export default templateOnly();

إذا كنت بحاجة إلى منطق مخصص أيضًا، فراجع أقسام الأخرى أدناه.

استخدام وسائط المنفذ

توفر منافذ المكونات الإضافية معلومات حول السياق المحيط عبر @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>

ℹ️ طرق الوصول القديمة إلى الوسائط

في العديد من منافذ المكونات الإضافية، من الممكن افتراضيًا الوصول إلى الوسائط باستخدام {{argName}} أو {{this.argName}}. في الوقت الحالي، لا يزال هذا يعمل في المنافذ الحالية.

تقوم منافذ المكونات الإضافية الجديدة (مع @defaultGlimmer={{true}}) بعرض الموصلات كمكونات glimmer للقالب فقط، والتي لا تحتوي على سياق this. في النهاية، سيتم ترحيل منافذ المكونات الإضافية الحالية أيضًا إلى هذا النمط. تقنية @outletArgs هي الأفضل لأنها ستعمل باستمرار في كل من منافذ المكونات الإضافية الكلاسيكية وglimmer.

إضافة منطق أكثر تعقيدًا

في بعض الأحيان، لا يكون قالب 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>

ℹ️ طرق قديمة لتعريف منطق معقد

في الإصدارات الأقدم من Discourse، لم يكن من الممكن تصدير تعريف مكون مخصص. بدلاً من ذلك، كان بإمكانك تصدير كائن يحتوي على وظيفتي setupComponent(args, component) و teardownComponent(component). لم يتم إهمال هذه التقنية القديمة رسميًا بعد، ولكننا نوصي بالتحول إلى نهج تصدير المكون الجديد للمضي قدمًا.

العرض الشرطي

إذا كنت تريد عرض المحتوى الخاص بك فقط في ظل ظروف معينة، فغالبًا ما يكون من الكافي تغليف القالب الخاص بك باستخدام كتلة {{#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) إلى إعادة تقييم الدالة.

ℹ️ shouldRender لموصلات القالب فقط

إذا كنت ترغب في تعريف دالة shouldRender بدون الحمل الزائد لمكون كامل، يمكنك القيام بشيء كهذا:

import templateOnly from "@ember/component/template-only";

export default Object.assign(templateOnly(), {
  shouldRender(outletArgs, helper) {
    // Logic here
  },
});

ℹ️ تطبيقات shouldRender القديمة

التتبع التلقائي (Autotracking): قبل Discourse 3.1، كان يتم تقييم shouldRender أثناء العرض الأولي فقط. لن تؤدي التغييرات في الخصائص المشار إليها إلى إعادة تقييم الدالة.

صيغة غير الفئة (Non-class syntax): في الوقت الحالي، لا يزال تعريف دالة shouldRender في كائن جافاسكريبت عادي (غير فئة) مدعومًا، ولكننا نوصي بالانتقال إلى صيغة قائمة على الفئة أو قائمة على القالب فقط للمضي قدمًا.

تقديم منافذ جديدة

إذا كنت بحاجة إلى منفذ غير موجود بعد، فلا تتردد في تقديم طلب سحب (pull request)، أو فتح موضوع في Dev.

---

يتم التحكم في إصدار هذه الوثيقة - اقترح تغييرات على github.