التثبيت والإعداد

إصدارات جاهزة الإعداد

التثبيت المخصص

لبناء تكاملك الخاص، نزّل نسخة محلية (أو أشِر إلى نسخة على CDN) من حزمة لغة، وملف JS المصغَّر، وملف CSS المصغَّر، ثم أنشئ مثيلًا جديدًا من «Ed11y».

عند استيراد وحدات ESM/JS:

استخدم ملفات JavaScript ذات الامتداد .umd مع المتصفحات والأنظمة القديمة:

المعاملات

لا يُستدعى التكامل المكتمل إلا للمحررين المسجَّل دخولهم (فأنت لا تريد أن يرى زوار موقعك المدقق!)، ويمكنه تجاوز أيٍّ من المعاملات الافتراضية.

لاحظ أن لجميع المعاملات قيمًا افتراضية؛ لذا لا تُضمِّن إلا ما تريد تجاوزه.

قد يبدو التكامل المخصَّص بدرجة كبيرة على هذا النحو:

كثيرًا ما تضبط التكاملات الجاهزة هذه المتغيرات أثناء التشغيل، فمثلًا تُحمِّل الصفحات في الوضع «assertive» إذا عُدِّلت مؤخرًا، ثم تعود إلى الوضع «polite» بعد عدة دقائق.

تخصيص المظهر

تتيح عدة معاملات اختيار قالب، وتجاوز الألوان، وحقن CSS.

لا تُضمِّن إلا المعاملات التي تحتاج إلى تجاوزها، لتسهيل التحديثات المستقبلية.

أحداث JS مفيدة

يمكن لمطوري القوالب الاستماع إلى هذه الأحداث للتفاعل معها وتعديل الصفحة حسب الحاجة.

بترتيب ظهورها المعتاد…

  • ed11yRunCustomTests: يُطلَق عندما يصبح كائن Results جاهزًا لحقن نتائج مخصصة فيه. لاحظ أنه يجب ضبط المعامل customTests على عدد دوال الاختبارات المخصصة التي ستشغّلها (…على الأرجح دالة واحدة…) كي يُطلَق هذا الحدث. التفاصيل في القسم التالي.
  • ed11yResults: يُطلَق عند انتهاء جميع الفحوصات. يمكن لتكاملات API حينئذٍ استخراج البيانات من الكائن Ed11y.results.
  • ed11yPanelOpened: يُطلَق عند فتح اللوحة، تلقائيًا أو يدويًا.
  • ed11yShowHidden: يوفّر رقم data-ed11y-result وقيمة منطقية viaJump. لا يُطلَق إلا إذا ضُبط المعامل «ed11yShowHidden» وكان أحد العناصر الأصل للعنصر يطابق محددًا. يُستخدم لإظهار التنبيهات الموجودة داخل حاويات لم تُفتح بعد، مثل الأكورديونات وعلامات التبويب ودوّارات الشرائح. أمثلة الاستخدام في القسم التالي.
  • ed11yPop: يوفّر قيمة ID من data-ed11y-result، إضافةً إلى مراجع للكائنين result وtip. يُطلَق عند ظهور تلميح، مما يتيح لك تعديل التلميحات أثناء التشغيل.
  • ed11yShut: يوفّر قيمة ID من data-ed11y-result. يُطلَق عند إغلاق تلميح.
  • ed11yDismissalUpdate: يوفّر معلومات موسّعة عندما يتجاهل مستخدم تنبيهًا أو يستعيده. يُستخدم لتكاملات API. يحتوي كائن الحدث على:
    • dismissPage
    • dismissTest
    • dismissKey
    • dismissAction

ستجد أمثلة في الأقسام التالية.

تعديل التلميحات

إذا كان كل ما تريده هو تعديل نص تلميح، فيمكنك تجاوز العناصر مباشرةً في الكائن العام ed11yLang.en (قبل استدعاء المكتبة) أو في الكائن Ed11y.M (بعد استدعاء المكتبة). على سبيل المثال، في وحدة Drupal حيث جعلنا Drupal.ed11yLang اسمًا مستعارًا لحزمة اللغة:

Drupal.ed11yLang.lang.testNames.title = "Please write shorter headings."

ينطبق هذا على أيٍّ من المفاتيح الافتراضية في ملف التوطين أو في الترجمة النشطة الخاصة باللغة.

تضيف وحدة Drupal أيضًا روابط تحرير مخصصة إلى التلميحات باستخدام المعامل editLinks. لاحظ الرابطين «Page editor» و«Layout editor»:

