copenhagen_theme

موضوع كوبنهاجن بواسطة Zendesk

سمة كوبنهاجن هي سمة دليل Zendesk الافتراضية. وهي مصممة لتكون سريعة الاستجابة ويمكن الوصول إليها. تعرف على المزيد حول تخصيص دليل Zendesk هنا.

يتكون موضوع كوبنهاجن لمركز المساعدة من:

• ملف البيان
• مجموعة من القوالب
• ملفات الأنماط وملفات جافا سكريبت
• مجلد الأصول.

كيفية الاستخدام

هذا هو الإصدار الأحدث من موضوع كوبنهاجن المتاح للدليل. من الممكن استخدام هذا المستودع كنقطة بداية لإنشاء المظهر المخصص الخاص بك. يمكنك تفرع هذا المستودع كما تراه مناسبًا. يمكنك استخدام IDE المفضل لديك لتطوير السمات ومعاينة تغييراتك محليًا في متصفح الويب باستخدام ZCLI. للحصول على التفاصيل، اقرأ وثائق موضوعات zcli.

تخصيص الموضوع الخاص بك

بمجرد إنشاء هذا المستودع، يمكنك أن لا تتردد في تحرير القوالب وCSS وJavaScript وإدارة الأصول.

ملف البيان

يسمح لك البيان بتحديد مجموعة من الإعدادات لموضوعك والتي يمكن بعد ذلك تغييرها عبر واجهة المستخدم في Theming Center. يمكنك قراءة المزيد عن ملف البيان هنا.

مجلد الإعدادات

إذا كان لديك متغير من النوع file ، فستحتاج إلى توفير ملف افتراضي لهذا المتغير في المجلد /settings . سيتم استخدام هذا الملف في لوحة الإعدادات بشكل افتراضي ويمكن للمستخدمين تحميل ملف مختلف إذا أرادوا ذلك. السابق. إذا كنت ترغب في الحصول على متغير لصورة الخلفية لقسم ما، فإن المتغير الموجود في ملف البيان الخاص بك سيبدو كما يلي:

 {
  ...
  "settings" : [ {
    "label" : "Images" ,
    "variables" : [ {
      "identifier" : "background_image" ,
      "type" : "file" ,
      "description" : "Background image for X section" ,
      "label" : "Background image" ,
    } ]
  } ]
}

وهذا سيبحث عن ملف داخل مجلد الإعدادات اسمه: background_image

إضافة الأصول

يمكنك إضافة أصول إلى مجلد الأصول واستخدامها في CSS وJavaScript والقوالب. يمكنك قراءة المزيد عن الأصول هنا

نشر الموضوع الخاص بك

بعد تخصيص السمة الخاصة بك، يمكنك تنزيل المستودع كملف zip واستيراده إلى Theming Center.

يمكنك متابعة وثائق الاستيراد هنا.

يمكنك أيضًا الاستيراد مباشرة من GitHub - تعرف على المزيد هنا.

قوالب

يتضمن الموضوع جميع القوالب المستخدمة لمركز المساعدة الذي يحتوي على جميع الميزات المتاحة. قائمة القوالب في الموضوع:

• صفحة المقالة
• صفحة الفئة
• صفحة قائمة منشورات المجتمع
• صفحة مشاركة المجتمع
• صفحة قائمة موضوعات المجتمع
• صفحة موضوع المجتمع
• صفحة المساهمات
• رأس الوثيقة
• صفحة الخطأ
• تذييل
• رأس
• الصفحة الرئيسية
• صفحة مشاركة مجتمعية جديدة
• صفحة طلب جديدة
• صفحة الطلبات
• صفحة نتائج البحث
• صفحة القسم
• صفحة الاشتراكات
• صفحة الملف الشخصي للمستخدم

يمكنك إضافة ما يصل إلى 10 قوالب اختيارية لما يلي:

• صفحة المقالة
• صفحة الفئة
• صفحة القسم

يمكنك القيام بذلك عن طريق إنشاء ملفات ضمن المجلدات templates/article_pages أو templates/category_pages أو templates/section_pages . تعلم المزيد هنا.

ورقة الأنماط وجافا سكريبت

نستخدم مجموعة التحديثات لتجميع ملفات JS وCSS المستخدمة في السمة - style.css و script.js . لا تقم بتحريرها مباشرة حيث سيتم إعادة إنشائها أثناء الإصدار.

