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

[Discourse]

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

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

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

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

طريقة إضافة الإعدادات هي إنشاء مستودع لسماتك، وفي المجلد الجذر لمستودعك قم بإنشاء ملف جديد باسم 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 أنواع من الإعدادات:

1. integer
2. float
3. string
4. bool (للقيم المنطقية Boolean)
5. list
6. enum
7. objects (بديل لـ json_schema)
8. upload (للصور)
9. 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 (Enum Setting):

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

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

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

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

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

إعداد الأيقونة (Icon Setting):

banner_icon:
  default: bullhorn
  type: icon

توفر إعدادات الأيقونة لمالكي المواقع منتقي أيقونات قابل للبحث، والقيمة هي اسم الأيقونة. تقوم Discourse بإضافة الأيقونة المحددة إلى ورقة الرموز (Sprite Sheet)، لذا يمكنك عرضها في سماتك دون الحاجة إلى تسجيلها بشكل منفصل.

نوع objects

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

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

يمكنك إضافة نص وصفي إلى إعداد السمة الخاص بك وسيظهر كعلبة مباشرة أسفل الإعداد. للقيام بذلك، أضف ببساطة خاصية 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: نص إنجليزي
    ar: نص باللغة العربية
    fr: نص فرنسي

والآن لديك دعم لـ 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;
}

حل عضوية المجموعة (Resolving group membership)

تحتاج مكونات السمات أحياناً إلى إظهار أو إخفاء ميزة بناءً على ما إذا كان المستخدم الحالي ينتمي إلى مجموعة محددة. تجنب فحص 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. يمكن لإعدادات السمة من نوع الكائنات (Object theme settings) استخدام نفس الخيار على الخصائص من نوع type: groups. راجع نوع الكائنات لإعدادات السمة للتفاصيل.

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

• Developing Discourse Themes & Theme Components

---

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

[mcwumbly (Dave McClure)]

@أسامة، مشاركة:1، موضوع:82557

نوع json_schema

نوع إعداد JSON Schema هو نوع إعداد جديد وفريد يسمح لك بإنجاز الكثير من الإعدادات المعقدة

أتساءل عما إذا كان ينبغي علينا استبدال هذا القسم بشيء حول: Objects type for theme setting

ربما نريد أيضًا مرجعًا من هذا المستند إلى: Migrate Discourse theme settings

[pfaffman (Jay Pfaffman)]

@Discourse

نوع json_schema

نوع JSON Schema هو نوع إعداد جديد وفريد يسمح لك بإنجاز الكثير من الإعدادات المعقدة.

@mcwumbly

أتساءل عما إذا كان يجب علينا استبدال هذا القسم بشيء حول: نوع الكائنات لإعداد السمة

نعم. لقد أضعت ما يقرب من ساعة في محاولة جعل json_schemas يعمل. (على الرغم من أنني كنت على علم بالطريقة الجديدة والمحسنة للقيام بذلك!!)

@Osama، إذا لم تتمكن من تحديث هذا بنفسك، فيرجى طلب شخص يمكنه ذلك. شكرًا.

[Osama]

آسف لحدوث ذلك، إليك طلب سحب لتحديث الوثيقة Replace references to `json_schema` with `objects` type documentation by OsamaSayegh · Pull Request #26 · discourse/discourse-developer-docs · GitHub

[gormus (Osman Görmüş)]

كيف يمكنني استخدام صورة معرفة كأصل (asset) لاستخدامها كقيمة افتراضية لحقل تحميل في إعدادات السمة؟

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

هل هناك طريقة للحصول على عنوان URL للأصل ديناميكيًا لاستخدامه كقيمة افتراضية؟

// about.json
{
  "assets": {
    "box_default_image": "assets/box-default-image.png"
  }
}

# settings.yml

box_image:
  type: upload
  default: settings.theme_uploads.box_default_image

[Moin]

هل جربت المفتاح من about.json؟ شيء مثل

# settings.yml

box_image:
  type: upload
  default: "box_default_image"

[gormus (Osman Görmüş)]

@moin هذا يعمل بشكل مثالي! شكرا لك!