تلميح أُدرج فيه رابطا «Page editor» و«Layout editor».

نسخة مبسطة من الشيفرة التي تضبط هذا المعامل:

ثم تستخدم وحدة Drupal الحدث ed11yPop لإظهار رابط التحرير أو إخفائه ديناميكيًا حسب السياق عند عرض التلميحات.

يوفّر هذا الحدث مراجع للكائنين result وtip:

الاختبارات المخصصة

إذا كانت قيمة المعامل customTests رقمًا، فسيُطلق Editoria11y الحدث «ed11yRunCustomTests» أثناء الفحص، ثم يتوقف مؤقتًا لمدة تصل إلى 500 ميلي ثانية منتظرًا ذلك العدد من أحداث «ed11yResume».

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

على سبيل المثال، إذا أردت إنشاء هذا التلميح للإشارة إلى الروابط الملصوقة من رسائل البريد الإلكتروني بعناوين URL مموّهة:

تلميح نصه «URL is Safe Link Encoded»

ستحتاج إلى:

  1. إضافة مستمع للحدث ed11yRunCustomTests
  2. البحث عن العناصر المطابقة
  3. تعريف رسالة التلميح
  4. إطلاق الحدث «resume» ليرسم Editoria11y التلميح:

التعامل مع التنبيهات في المحتوى المخفي أو محدود الحجم

تُخفي كثير من المكونات التفاعلية (علامات التبويب، وشرائح العرض، والأكورديونات) جزءًا من المحتوى. تتضمن لوحة معلومات Editoria11y زرَّي «التالي» و«السابق» للانتقال مباشرةً إلى المشكلات. إذا قدّر Editoria11y أن تلميح المشكلة غير ظاهر حاليًا، فسينبّه المستخدم إلى وجود خلل، ثم يُبرز أول عنصر أصل ظاهر، مثل عنصر div المحيط بالأكورديون.

من الأفضل أن يُظهر قالبك تلك العناصر قبل أن يجري Editoria11y فحص الظهور، فيعمل كل شيء كالسحر لمستخدميك: تتقدم دوّارات الشرائح تلقائيًا وتنفتح الأكورديونات تلقائيًا لعرض المشكلة.

لفعل ذلك عند فتح اللوحة أول مرة (مثل فتح جميع لوحات الأكورديون التي تحتوي على مشكلات)، أضف مستمع أحداث JS للحدث ed11yPanelOpened، ثم نفّذ querySelectorAll للعثور على عناصر ed11y-element-result المعنية، ثم استدعِ الدالة التي يستخدمها قالبك لإظهار ذلك الجزء من الصفحة.

إليك مثالًا يعتمد على jQuery. عند فتح اللوحة، يعطّل المثال قائمة مثبّتة (حتى لا تُغطّى العناصر)، ثم يبحث عن أي عناصر ed11y-element-result داخل عناصر أكورديون مغلقة ويحاكي النقر على زر التبديل الخاص بها:

لإظهار المحتوى فقط عند الانتقال إلى تلميح محدد عبر زر «التالي» في اللوحة (مثلًا في علامة تبويب مغلقة أو في الشريحة التالية من دوّار الشرائح)، ستحتاج إلى ضبط hiddenHandlers على محددات CSS المناسبة، وضبط checkVisible على TRUE في معاملاتك. ثم أضف مستمع أحداث للحدث ed11yShowHidden. يُطلَق هذا الحدث إذا تبيّن لـ Editoria11y أن التلميح موجود داخل حاوية تطابق أحد محددات hiddenHandlers المذكورة في قائمة الخيارات. يتضمن حدث JS هذا قيمة ID للتلميح الذي يوشك على فتحه. بعد إطلاق هذا الحدث، يتوقف Editoria11y برهةً ليمنح شيفرة JS لديك الوقت الكافي لإظهار العنصر.

إليك مثالًا من تكامل لدى Penn State. يبحث المثال عن العنصر المطابق لقيمة ID المقدَّمة، ثم يعثر على الحاوية الأصل للمكوّن التفاعلي الذي يضمه، ويُطلق الحدث الخاص بها لتفعيل زر التبديل:

ملاحظة أخيرة: بعض القوالب لا تتوافق ببساطة مع فحص الظهور، كأن يكون ارتفاع الحاوية <main> مساويًا 0px. على هذه المواقع تعطيل فحص الظهور كليًا بضبط checkVisible على false.