للبدء:

$ yarn install
$ yarn start

سيؤدي هذا إلى تجميع كافة التعليمات البرمجية المصدر في src styles ومراقبة التغييرات. وسيبدأ أيضًا في preview .

ملحوظات:

• نحن لا نستخدم babel عمدًا عند تجميع script.js حتى نتمكن من الحصول على مخرجات حزمة نظيفة. تأكد من استخدام ميزات ecmascript المدعومة على نطاق واسع فقط (ES2015).
• لا تقم بتحرير style.css و script.js والملفات الموجودة داخل مجلد assets مباشرة. يتم تجديدها أثناء الإصدار.
• تتطلب المعاينة تسجيل الدخول، لذا تأكد من تشغيل yarn zcli login -i أولاً إذا لم تكن قد فعلت ذلك من قبل.

أصول

يأتي قالب كوبنهاجن مع عدد قليل من أصول JavaScript، ولكن يمكنك إضافة أصول أخرى إلى القالب الخاص بك عن طريق وضعها في مجلد assets .

مكونات التفاعل

بدءًا من الإصدار 4.0.0، يستخدم قالب Copenhagen بعض مكونات React لعرض أجزاء من واجهة المستخدم. توجد هذه المكونات في المجلد src/modules وتم إنشاؤها باستخدام مكتبة مكونات Zendesk Garden.

يتم تجميع هذه المكونات كوحدات JavaScript أصلية كجزء من عملية إنشاء مجموعة التحديثات، ويتم إصدارها كملفات JS في مجلد assets . نظرًا لإعادة تسمية الأصول عند تثبيت السمة، يجب استيراد الوحدات باستخدام مساعد الأصول.

لتسهيل عملية استيراد الوحدات، أضفنا مكونًا إضافيًا تراكميًا يقوم بإنشاء خريطة استيراد تقوم بتعيين اسم الوحدة إلى عنوان URL للأصل. يتم بعد ذلك إدخال خريطة الاستيراد هذه في قالب document_head.hbs أثناء الإنشاء.

على سبيل المثال، إذا قمت بتعريف وحدة باسم my-module في المجلد src/modules/my-module ، فيمكنك إضافتها إلى الملف rollup.config.mjs مثل هذا:

 export default defineConfig ( [
  // ...
  // Configuration for bundling modules in the src/modules directory
  {
    // ...
    input : {
      "my-module" : "src/modules/my-module/index.js" ,
    } ,
    // ...
  }
] ) ;

سيقوم التراكمي بإنشاء ملف باسم my-module-bundle.js في مجلد assets وستتم إضافة خريطة الاستيراد هذه إلى قالب document_head.hbs :

 < script type =" importmap " >
{
  "imports" : {
    "my-module" : "{{asset 'my-module-bundle.js'}}" ,
  }
}
</ script >

يمكنك بعد ذلك استيراد الوحدة في القوالب الخاصة بك مثل هذا:

 < script type = " module " >
  import { something } from " my-module " ;

  // ...
</ script > 

تدويل

يتم تنفيذ I18n في مكونات React باستخدام مكتبة React-i18next. نحن نستخدم ملف JSON مسطح ونستخدم . كفاصل لصيغ الجمع، وهو يختلف عن الافتراضي _ ويتم تكوينه أثناء التهيئة.

أضفنا أيضًا بعض الأدوات لنتمكن من دمج المكتبة مع نظام الترجمة الداخلي المستخدم في Zendesk. إذا كنت تقوم بإنشاء سمة مخصصة وترغب في تقديم ترجماتك الخاصة، فيمكنك الرجوع إلى وثائق المكتبة لإعداد تحميل ترجماتك.

التكامل مع نظام الترجمة Zendesk

إضافة سلاسل الترجمات

تتم إضافة سلاسل الترجمة مباشرة في الكود المصدري، عادةً باستخدام خطاف useTranslation ، وتمرير المفتاح والقيمة الإنجليزية الافتراضية:

 import { useTranslation } from 'react-i18next' ;

function MyComponent ( ) {
  const { t } = useTranslation ( ) ;

  return < div > { t ( "my-key" , "My default value" ) } < / div>
}

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

صيغ الجمع

