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

[Discourse]

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

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

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

تختلف إضافة الإعدادات إلى سماتك قليلاً عن إضافة أكواد 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 الذي سيكون إعدادًا نصيًا بـ “My Forums” كقيمة افتراضية، و max_avatars كإعداد عددي صحيح بقيمة افتراضية 7.

يمكنك الوصول إلى إعداداتك في كود JavaScript الخاص بك كالتالي: 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 عليها بشكل صحيح.

إعداد القائمة:

whitelisted_fruits:
  default: apples|oranges
  type: list

إعداد enum:

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

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

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

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

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

نوع 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: English text
    ar: نص باللغة العربية
    fr: Texte français

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

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

سمات الحد الأدنى والحد الأقصى

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

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

integer_setting:
  default: 10
  min: 5
  max: 100

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

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

الوصول إلى الإعدادات في JavaScript/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;
}

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

تحتاج مكونات السمة أحيانًا إلى إظهار أو إخفاء ميزة بناءً على ما إذا كان المستخدم الحالي عضوًا في مجموعة محددة. تجنب التحقق من 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 قيمة منطقية بنفس اسم الإعداد مع بادئة 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.

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

• 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 هذا يعمل بشكل مثالي! شكرا لك!