إضافة إعدادات إلى سمة Discourse الخاصة بك

[Discourse]

يتمتع Discourse بقدرة على السماح للمواضيع (Themes) بأن يكون لها “إعدادات” يمكن لمطوري المواضيع إضافتها للسماح لمالكي المواقع بتخصيص المواضيع عبر واجهة المستخدم دون الحاجة إلى تغيير أي سطر من الكود والقلق بشأن فقدان تعديلاتهم مع التحديثات المستقبلية للموضوع.

يمكن للمواضيع أيضاً تعديل بعض إعدادات الموقع القابلة للتخصيص، لمزيد من المعلومات حول ذلك، راجع موضوع إعدادات الموقع القابلة للتخصيص.

إضافة إعدادات إلى موضوعك

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

الطريقة لإضافة الإعدادات هي إنشاء مستودع لموضوعك، وفي المجلد الجذر لمستودعك قم بإنشاء ملف جديد باسم settings.yaml (أو settings.yml). في هذا الملف ستستخدم لغة YAML لتحديد إعدادات موضوعك.

ملاحظة: قد تجد أنه من المفيد الاستفادة من Theme CLI، الذي يبسط عملية التطوير بشكل كبير.

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

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

simple_setting: true

كما يمكنك أن تلاحظ، هذا سينشئ إعداداً باسم simple_setting وسيكون true هو قيمته الافتراضية.

وبالمثل، يمكنك إضافة شيء مثل هذا:

site_name: My Forums
max_avatars: 7

وسيتوفر لديك إعدادان إضافيان، site_name الذي سيكون إعداداً نصياً (string) بـ “My Forums” كقيمة افتراضية، و max_avatars كإعداد عددي صحيح (integer) بقيمة افتراضية 7.

يمكنك الوصول إلى إعداداتك في كود JS الخاص بك هكذا: settings.your_setting_key.

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

الأنواع المدعومة

هناك 8 أنواع من الإعدادات:

1. integer
2. float
3. string
4. bool (للقيم المنطقية)
5. list
6. enum
7. objects (بديل لـ json_schema)
8. upload (للصور)

ويمكنك تحديد النوع بإضافة سمة type إلى إعدادك هكذا:

float_setting:
  type: float
  default: 3.14

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

float_setting:
  default: 3.14

مع ذلك، فإنك تحتاج إلى تعيين سمة النوع عند العمل مع إعدادات list و enum، وإلا لن يتعرف Discourse عليها بشكل صحيح.

إعداد القائمة (List Setting):

whitelisted_fruits:
  default: apples|oranges
  type: list

إعداد القائمة المحدودة (Enum Setting):

favorite_fruit:
  default: orange
  type: enum
  choices:
    - apple
    - banana

في حال لم يكن الفرق بين إعدادات القائمة (list) والقائمة المحدودة (enum) واضحاً لك: تسمح لك إعدادات enum لمستخدمي الموضوع باختيار قيمة واحدة فقط من مجموعة من القيم التي تحددها (انظر سمة choices).

من ناحية أخرى، تسمح إعدادات القائمة لمستخدميك بإنشاء قائمة (أي مصفوفة) من القيم الخاصة بهم. يمكنهم إضافة أو إزالة عناصر من القائمة الافتراضية للقيم في الإعداد.
يمكنك تعيين القائمة الافتراضية للقيم للإعداد عن طريق ربط القيم برمز الخط العمودي |. انظر إعداد القائمة في المثال أعلاه.

يمكنك رؤية حالة استخدام واقعية لإعدادات القائمة هنا: Auto-Linkify Words.

ملاحظة: انتبه إلى المسافات البادئة (Indentation) عند العمل مع YAML لأن YAML حساس جداً للمسافات وسيعرض خطأ في الصيغة إذا كانت مسافات بادئة الكود غير صحيحة.

نوع objects

نوع الإعداد objects هو نوع خاص يسمح لك بإنجاز إعدادات متقدمة بهيكل مخصص وتحقق (Validations). لدينا توثيق منفصل لهذا النوع.

وصف الإعداد والتعريب

يمكنك إضافة نص وصف إلى إعداد موضوعك وسيظهر كعلامة مباشرة أسفل الإعداد. للقيام بذلك، أضف ببساطة سمة description إلى إعدادك هكذا:

whitelisted_fruits:
  default: apples|oranges
  type: list
  description: "سيتم عرض هذا النص أسفل هذا الإعداد وهو يوضح ما يفعله الإعداد!"

وسيحصل على هذا:

دعم اللغات المتعددة

إذا كنت تعرف أكثر من لغة، وترغب في إضافة دعم لتلك اللغات إلى موضوعك، فيمكنك بالتأكيد القيام بذلك بشرط أن يدعم Discourse تلك اللغات.

أولاً، تأكد من أن اللغة التي تريد دعمها موجودة في هذه القائمة:

قائمة اللغات

الرمز				الاسم
ar				اللغة العربية
bs_BA				bosanski jezik
ca				català
cs				čeština
da				dansk
de				Deutsch
el				ελληνικά
en				English
es				Español
et				eesti
fa_IR				فارسی
fi				suomi
fr				Français
gl				galego
he				עברית
id				Indonesian
it				Italiano
ja				日本語
ko				한국어
lv				latviešu valoda
nb_NO				Norsk bokmål
nl				Nederlands
pl_PL				język polski
pt				Português
pt_BR				Português (BR)
ro				limba română
ru				Русский
sk				slovenčina
sq				Shqip
sr				српски језик
sv				svenska
te				తెలुగు
th				ไทย
tr_TR				Türkçe
uk				українська мова
ur				اردو
vi				Việt Nam
zh_CN				中文
zh_TW				中文 (TW)

(إذا لم تتمكن من رؤية لغتك في القائمة، فقد ترغب في الاطلاع على How to add a new language)

ثم ستحتاج إلى العثور على رمز لغتك من القائمة أعلاه واستخدام رمز اللغة كمفتاح تحت سمة description والترجمة كقيمة للمفتاح هكذا:

whitelisted_fruits:
  default: apples|oranges
  type: list
  description:
    en: English text
    ar: نص باللغة العربية
    fr: Texte français

والآن لديك دعم لـ 3 لغات: الإنجليزية والعربية والفرنسية.

سمات وخيارات إضافية للإعدادات

سمات الحد الأدنى والحد الأقصى (Min and max)

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

لتحديد الحدود، أضف ببساطة سمة min أو max أو كليهما إلى إعدادك هكذا:

integer_setting:
  default: 10
  min: 5
  max: 100

يمكنك تحديد الحدود لإعدادات نوع integer و float و string. لإعدادات integer و float، يتم التحقق من قيمة الإعداد نفسه ضد الحدود. ولإعدادات string، يتم التحقق من طول القيمة ضد الحدود المحددة.

إذا حاول المستخدم إدخال قيمة خارج النطاق المسموح به، سيرى خطأ يخبره بالقيم الدنيا والعظمى.

الوصول إلى الإعدادات في كود JS/CSS/Handlebars الخاص بك

تكون إعدادات الموضوع متاحة عالمياً كمتغير settings في ملفات JavaScript للموضوع. على سبيل المثال:

// {theme}/javascripts/discourse/api-initializers/init-theme.gjs
import { apiInitializer } from "discourse/lib/api";

export default apiInitializer((api) => {
  console.log("الإعدادات هي", settings);
});

يمكن أيضاً استخدام كائن settings هذا بشكل عادي داخل وسوم <template> في ملفات .gjs.

تعيين متغيرات CSS

في CSS، سيتم إنشاء متغير لكل إعداد من إعدادات موضوعك وسيكون لكل متغير نفس اسم الإعداد الذي يمثل.

لذا، إذا كان لديك إعداد float باسم global_font_size وإعداد string باسم site_background، يمكنك القيام بشيء مثل هذا في كود CSS الخاص بموضوعك:

html {
  font-size: #{$global-font-size}px;
  background: $site-background;
}

حل عضوية المجموعة

tحتاج مكونات المواضيع أحياناً إلى إظهار أو إخفاء ميزة بناءً على ما إذا كان المستخدم الحالي عضوًا في مجموعة مُعدّة. تجنب التحقق من currentUser.groups لهذا الغرض لأنها تتضمن فقط المجموعات الظاهرة للمستخدم وقد تفوت المجموعات المخفية.

للإعدادات القائمة على المجموعات، أضف resolve_group_membership: true لحل التحقق من جانب الخادم:

copy_button_allowed_groups:
  default: "1|3"
  type: list
  list_type: group
  resolve_group_membership: true

هذه الخيار صالح فقط عندما يكون للإعداد type: list و list_type: group. عند تفعيله، لا يتضمن كائن settings في الواجهة الأمامية قائمة المجموعات الأصلية. بدلاً من ذلك، يضيف Discourse قيمة منطقية (boolean) بنفس اسم الإعداد مع بادئة user_in_:

// {theme}/javascripts/discourse/api-initializers/init-theme.gjs
import { apiInitializer } from "discourse/lib/api";

export default apiInitializer((api) => {
  if (!settings.user_in_copy_button_allowed_groups) {
    return;
  }

  // المستخدم عضو في مجموعة واحدة على الأقل مختارة.
});

تعمل القيمة المنطقية المولدة أيضاً مع المجموعات التلقائية مثل logged_in_users و anonymous_users. يمكن لإعدادات موضوع الكائنات استخدام نفس الخيار على خصائص type: groups. راجع نوع الكائنات لإعدادات الموضوع للتفاصيل.

مواضيع ذات صلة

• Developing Discourse Themes & Theme Components

---

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