عند استخدام صيغة الجمع، نحتاج إلى توفير القيم الافتراضية zero one والقيم other ، حسب طلب نظام الترجمة الخاص بنا. يمكن القيام بذلك عن طريق تمرير القيم الافتراضية في خيارات الدالة t .

 t ( "my-key" , {
  "defaultValue.zero" : "{{count}} items" ,
  "defaultValue.one" : "{{count}} item" ,
  "defaultValue.other" : "{{count}} items" ,
  count : ...
} ) 

استخراج السلسلة

يمكن استخدام البرنامج النصي bin/extract-strings.mjs لاستخراج سلاسل الترجمة من الكود المصدري ووضعها في ملف YAML الذي يلتقطه نظام الترجمة الداخلي لدينا. تم توثيق استخدام البرنامج النصي في البرنامج النصي نفسه.

يغلف البرنامج النصي أداة i18next-parser ويحول مخرجاتها إلى تنسيق YAML المستخدم داخليًا. من الممكن استخدام أسلوب مماثل في قالب مخصص، إما باستخدام مخرجات i18next-parser القياسية كمصدر للترجمات أو تنفيذ محول مخصص.

تحديث ملفات الترجمة

استخدم bin/update-modules-translations.mjs لتنزيل أحدث الترجمات لجميع الوحدات. يتم بعد ذلك تجميع كافة الملفات من خلال عملية الإنشاء في ملف [MODULE]-translations-bundle.js واحد.

في المرة الأولى التي تتم فيها إضافة الترجمات إلى الوحدة النمطية، تحتاج إلى إضافة تعيين بين مجلد الوحدة النمطية واسم الحزمة في أنظمة الترجمات إلى متغير MODULE في البرنامج النصي. على سبيل المثال، إذا كانت الوحدة موجودة في src/modules/my-module واسم الحزمة هو cph-theme-my-module ، فستحتاج إلى إضافة:

 const MODULES = {
  ... ,
  "my-module" : "cph-theme-my-module"
}

اختبار إمكانية الوصول

نحن نستخدم برنامجًا نصيًا مخصصًا للعقدة يقوم بتشغيل Lighthouse لاختبار إمكانية الوصول الآلي.

هناك طريقتان لتشغيل البرنامج النصي:

• وضع التطوير - يقوم بإجراء عمليات تدقيق إمكانية الوصول في معاينة السمة المحلية، على حساب محدد. يتطلب تشغيل zcli themes:preview ؛
• وضع CI - يقوم بإجراء عمليات تدقيق إمكانية الوصول على الموضوع المباشر لحساب معين.

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

وضع التطوير

لتشغيل عمليات تدقيق إمكانية الوصول أثناء تغيير السمة:

1. ابدأ في تجميع التغييرات ومعاينتها كما تفعل عادةً:

$ yarn install
$ yarn start

2. قم بإنشاء ملف .a11yrc.json في المجلد الجذر (انظر المثال)؛

   1. حدد الحساب/النطاق الفرعي لمعاينة السمة والتأكد من مطابقتها لملف تعريف zcli النشط
   2. املأ username وكلمة password ببيانات اعتماد المستخدم المسؤول؛
   3. حدد عناوين urls المطلوب اختبارها (إذا تركت فارغة، فسيقوم البرنامج النصي باختبار جميع عناوين URL)؛

3. في وحدة تحكم منفصلة، ​​قم بتشغيل عمليات تدقيق إمكانية الوصول في وضع التطوير:

 yarn test-a11y -d

سيتم بعد ذلك تشغيل عمليات تدقيق A11y على المعاينة التي بدأت في الخطوة 1 .

وضع سي

لإجراء عمليات تدقيق إمكانية الوصول على الموضوع المباشر لحساب معين، يجب على المرء:

1. تثبيت وحدات العقدة:

 yarn install

2. قم بتعيين end_user_email و end_user_password subdomain وعناوين urls كمتغيرات بيئة وقم بتشغيل عمليات تدقيق إمكانية الوصول في وضع CI، على سبيل المثال:

 end_user_email=<EMAIL> 
end_user_password=<PASSWORD> 
subdomain=<SUBDOMAIN> 
urls="
    https://<SUBDOMAIN>.zendesk.com/hc/en-us/
    https://<SUBDOMAIN>.zendesk.com/hc/en-us/requests/new
    https://<SUBDOMAIN>.zendesk.com/hc/en-us/requests" 
yarn test-a11y 

تجاهل القائمة

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

يجب أن يتضمن الإدخال ما يلي:

• معرف التدقيق؛
• path كسلسلة نمط عنوان url؛
• selector كسلسلة.

على سبيل المثال:

  custom: {
    ignore: {
      tabindex: [
        {
          path : "*" ,
          selector : "body > a.skip-navigation" ,
        } ,
      ] ,
      aria - allowed - attr : [
        {
          path : "/hc/:locale/profiles/:id" ,
          selector : "body > div.profile-info"
        }
      ]
    } ,
  } ,

في هذا المثال، سيتم الإبلاغ عن أخطاء فهرس tabindex للتدقيق مع body > a.skip-navigation كتحذيرات في جميع الصفحات ( * ). سيحدث نفس الشيء بالنسبة لتدقيق aria-allowed-attr مع body > div.profile-info ، ولكن فقط لصفحة ملف تعريف المستخدم /hc/:locale/profiles/:id .

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

المساهمة

نرحب بطلبات السحب على GitHub على https://github.com/zendesk/copenhagen_theme. يرجى ذكر @zendesk/vikings عند إنشاء طلب سحب.

نحن نستخدم الالتزامات التقليدية لتحسين إمكانية قراءة سجل المشروع ولأتمتة عملية الإصدار. لذلك يجب أن تحترم رسالة الالتزام التنسيق التالي:

 <type>[optional scope]: <description>

[optional body]

[optional footer(s)]

• النوع: يصف فئة التغيير. انظر الأنواع المدعومة.
• النطاق: (اختياري) يصف ما يتأثر بالتغيير
• الموضوع: وصف صغير للتغيير
• body: (اختياري) معلومات سياقية إضافية حول التغيير
• التذييل: (اختياري) يضيف روابط خارجية ومراجع المشكلات والمعلومات الوصفية الأخرى

أي:

 chore: automate release
fix(styles): fix button padding
feat(script): add auto focus to fields with errors

نحن نستخدم husky و commitlint للتحقق من صحة الرسائل عند الالتزام.

نحن نستخدم إجراءات Github مع semantic-release لإصدار نسخة جديدة من السمة بمجرد دمج العلاقات العامة. في كل عملية دمج، يقوم semantic-release بتحليل رسائل الالتزام ويستنتج زيادة في الإصدار الدلالي. ثم يقوم بعد ذلك بإنشاء علامة git، وتحديث إصدار البيان وإنشاء سجل التغيير المقابل.

أنواع الالتزام

تصف القائمة أدناه أنواع الالتزام المدعومة وتأثيرها في الإصدار وسجل التغيير.

يكتب	وصف	يطلق	سجل التغيير
يبني	التغييرات التي تؤثر على نظام البناء أو التبعيات الخارجية	-	-
عمل روتيني	التغييرات الأخرى التي لا تعدل كود المصدر	-	-
ci	تغييرات على ملفات تكوين CI والبرامج النصية الخاصة بنا	-	-
مستندات	التوثيق يتغير فقط	-	-
الفذ	ميزة جديدة	صغير	سمات
يصلح	إصلاح الخلل	رقعة	إصلاحات الأخطاء
الأداء	تغيير التعليمات البرمجية الذي يعمل على تحسين الأداء	رقعة	تحسينات الأداء
إعادة بناء	تغيير التعليمات البرمجية الذي لا يصلح خطأ ولا يضيف ميزة	-	-
يرجع	إرجاع الالتزام السابق	رقعة	يعود
أسلوب	التغييرات التي لا تؤثر على معنى الكود (المسافة البيضاء، التنسيق، الفواصل المنقوطة المفقودة، إلخ)	-	-
امتحان	إضافة الاختبارات المفقودة أو تصحيح الاختبارات الموجودة	-	-

كسر التغييرات

يجب أن تتضمن الالتزامات التي تضيف تغييرًا عاجلاً BREAKING CHANGE في نص رسالة الالتزام أو تذييلها.

أي:

 feat: update theme to use theming api v2

BREAKING CHANGE: theme is now relying on functionality that is exclusive to the theming api v2

سيؤدي هذا بعد ذلك إلى إنشاء إصدار رئيسي وإضافة قسم BREAKING CHANGES في سجل التغيير.

تقارير الأخطاء

يجب إرسال تقارير الأخطاء من خلال قنوات الدعم القياسية الخاصة بـ Zendesk: https://www.zendesk.com/contact/