يتمتع Discourse بخاصية تتيح للمواضيع (Themes) أن تحتوي على “إعدادات” يمكن لمطوري المواضيع إضافتها، مما يسمح لمالكي المواقع بتخصيص المواضيع من خلال واجهة المستخدم دون الحاجة إلى تغيير أي سطر من الكود أو القلق بشأن فقدان التغييرات مع التحديثات المستقبلية للموضوع.
كما يمكن للمواضيع تعديل بعض إعدادات الموقع القابلة للتخصيص، ولمزيد من المعلومات حول ذلك، راجع موضوع إعدادات الموقع القابلة للتخصيص.
إضافة الإعدادات إلى موضوعك
إضافة الإعدادات إلى موضوعك تختلف قليلاً عن إضافة كود CSS وJS، حيث لا يوجد طريقة للقيام بذلك عبر واجهة المستخدم.
طريقة إضافة الإعدادات هي إنشاء مستودع (repository) لموضوعك، وفي المجلد الجذري (root folder) لمستودعك أنشئ ملفاً جديداً باسم settings.yaml (أو settings.yml). في هذا الملف، ستستخدم لغة YAML لتعريف إعدادات موضوعك.
ملاحظة: قد تجد أنه من المفيد الاستفادة من Theme CLI، حيث يبسط عملية التطوير بشكل كبير.
الآن، إذا كنت على دراية بتطوير الإضافات (plugins)، فربما لا يكون هذا شيئاً جديداً عليك - فهو يعمل بنفس الطريقة تقريباً كما هو الحال عند إضافة إعدادات الموقع إلى إضافتك. ما عليك سوى وضع بعض 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.
لذلك، حتى هذه النقطة، غطينا أبسط طريقة لتعريف الإعدادات. في القسم التالي، سنتعمق قليلاً في الأنواع المختلفة للإعدادات وكيفية استخدامها.
الأنواع المدعومة
هناك 9 أنواع من الإعدادات:
integerfloatstringbool(للقيم المنطقية)listenumobjects(بديل عنjson_schema)upload(للصور)icon(لأيقونة واحدة من مجموعة أيقونات Discourse)
ويمكنك تحديد النوع بإضافة خاصية type إلى إعدادك على النحو التالي:
float_setting:
type: float
default: 3.14
يجب أن أقول إنك لا تحتاج دائماً إلى تعيين خاصية type بشكل صريح، لأن Discourse ذكي بما يكفي لاستنتاج نوع الإعداد من القيمة الافتراضية للإعداد. لذا يمكنك اختصار المثال أعلاه إلى هذا:
float_setting:
default: 3.14
ومع ذلك، فإنك تحتاج إلى تعيين خاصية النوع عند العمل مع إعدادات list، enum و icon، وإلا لن يتعرف عليها Discourse بشكل صحيح.
إعداد القائمة (List Setting):
whitelisted_fruits:
default: apples|oranges
type: list
إعداد التعداد (Enum Setting):
favorite_fruit:
default: orange
type: enum
choices:
- apple
- banana
في حال لم تكن الفروق بين إعدادات القوائم (list) والتعداد (enum) واضحة لك: إعدادات التعداد تسمح لمستخدمي موضوعك باختيار قيمة واحدة فقط من مجموعة قيم محددة من قِبلك (انظر خاصية choices).
من ناحية أخرى، تسمح إعدادات القوائم لمستخدميك بإنشاء قائمة (أي مصفوفة) من القيم الخاصة بهم. يمكنهم الإضافة إلى القائمة الافتراضية للقيم أو الحذف منها.
يمكنك تعيين القائمة الافتراضية للقيم للإعداد عن طريق ربط القيم بعلامة خط عمودي |. راجع إعداد القائمة في المثال أعلاه.
يمكنك رؤية حالة استخدام واقعية لإعدادات القوائم هنا: Auto-Linkify Words.
إعداد الأيقونة (Icon Setting):
banner_icon:
default: bullhorn
type: icon
تتيح إعدادات الأيقونة لمالكي الموقع منتقي أيقونات قابل للبحث، والقيمة هي اسم الأيقونة. يضيف Discourse الأيقونة المختارة إلى ورقة الرموز (sprite sheet)، لذا يمكنك عرضها في موضوعك دون تسجيلها بشكل منفصل.
نوع objects
نوع إعداد objects هو نوع خاص يتيح لك تحقيق إعدادات متقدمة بهيكل مخصص وتحقق (validations). لدينا توثيق منفصل لهذا النوع.
وصف الإعدادات والتوطين (Localizations)
يمكنك إضافة نص وصف إلى إعداد موضوعك وسيظهر كتسمية مباشرة تحت الإعداد. للقيام بذلك، ما عليك سوى إضافة خاصية description إلى إعدادك على النحو التالي:
whitelisted_fruits:
default: apples|oranges
type: list
description: "سيتم عرض هذا النص تحت هذا الإعداد وهو يشرح ما يفعله الإعداد!"
وسيحصل على هذا:
دعم اللغات المتعددة
إذا كنت تعرف أكثر من لغة واحدة، وترغب في إضافة دعم لهذه اللغات إلى موضوعك، فيمكنك بالتأكيد القيام بذلك بشرط أن يدعم Discourse هذه اللغات.
أولاً، تأكد من أن اللغة التي تريد دعمها موجودة في هذه القائمة:
قائمة اللغات
| الرمز | الاسم | |||
|---|---|---|---|---|
| ar | العربية | |||
| bs_BA | البوسنية | |||
| ca | الكاتالونية | |||
| cs | التشيكية | |||
| da | الدنماركية | |||
| de | الألمانية | |||
| el | اليونانية | |||
| en | الإنجليزية | |||
| es | الإسبانية | |||
| et | الإستونية | |||
| fa_IR | الفارسية | |||
| fi | الفنلندية | |||
| fr | الفرنسية | |||
| gl | الغاليسية | |||
| he | العبرية | |||
| id | الإندونيسية | |||
| it | الإيطالية | |||
| ja | اليابانية | |||
| ko | الكورية | |||
| lv | اللاتفية | |||
| nb_NO | النرويجية (بوكمول) | |||
| nl | الهولندية | |||
| pl_PL | البولندية | |||
| pt | البرتغالية | |||
| pt_BR | البرتغالية (البرازيل) | |||
| ro | الرومانية | |||
| ru | الروسية | |||
| sk | السلوفاكية | |||
| sq | الألبانية | |||
| sr | الصربية | |||
| sv | السويدية | |||
| te | التيلوغوية | |||
| th | التايلاندية | |||
| tr_TR | التركية | |||
| uk | الأوكرانية | |||
| ur | الأردية | |||
| vi | الفيتنامية | |||
| zh_CN | الصينية | |||
| zh_TW | الصينية (تايوان) |
(إذا لم تتمكن من رؤية لغتك في القائمة، فقد ترغب في الاطلاع على How to add a new language)
ثم ستحتاج إلى العثور على رمز لغتك من القائمة أعلاه واستخدام رمز اللغة كمفتاح تحت خاصية description والترجمة كقيمة للمفتاح على النحو التالي:
whitelisted_fruits:
default: apples|oranges
type: list
description:
en: نص إنجليزي
ar: نص باللغة العربية
fr: نص فرنسي
والآن لديك دعم لثلاث لغات: الإنجليزية والعربية والفرنسية.
خصائص وخيارات إضافية للإعدادات
خصائص الحد الأدنى والحد الأقصى (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 are", settings);
});
يمكن استخدام كائن settings هذا أيضاً بشكل عادي داخل وسوم <template> في ملفات .gjs.
تعيين متغيرات CSS
في CSS، سيتم إنشاء متغير لكل إعداد في موضوعك، وسيحمل كل متغير نفس اسم الإعداد الذي يمثله.
لذا، إذا كان لديك إعداد عائم (float) يسمى global_font_size وإعداد نصي (string) يسمى site_background، يمكنك القيام بشيء مثل هذا في CSS الخاص بموضوعك:
html {
font-size: #{$global-font-size}px;
background: $site-background;
}
حل عضوية المجموعة (Resolving group membership)
تحتاج مكونات الموضوع أحياناً إلى إظهار ميزة أو إخفائها بناءً على ما إذا كان المستخدم الحالي ضمن مجموعة محددة. تجنب فحص currentUser.groups لهذا الغرض لأنه يتضمن فقط المجموعات المرئية للمستخدم، وقد يفوت المجموعات المخفية.
لإعدادات القائمة المدعومة بالمجموعات (group-backed list settings)، أضف 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. يمكن لإعدادات الموضوع من نوع الكائنات (Object theme settings) استخدام نفس الخيار على خصائص type: groups. راجع نوع الكائنات لإعدادات الموضوع للتفاصيل.
مواضيع ذات صلة
هذا المستند خاضع للتحكم في الإصدارات - اقترح تغييرات على github.