لقد عملنا مؤخرًا على تحديث رأس صفحة Discourse من نظام “الويدجات” (widgets) القديم إلى مكونات Glimmer الحديثة. هذا التغيير متاح الآن في نواة Discourse خلف إعداد الموقع glimmer header mode.
الجدول الزمني التقريبي
(تقديرات تقريبية جدًا - قابلة للتغيير في أي اتجاه)
الربع الأول من 2024:
-
اكتمال التنفيذ الأساسي وتمكينه على موقع Meta -
نشر نصائح الترقية؛ تفعيل رسائل الإيقاف عن الاستخدام في وحدة التحكم -
بدء العمل لتحديث جميع الإضافات والمظاهر الرسمية والطرف الثالث
الربع الثاني من 2024:
-
البدء في تمكين تنفيذ الرأس الجديد افتراضيًا -
جاهزية المظاهر والإضافات الرسمية والطرف الثالث للترقية -
بدء رسائل الإيقاف عن الاستخدام في تشغيل شريط تحذير للمسؤولين لأي مشكلات متبقية
الربع الثالث من 2024:
-
نشر موضوع إعلان لزيادة الوضوح: Preparing your community for behind-the-scenes header changes -
الأسبوع الذي يبدأ في 5 أغسطس 2024 (v3.4.0.beta1): تمكين الرأس الجديد لجميع المواقع افتراضيًا. سيظل بإمكان المسؤولين التبديل إلى الرأس القديم عن طريق تبديل إعداد الموقع glimmer header mode. -
الأسبوع الذي يبدأ في 2 سبتمبر 2024: الإزالة النهائية لعلم الميزة والكود القديم
ماذا يعني هذا بالنسبة لي؟
إذا كانت إضافتك أو مظهرك يستخدم أي واجهات برمجة تطبيقات (APIs) للويدجات (widgets) لتخصيص الرأس، فستحتاج هذه الواجهات إلى التحديث لتكون متوافقة مع الرأس الجديد.
كيف يمكنني تجربة الرأس الجديد؟
في أحدث إصدار من Discourse، يتم تمكين الرأس الجديد تلقائيًا عندما تكون جميع المظاهر والإضافات الخاصة بك متوافقة.
إذا لم تكن مظاهرك/إضافاتك متوافقة، فسيتم استخدام الرأس القديم، وسيتم طباعة تحذير في وحدة التحكم جنبًا إلى جنب مع رسائل الإيقاف عن الاستخدام الحالية. كما سيتم عرض شريط تحذير للمسؤولين في واجهة المستخدم.
في الحالة غير المرجحة التي لا يعمل فيها هذا النظام التلقائي كما هو متوقع، يمكنك تجاوز هذا “علم الميزة التلقائي” مؤقتًا عبر إعداد الموقع glimmer header mode. إذا قمت بذلك، يرجى إخبارنا بالسبب في هذا الموضوع.
هل أحتاج إلى تحديث إضافتي/مظهري؟
لتحديد ما إذا كان تخصيصك يحتاج إلى تحديث، تحقق مما إذا كان يستخدم decorateWidget، أو changeWidgetSetting، أو reopenWidget، أو attachWidgetAction على أي من هذه الويدجات:
- header
- site-header
- header-contents
- header-buttons
- user-status-bubble
- sidebar-toggle
- header-icons
- header-topic-info
- header-notifications
- home-logo
- user-dropdown
أو يستخدم أحد طرق واجهة برمجة التطبيقات (plugin API) التالية:
addToHeaderIconsaddHeaderPanel
ستؤدي جميع هذه الأمور الآن إلى طباعة رسائل الإيقاف عن الاستخدام في وحدة التحكم. معرّفات الإيقاف عن الاستخدام هي:
discourse.add-header-paneldiscourse.header-widget-overrides
إذا كنت تستخدم أكثر من مظهر في نسختك، فتأكد من فحص جميعها.
إشعار المسؤول
اعتبارًا من 20 يونيو 2024، قمنا بتمكين إشعار المسؤول للإيقافات المذكورة أعلاه.
إذا تم نشر نسختك بعد هذا التاريخ، وأثّرت الإضافات أو المظاهر أو مكونات المظاهر الحالية في نسختك على أحد تحذيرات الإيقاف عن الاستخدام، فسيتم عرض الرسالة التالية فقط للمسؤولين*:
هذه الرسالة هي مجرد تنبيه للمسؤولين بضرورة اتخاذ إجراء قريبًا لتحديث التخصيصات المتأثرة: فالتخصيصات القديمة ستظل تعمل حتى نقوم بإزالة قاعدة الكود القديمة.
ما هي البدائل؟
كل مظهر/إضافة يختلف عن الآخر، ولكن إليك بعض التوجيهات لأكثر حالات الاستخدام شيوعًا:
addToHeaderIcons
بالنسبة لأيقونات الرأس المخصصة، نوصي بإزالة الكود الخاص بك وتثبيت مكون مظهر Custom Header Links (Icons) الرسمي. إذا لم يلبي ذلك متطلباتك، راجع أدناه للحصول على تفاصيل حول تغييرات الكود المطلوبة:
تم إيقاف واجهة برمجة التطبيقات addToHeaderIcons لصالح واجهة headerIcons الجديدة. وهي موجودة للسماح بإضافة أو إزالة أو إعادة ترتيب الأيقونات في الرأس. تتطلب تمرير مكون (Component).
يمكن تمرير المكون على النحو التالي:
| قبل | بعد |
|---|---|
| api.addToHeaderIcons(“widget-foo”) | api.headerIcons.add(“foo”, FooIcon) |
| api.decorateWidget(“header-icons:before”, () => return helper.h(“div”, “widget-foo”)) | api.headerIcons.add(“foo”, FooIcon, { before: “search” }) |
| api.decorateWidget(“header-icons:after”, () => return helper.h(“div”, “widget-foo”)) | api.headerIcons.add(“foo”, FooComponent, { after: “search” }) |
يستخدم هذا المثال تنسيق قالب Ember (gjs) لتعريف مكون مضمن وتمريره إلى واجهة headerButtons.add:
// .../discourse/api-initializers/add-my-button.gjs
import DButton from "discourse/components/d-button";
import { apiInitializer } from "discourse/lib/api";
export default apiInitializer("1.0", (api) => {
api.headerIcons.add("some-unique-name", <template>
<li><DButton class="icon btn-flat" @href="/u" @icon="address-book" /></li>
</template>);
});
أو لقائمة منسدلة، يمكنك استخدام <DMenu بدلاً من <DButton:
import DButton from "discourse/components/d-button";
import { apiInitializer } from "discourse/lib/api";
import DMenu from "float-kit/components/d-menu";
export default apiInitializer("1.0", (api) => {
api.headerIcons.add("some-unique-name", <template>
<li>
<DMenu class="icon btn-flat" @icon="address-book">
<DButton @translatedLabel="User 1" @href="/u/user1" />
<DButton @translatedLabel="User 2" @href="/u/user2" />
<DButton @translatedLabel="User 3" @href="/u/user3" />
</DMenu>
</li>
</template>);
});
تسويات ترقية أمثلة:
decorateWidget("header-buttons:*")
بالنسبة لروابط الرأس المخصصة، نوصي بإزالة الكود الخاص بك وتثبيت مكون مظهر Custom Header Links الرسمي. إذا لم يلبي ذلك متطلباتك، راجع أدناه للحصول على تفاصيل حول تغييرات الكود المطلوبة:
تم إيقاف ويدجة header-buttons وقمنا بإدخال واجهة برمجة تطبيقات headerButtons. وهي موجودة للسماح بإضافة أو إزالة أو إعادة ترتيب الأزرار في الرأس. تتطلب تمرير مكون (Component).
| قبل | بعد |
|---|---|
| api.decorateWidget(“header-buttons:before”) | api.headerButtons(“button-name”, ButtonComponent, { before: “auth” }) |
| api.decorateWidget(“header-buttons:after”) | api.headerButtons(“button-name”, ButtonComponent, { after: “auth” }) |
changeWidgetSetting(...) لويدجات الرأس
يمكن تحقيق الاستخدامات الأكثر شيوعًا لـ
changeWidgetSettingباستخدام مكونات المظاهر التالية:إذا لم تناسب هذه الحالات استخدامك، فاستمر في القراءة…
استخدمت بعض التخصيصات على ويدجات الرأس واجهة برمجة التطبيقات changeWidgetSetting.
على الرغم من عدم وجود بديل مباشر للتخصيصات مثل المذكورة أعلاه، نظرًا لكيفية عمل حقول مكونات Glimmer، فقد قمنا بإدخال واجهة برمجة تطبيقات جديدة في Discourse 3.3.0.beta3 للتعامل مع بعض هذه الحالات.
يمكن استخدام registerValueTransformer لتجاوز القيم التي تم وضع علامة عليها في الكود المصدري على أنها قابلة للتجاوز، وهي نهج مشابه لكيفية عمل منافذ الإضافات (plugin outlets).
لقد أضفنا بالفعل محولين (transformers) للحالات التي وجدناها شائعة في قاعدة الكود المصدري لدينا:
-
home-logo-href: يمكن استخدامه لتجاوز URL في رابط شعار الصفحة الرئيسية. راجع القسمhome-logoأدناه للحصول على أمثلة. -
header-notifications-avatar-size: يمكن استخدامه لتغيير حجم الصورة المسترجعة لصورة المستخدم في الرأس. مثال:
الكود أدناه:
api.changeWidgetSetting(
"header-notifications",
"avatarSize",
settings.header_avatars_size
);
سيتم تحويله إلى:
api.registerValueTransformer(
"header-notifications-avatar-size",
() => settings.header_avatars_size
);
يجب إضافة هذه المحولات إلى الكود المصدري لـ Discourse. إذا كنت بحاجة إلى محول مختلف، يرجى إخبارنا بنشر حالتك الاستخدامية أدناه.
يمكن العثور على مزيد من التفاصيل حول واجهات برمجة تطبيقات محول القيم الجديدة هنا.
home-logo
لقد قمنا بإدخال منفذ إضافة (plugin outlet) لـ home-logo هنا كبديل لزينات الويدجات home-logo:before أو home-logo:after. يمكنك استخدام التسمية التلقائية __before و __after في ملف الاتصال (connector file) لتحديد مكان وضع المحتوى المخصص الخاص بك.
يمكن العثور على مزيد من التفاصيل حول تسمية ملف الاتصال قبل/بعد هنا.
| قبل | بعد |
|---|---|
| api.decorateWidget(“home-logo:before”) | نقل المحتوى إلى /connectors/home-logo__before |
| api.decorateWidget(“header-buttons:after”) | نقل المحتوى إلى /connectors/home-logo__after) |
تغيير رابط URL لشعار الصفحة الرئيسية:
حاجة شائعة جدًا هي تغيير الرابط الذي يشير إليه home-logo. لقد قمنا بإدخال محول القيمة home-logo-href لمعالجة ذلك. أمثلة:
-
لتغيير الرابط إلى عنوان URL ثابت
api.registerValueTransformer("home-logo-href", () => "https://example.com"); -
لإرجاع عنوان URL ديناميكي بناءً على المستخدم الحالي
api.registerValueTransformer("home-logo-href", () => { const currentUser = api.getCurrentUser(); return `https://example.com/${currentUser.username}`; }); -
لإرجاع عنوان URL بناءً على إعداد مكون المظهر
api.registerValueTransformer("home-logo-href", () => { return settings.example_logo_url_setting; });
ماذا عن التخصيصات الأخرى؟
إذا لم يمكن تحقيق تخصيصك باستخدام CSS، أو منافذ الإضافات (PluginOutlets)، أو واجهات برمجة التطبيقات الجديدة التي قدمناها، فيرجى إخبارنا بإنشاء موضوع Development جديد لمناقشته.
كيف يمكنني تحديث مظهر/إضافة لدعم الرأسين القديم والجديد؟
جميع واجهات برمجة التطبيقات ومنافذ الإضافات الجديدة المذكورة في هذا المستند مدعومة في كل من الرأس الجديد والقديم. لذا فأنت بحاجة فقط إلى إجراء تحديث واحد لمظهرك/إضافتك الآن، وسيكون المستخدمون جاهزين للتبديل.




