قوالب مُنشئ الـ Url

[Drew-ART (Drew)]

مكون متخصص جدًا لموقعي، ولكني سأشاركه هنا لأنه قد يكون مفيدًا. يضيف قالبًا إلى المُنشئ بناءً على سلسلة نصية في عنوان URL.

كانت هناك الكثير من المناقشات حول وجود قوالب مُنشئ للوسوم (tags). لم ينجح ذلك في حالة الاستخدام الخاصة بي، لذا قمت ببناء هذا بدلاً من ذلك. يمكن استخدامه عند الضرورة، أو تعديله قليلاً ليعمل مع الوسوم أيضًا.

جيت هب (Github): GitHub - focallocal/url-composer-templates: Reads url strings and adds template text to the composer if a match is found

قوالب مُنشئ عنوان URL (URL Composer Templates)

مكون سمة (Theme Component) لمنصة Discourse يقوم بملء المُنشئ مسبقًا بنص قالب بناءً على معلمات عنوان URL. مصمم للعمل بسلاسة مع Docuss لتوفير قوالب خاصة بالسياق لأنواع مختلفة من التفاعلات.

الميزات

• دعم معلمات عنوان URL: يكتشف تلقائيًا ?composer_template=X في عناوين URL ويطبق القالب المقابل.
• أنواع قوالب متعددة: قم بتكوين ما يصل إلى 6 قوالب مختلفة لأغراض مختلفة (تقرير، حضور، دعوة، قوالب مخصصة).
• فتح المُنشئ تلقائيًا: اختياريًا، يفتح المُنشئ تلقائيًا عند زيارة رابط Docuss بدون سلاسل (threads) موجودة.
• تطبيق مرن: يمكن تطبيق القوالب على المنشور الأول فقط، أو جميع الردود، أو كليهما.
• استمرارية الجلسة: يستخدم sessionStorage للحفاظ على اختيار القالب عبر تنقلات الصفحة.
• وضع التصحيح (Debug Mode): تمكين تسجيل مفصل لوحدة التحكم لاستكشاف أخطاء تطبيق القالب وإصلاحها.

التثبيت

1. تثبيت مكون السمة على Discourse:

   • انتقل إلى المسؤول (Admin) ← تخصيص (Customize) ← السمات (Themes).
   • انقر على “تثبيت” (Install) ← “من مستودع Git” (From a Git repository).
   • أدخل: https://github.com/focallocal/url-composer-templates
   • أضف المكون إلى السمة النشطة لديك.

2. لا حاجة لإعادة بناء المكون الإضافي (plugin rebuild)! دعم معلمة composer_template موجود بالفعل في dcs-discourse-plugin و dcs-client.

3. نشر تطبيق React الخاص بك (fl-maps) باستخدام مكونات DCSLink المحدثة التي تمرر الخاصية composerTemplate.

4. تكوين القوالب في إعدادات المكون (المسؤول ← تخصيص ← السمات ← سمتك ← url-composer-templates ← الإعدادات).

التكوين

إعدادات القالب

يحتوي كل قالب على ثلاثة خيارات تكوين:

القالب 1 (تقرير - Report)

• template_1_id: report - قيمة معلمة عنوان URL لتشغيل هذا القالب.
• template_1_text: النص الذي سيتم ملؤه مسبقًا في المُنشئ.
• template_1_use_for: first_post - يتم التطبيق فقط عند إنشاء مواضيع جديدة.

القالب 2 (حضور - Going)

• template_2_id: going - لتفاعلات من نوع “أنا قادم”.
• template_2_text: النص المملوء مسبقًا لتأكيدات الحضور.
• template_2_use_for: all_replies - يتم التطبيق على جميع الردود (وليس المنشورات الأولى).

القالب 3 (دعوة - Invite)

• template_3_id: invite - لتفاعلات الدعوة.
• template_3_text: النص المملوء مسبقًا للدعوات.
• template_3_use_for: all_replies - يتم التطبيق على جميع الردود.

القوالب 4-6 (مخصصة - Custom)

• معطلة افتراضيًا.
• يمكن تمكينها وتخصيصها لحالات استخدام محددة.
• قم بتكوين المعرف (ID) والنص ونطاق التطبيق حسب الحاجة.

إعدادات الفتح التلقائي

• enable_auto_open_composer: true - عند التمكين، يفتح المُنشئ تلقائيًا إذا:
  • تم النقر على رابط Docuss (يحتوي عنوان URL على ?composer_template=X).
  • لا توجد مواضيع موجودة بعد لمجموعة الوسوم الحالية.
  • يساعد المستخدمين على بدء المناقشات على الفور.

