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

[Discourse]

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

بيئة التطوير

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

plugin.rb

استخدم GitHub - discourse/discourse-plugin-skeleton: Template for Discourse plugins · GitHub لإنشاء هيكل كامل لإضافة 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/dev.

تغييراتي لم يتم التقاطها!

أحيانًا لا يتم مسح ذاكرة التخزين المؤقت (cache) بالكامل، خاصة عند إنشاء ملفات جديدة أو حذف ملفات قديمة. للتغلب على هذه المشكلة، احذف مجلد tmp وابدأ rails مرة أخرى. على جهاز Mac يمكنك القيام بذلك بأمر واحد: rm -rf tmp; bin/dev.

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

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

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

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

لنضيف بعض JavaScript

حاليًا، إضافتك لا تفعل شيئًا. لنضيف ملف javascript سيعرض مربع تنبيه (alert box) عند تحميل discourse. سيكون هذا مزعجًا للغاية لأي مستخدم ولا يُنصح به كإضافة فعلية، لكنه سيوضح كيفية إدراج JavaScript في تطبيقنا العامل.

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

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. هذا الملف بالتحديد exports كائنًا واحدًا، يحتوي على name ودالة initialize.

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

4. تُستدعى دالة initialize() عند تحميل التطبيق. في حالتنا، كل ما تفعله هو تنفيذ كود alert() الخاص بنا.

أنت الآن مطور إضافات Discourse معتمد!

---

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

الجزء 1: هذا الموضوع
الجزء 2: Plugin Outlets
الجزء 3: Site Settings
الجزء 4: git setup
الجزء 5: Admin interfaces
الجزء 6: Acceptance tests
الجزء 7: Publish your plugin

---

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