استخدام واجهة برمجة تطبيقات DModal لعرض نوافذ Modal (المعروفة أيضًا باسم النوافذ المنبثقة/الحوارات) في Discourse

[Discourse]

يأتي Discourse 3.1.0.beta6 مع واجهة برمجة تطبيقات (API) جديدة تمامًا قائمة على المكونات DModal.

يحل هذا محل واجهة برمجة التطبيقات القديمة القائمة على المتحكم (controller-based API)، والتي أصبحت الآن مهملة. إذا كان لديك نوافذ منبثقة (modals) حالية تستخدم واجهات برمجة التطبيقات القديمة، فراجع دليل الترحيل هنا.

عرض نافذة منبثقة (Rendering a Modal)

يتم عرض النوافذ المنبثقة عن طريق تضمين المكون DModal في قالب handlebars. إذا لم يكن لديك قالب مناسب بالفعل، فراجع Using Plugin Outlet Connectors from a Theme or Plugin.

قد تبدو النافذة المنبثقة البسيطة شيئًا كهذا:

<DButton
  @translatedLabel="Show Modal"
  @action={{fn (mut this.modalIsVisible) true}}
/>

{{#if this.modalIsVisible}}
  <DModal @title="My Modal" @closeModal={{fn (mut this.modalIsVisible) false}}>
    Hello world, this is some content in a modal
  </DModal>
{{/if}}

يتم استخدام مساعد mut هنا كطريقة خاصة بـ hbs لتعيين قيمة. يمكنك أيضًا تعيين modalIsVisible باستخدام أي طريقة Ember قياسية أخرى.

سيؤدي هذا المثال إلى إنشاء نافذة منبثقة بسيطة كهذه:

التغليف في مكون (Wrapping in a component)

قبل إدخال المزيد من التعقيد، من الأفضل عادةً تغليف النافذة المنبثقة الجديدة في تعريف المكون الخاص بها. لننقل محتويات DModal إلى داخل تعريف مكون جديد MyModal /.

{{! components/my-modal.hbs }}
<DModal @title="My Modal" @closeModal={{@closeModal}}>
  Hello world, this is some content in a modal
</DModal>

سيسمح لك تقديم ملف مكون .js مصاحب بإدخال منطق وحالة أكثر تعقيدًا.

لاستخدام المكون الجديد، قم بتحديث موقع الاستدعاء للإشارة إليه، مع التأكد من تمرير وسيطة @closeModal.

<DButton
  @translatedLabel="Show Modal"
  @action={{fn (mut this.modalIsVisible) true}}
/>

{{#if this.modalIsVisible}}
  <MyModal @closeModal={{fn (mut this.modalIsVisible) false}} />
{{/if}}

إضافة تذييل (Adding a footer)

تحتوي العديد من النوافذ المنبثقة على نوع من الدعوة إلى اتخاذ إجراء (call-to-action). في Discourse، تميل هذه إلى أن تكون موجودة في الجزء السفلي من النافذة المنبثقة. لجعل هذا ممكنًا، يحتوي DModal على عدد من “الكتل المسماة” (named blocks) التي يمكن عرض محتوى بداخلها. إليك المثال المحدث لتضمين زرين في التذييل، أحدهما هو زر DModalCancel القياسي الخاص بنا:

<DModal @title="My Modal" @closeModal={{@closeModal}}>
  <:body>
    Hello world, this is some content in a modal
  </:body>
  <:footer>
    <DButton class="btn-primary" @translatedLabel="Submit" />
    <DModalCancel @close={{@closeModal}} />
  </:footer>
</DModal>

عرض نافذة منبثقة من سياق غير hbs (Rendering a modal from a non-hbs context)

من الناحية المثالية، يجب عرض مثيلات DModal من داخل قالب Ember handlebars باستخدام التقنية التصريحية الموضحة أعلاه. إذا لم يكن ذلك ممكنًا لحالة الاستخدام الخاصة بك (على سبيل المثال، تحتاج إلى تشغيل نافذة منبثقة من أنظمة العرض القديمة “raw-hbs” أو “widget” في Discourse)، فيمكن القيام بذلك عن طريق حقن خدمة modal واستدعاء modal.show().

تأكد من أنك قمت بتغليف النافذة المنبثقة الخاصة بك في المكون الخاص بها كما هو موضح أعلاه. بعد ذلك، قم بتشغيل النافذة المنبثقة عن طريق تمرير مرجع لفئة المكون الخاص بك إلى showModal:

import MyModal from "discourse/components/my-modal";

// (حقن خدمة modal في المكان ذي الصلة)

// أضف هذا الاستدعاء كلما أردت فتح النافذة المنبثقة.
// سيتم تمرير وسيطة `@closeModal` إلى المكون الخاص بك تلقائيًا.
this.modal.show(MyModal);

// اختياريًا، قم بتمرير معلمة 'model'. يتم تمريرها كـ `@model` إلى المكون الخاص بك.
// يمكن أن يشمل هذا البيانات، وكذلك الإجراءات/ردود الاتصال لاستخدامها من قبل النافذة المنبثقة الخاصة بك.
this.modal.show(MyModal, {
  model: { topic: this.topic, someAction: this.someAction },
});

// `modal.show()` تُرجع وعدًا (promise)، لذا يمكنك الانتظار حتى يتم إغلاقها
// سيتم حلها بالبيانات المارة إلى إجراء `@closeModal`
const result = await this.modal.show(MyModal);

المزيد من التخصيص! (More customizability!)

يحتوي DModal على عدد من الكتل المسماة (named blocks) والوسائط (arguments). راجع دليل الأنماط التفاعلي للوسائط، و تنفيذ قالب d-modal للكتل المسماة.

---

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