تطوير إضافات Discourse - الجزء 1 - إنشاء إضافة أساسية

[Discourse]

بناء إضافة (plugin) في Discourse يمكن أن يكون بسيطًا حقًا، بمجرد أن تتعلم بعض الخفايا. الهدف من هذا المنشور هو إنشاء هيكل أساسي للإضافة وتعريفك بالأساسيات.

بيئة التطوير الخاصة بك

تأكد من أن لديك بيئة تطوير Discourse قيد التشغيل على جهاز الكمبيوتر الخاص بك. أوصي باستخدام دليل الإعداد المناسب والعودة عندما تنتهي.

plugin.rb

استخدم GitHub - discourse/discourse-plugin-skeleton: Template for Discourse plugins لإنشاء هيكل إضافة Discourse كامل في دليل الإضافات الخاص بك

تم تجميع الهيكل الأساسي الآن في نواة Discourse، سيقوم rake plugin:create[plugin-name] بإنشاء إضافة باستخدام الهيكل الأساسي

عند بدء تشغيل Discourse، فإنه يبحث في دليل plugins عن الدلائل الفرعية التي تحتوي على ملف plugin.rb. لملف plugin.rb غرضان: فهو بمثابة بيان (manifest) لإضافتك مع المعلومات المطلوبة حول إضافتك بما في ذلك: اسمها ومعلومات الاتصال ووصفها. الغرض الثاني هو تهيئة أي كود Ruby ضروري لتشغيل إضافتك.

في حالتنا، لن نضيف أي كود Ruby ولكننا ما زلنا بحاجة إلى plugin.rb. لنقم بإنشاء الدليل basic-plugin مع الملف plugin.rb بداخله، بالمحتويات التالية:

basic-plugin/plugin.rb

# name: basic-plugin
# about: A super simple plugin to demonstrate how plugins work
# version: 0.0.1
# authors: Awesome Plugin Developer
# url: https://github.com/yourusername/basic-plugin

بمجرد إنشاء هذا الملف، يجب عليك إعادة تشغيل الخادم المحلي الخاص بك ويجب تحميل الإضافة.

نقطة مهمة يجب الانتباه إليها!

إذا كنت معتادًا على تطوير Rails العادي، فقد تلاحظ أن الإضافات ليست سهلة جدًا عندما يتعلق الأمر بإعادة التحميل. بشكل عام، عند إجراء تغييرات على إضافتك، يجب عليك إيقاف تشغيل الخادم باستخدام Ctrl+c، ثم تشغيله مرة أخرى باستخدام bin/ember-cli -u.

لم يتم تطبيق التغييرات التي أجريتها!

في بعض الأحيان لا يتم مسح ذاكرة التخزين المؤقت بالكامل، خاصة عند إنشاء ملفات جديدة أو حذف ملفات قديمة. للتغلب على هذه المشكلة، قم بإزالة مجلد tmp الخاص بك وقم بتشغيل Rails مرة أخرى. على جهاز Mac يمكنك القيام بذلك في أمر واحد: rm -rf tmp; bin/ember-cli -u.

التحقق من تحميل إضافتك

بمجرد إعادة تشغيل الخادم المحلي الخاص بك، قم بزيارة الرابط /admin/plugins (تأكد من تسجيل الدخول كحساب مسؤول أولاً، حيث يمكن للمسؤولين فقط رؤية سجل الإضافات).

إذا سار كل شيء على ما يرام، يجب أن ترى إضافتك في القائمة:

تهانينا، لقد أنشأت للتو إضافتك الأولى!

لنضف بعض Javascript

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

قم بإنشاء الملف التالي:

plugins/basic-plugin/assets/javascripts/discourse/initializers/alert.js

export default {
  name: "alert",
  initialize() {
    alert("alert boxes are annoying!");
  },
};

الآن إذا أعدت تشغيل الخادم المحلي الخاص بك، يجب أن ترى “alert boxes are annoying!” تظهر على الشاشة. (إذا لم يحدث ذلك، راجع العنوان “لم يتم تطبيق التغييرات التي أجريتها” أعلاه).

دعنا نحلل كيف نجح هذا:

1. يتم تنفيذ ملفات Javascript الموضوعة في assets/javascripts/discourse/initializers تلقائيًا عند تحميل تطبيق Discourse.

2. يقوم هذا الملف تحديدًا بـ export كائن واحد، يحتوي على name ودالة initialize.

3. يجب أن يكون name فريدًا، لذلك أسميته للتو alert.

4. يتم استدعاء الدالة initialize() عند تحميل التطبيق. في حالتنا، كل ما تفعله هو تنفيذ كود alert() الخاص بنا.
   أنت الآن مطور إضافات Discourse رسمي!

---

المزيد في السلسلة

الجزء 1: هذا الموضوع
الجزء 2: مخارج الإضافات (Plugin Outlets)
الجزء 3: إعدادات الموقع (Site Settings)
الجزء 4: إعداد Git
الجزء 5: واجهات المسؤول (Admin interfaces)
الجزء 6: اختبارات القبول (Acceptance tests)
الجزء 7: نشر إضافتك (Publish your plugin)

---

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