وضع التصحيح

• debug_mode: false - قم بالتمكين لرؤية سجلات وحدة التحكم التفصيلية مع بادئات الرموز التعبيرية (emoji):
  • سجلات تطبيق القالب.
  • سجلات فتح المُنشئ التلقائي.

تكامل Docuss

التكامل التلقائي

تم تصميم مكون url-composer-templates للعمل تلقائيًا مع Docuss. عندما يكون لديك كل من:

• هذا المكون مثبتًا على مثيل Discourse الخاص بك.
• عميل Docuss والمكون الإضافي المحدث (مع دعم composer_template).

سيتم تطبيق القوالب تلقائيًا بناءً على:

1. وضع التفاعل (Interact Mode):
   • وضع DISCUSS ← يستخدم تلميحات triggerId (حضور، دعوة) أو يعود إلى report.
   • وضع COMMENT ← يستخدم قالب report.

القوالب المخصصة عبر سمات HTML

لمزيد من التحكم الدقيق، يمكنك تحديد القوالب مباشرة في HTML الخاص بك باستخدام السمة data-dcs-composer-template:

<!-- مثال: زر التقرير -->
<div class="dcs-trigger" 
     data-dcs-trigger-id="issue-report"
     data-dcs-interact-mode="DISCUSS"
     data-dcs-composer-template="report">
  الإبلاغ عن مشكلة
</div>

<!-- مثال: زر الحضور -->
<div class="dcs-trigger" 
     data-dcs-trigger-id="event-rsvp"
     data-dcs-interact-mode="DISCUSS"
     data-dcs-composer-template="going">
  أنا قادم!
</div>

<!-- مثال: زر الدعوة -->
<div class="dcs-trigger" 
     data-dcs-trigger-id="invite-friends"
     data-dcs-interact-mode="DISCUSS"
     data-dcs-composer-template="invite">
  دعوة الأصدقاء
</div>

<!-- مثال: قالب مخصص -->
<div class="dcs-trigger" 
     data-dcs-trigger-id="feedback"
     data-dcs-interact-mode="DISCUSS"
     data-dcs-composer-template="custom1">
  قدم ملاحظاتك
</div>

مطابقة معرف القالب (Template ID Matching)

يطابق المكون معرفات القالب من معلمة عنوان URL مع معرفات القالب المكونة:

معلمة عنوان URL	إعداد القالب	الغرض الافتراضي
?composer_template=report	template_1_id	تقارير الأخطاء، المشكلات
?composer_template=going	template_2_id	تأكيدات الحضور في الفعاليات
?composer_template=invite	template_3_id	الدعوات
?composer_template=custom1	template_4_id	استخدام مخصص
?composer_template=custom2	template_5_id	استخدام مخصص
?composer_template=custom3	template_6_id	استخدام مخصص

كيف يعمل

تدفق تطبيق القالب

1. اكتشاف عنوان URL: عندما ينتقل المستخدم إلى عنوان URL يحتوي على ?composer_template=X، يقوم المكون بتخزين معرف القالب في sessionStorage.
2. اعتراض المُنشئ: عند فتح المُنشئ، يتحقق المكون من وجود معرف قالب مخزن.
3. مطابقة القالب: يجد القالب المطابق بناءً على المعرف.
4. التحقق من النطاق: يتحقق مما إذا كان يجب تطبيق القالب (المنشور الأول، الرد، أو كليهما).
5. إدراج النص: يملأ المُنشئ مسبقًا بنص القالب.
6. التنظيف: يضع علامة على القالب على أنه تم تطبيقه لمنع إعادة التطبيق.

تدفق الفتح التلقائي

1. اكتشاف المعلمة: يتحقق مما إذا كان عنوان URL يحتوي على ?composer_template=X وما إذا كان الفتح التلقائي ممكّنًا.
2. البحث عن الموضوع: يبحث عن مواضيع موجودة مع مجموعة الوسوم الحالية.
3. فتح المُنشئ: إذا لم يتم العثور على مواضيع، يقوم بفتح المُنشئ تلقائيًا.
4. تطبيق القالب: يتم تطبيق القالب بعد ذلك عبر التدفق العادي المذكور أعلاه.

حالات الاستخدام المثالية

موقع الفعالية

# settings.yml
template_2_id: "going"
template_2_text: "أنا أخطط للحضور! 🎉\n\nأتطلع لرؤية الجميع هناك."
template_2_use_for: "all_replies"

template_3_id: "invite"
template_3_text: "أود دعوة الأصدقاء لهذا الحدث.\n\nمن أدعو:\n- \n\nلماذا يجب أن يأتوا:\n"
template_3_use_for: "first_post"

تتبع المشكلات

template_1_id: "bug"
template_1_text: "**وصف الخطأ:**\n\n**خطوات إعادة الإنتاج:**\n1. \n2. \n3. \n\n**السلوك المتوقع:**\n\n**السلوك الفعلي:**\n"
template_1_use_for: "first_post"

template_4_enabled: true
template_4_id: "feature"
template_4_text: "**طلب ميزة:**\n\n**حالة الاستخدام:**\n\n**الحل المقترح:**\n"
template_4_use_for: "first_post"

مشاركة المجتمع

template_1_id: "question"
template_1_text: "**سؤالي:**\n\n**ما جربته:**\n\n**سياق إضافي:**\n"
template_1_use_for: "first_post"

template_2_id: "answer"
template_2_text: "إليك ما نجح معي:\n\n**الحل:**\n\n**لماذا ينجح:**\n"
template_2_use_for: "all_replies"

استكشاف الأخطاء وإصلاحها

القوالب لا يتم تطبيقها

1. تحقق من معلمة عنوان URL: تأكد من أن عنوان URL يحتوي على ?composer_template=X حيث تتطابق X مع معرف القالب.
2. تمكين وضع التصحيح: قم بتشغيل debug_mode في الإعدادات لرؤية سجلات وحدة التحكم.
3. التحقق من نطاق القالب: تحقق مما إذا كان إعداد use_for يطابق الإجراء الخاص بك (إنشاء موضوع مقابل الرد).
4. مسح SessionStorage: افتح وحدة تحكم المتصفح وقم بتشغيل: sessionStorage.clear()

الفتح التلقائي لا يعمل

1. التحقق من الإعداد: تأكد من تعيين enable_auto_open_composer على true.
2. التحقق من عنوان URL: يعمل الفتح التلقائي فقط عندما يحتوي عنوان URL على ?composer_template=X.
3. التحقق من المواضيع الحالية: يتم تشغيل الفتح التلقائي فقط عندما لا توجد مواضيع موجودة لمجموعة الوسوم.
4. تمكين وضع التصحيح: ابحث عن سجلات وحدة التحكم التي تحمل الرمز التعبيري .

تطبيق القالب الخاطئ

1. التحقق من معرفات القالب: تأكد من أن معلمة عنوان URL تطابق معرف القالب بالضبط (حساسة لحالة الأحرف).
2. التحقق من الأولوية: إذا كان من الممكن أن يتطابق أكثر من قالب، يتم استخدام أول قالب مطابق.
3. مسح الجلسة: قد تحتوي SessionStorage على قيم قديمة: sessionStorage.clear().

مشكلات تكامل Docuss

1. تحديث Docuss: تأكد من أن لديك أحدث إصدارات من:
   • dcs-client (مع دعم composerTemplate في HtmlBased.js).
   • dcs-discourse-plugin (مع إنشاء معلمات عنوان URL في DcsIFrame.js.es6).
2. التحقق من سمات HTML: تأكد من تعيين data-dcs-composer-template بشكل صحيح على المشغلات (triggers).
3. فحص الشبكة: تحقق من علامة تبويب الشبكة (Network) في أدوات المطور بالمتصفح لمعرفة ما إذا كانت معلمات عنوان URL تتم إضافتها.

سجل الإصدارات

الإصدار 1.0.0 (الحالي)

• الإصدار الأولي.
• دعم لـ 6 قوالب قابلة للتكوين.
• اختيار القالب بناءً على معلمة عنوان URL.
• فتح المُنشئ تلقائيًا لروابط Docuss.
• استمرارية SessionStorage.
• وضع التصحيح لاستكشاف الأخطاء وإصلاحها.

المساهمة

هل وجدت خطأً أو لديك طلب ميزة؟ يرجى فتح مشكلة على مستودع GitHub.

الترخيص

هذا المكون مفتوح المصدر ومتاح بموجب ترخيص MIT.

الاعتمادات

تم تطويره بواسطة Andy@Focallocal للاستخدام مع Docuss - نظام لتضمين مناقشات Discourse في أي موقع ويب.