تطوير قوالب ووردبريس صف وتسجيل ملفات Javascript و CSS في قوالب ووردبريس

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

فهرس السلسلة:

• مقدمة إلى تطوير قوالب ووردبريس: تحويل صفحة HTML إلى قالب ووردبريس
• التصفيح (Pagination) في قوالب ووردبريس
• إضافة قوائم التنقل (Navigation Menu) إلى قالب ووردبريس
• صف وتسجيل ملفات Javascript و CSS في قوالب ووردبريس (هذا الدرس)

ما المقصود بالصف؟

هو وضع الملف في صفّ/دور/طابور (queue) لتقوم ووردبريس بمعالجته لاحقاً. تخيل أنك تضع الملف في دور/طابور شراء جهاز آي فون جديد مثلاً! 
وعندما يحين موعد عرض الملفات، تقوم ووردبريس بمعالجة الصفّ ومتطلبات كل ملفّ فيه، ثم إعادة ترتيب الصف حسب المتطلبات، وأخيراً عرض الملفات في مكانها المناسب مع متطلباتها.

الخطوات العامة

سنعرض الآن الخطوات بشكل عام، ثم تفصيلها وطريقة استخدامها في الفقرة اللاحقة.

لصفّ ملفٍّ ما، سواء كان ملف JavaScript أو CSS نحتاج إلى:

1. استخدام الحدث (action) المناسب.
2. تسجيل الملف المراد استخدامه؛ حيث يجب استخدام معرّف (handle) للملف، مسار الملف، ويمكن تحديد متطلباته (dependencies) إن وُجدت.
3. صفّ الملف (enqueue)؛ باستخدام المعرّف المُستخدم أثناء تسجيل الملف.

تسجيل وصف ملفات CSS

تسجيل ملف CSS

لتسجيل ملفٍّ جديد نقوم باستخدام دالّة wp_register_style، يمكن للدالّة أن تقبل المحدّدات التالية:

• handle$: مطلوب، هو المعرّف الخاص بالملف، الذي سيتم استخدامه عند صفّ الملف (enqueue).
• src$: مطلوب، هو رابط (URL) ملف CSS المطلوب تسجيله، مثل:http://example.com/css/mystyle.css، لكن يجب ألا يتم استخدام الرابط بهذا الشكل، بل يجب أن يكون أكثر مرونة (التفصيل في الملاحظة بعد نهاية الفقرة).
• deps$: مصفوفة من المعرّفات، التي تمثّل متطلبات الملف الذي نقوم بتسجيله، كي يتم صفّها قبل صفّ الملف المُسجَّل. القيمة الافتراضية: مصفوفة فارغة ()array.
• ver$: إصدار الملف المُسجَّل، تقوم ووردبريس بوضعه كرقم بعد رابط الملف، على الشكل:custom.css?ver=123، إن لم يتم وضع قيمة لهذا المحدّد، فسيتم وضع إصدار ووردبريس الحالي بدلاً منه، لعدم وضع أي رقم نضع قيمة المحدّد null. القيمة الافتراضية:false.
• media$: قيمة حقل media الذي سيتم استخدامه مع وسم <link> أثناء صفّ الملف، القيمة الممكنة: all، screen، handheld، print. القيمة الافتراضية هي all.

ملاحظة هامة: عند تسجيل أو صفّ الملفات، يجب أن تكون الروابط مرنة، أي أن يتم استبدال اسم الموقع/النطاق عن طريق دوالّ ووردبريس. 
مثال خاطئ:

add_action( 'wp_enqueue_scripts', 'register_invalid_style' );

function register_invalid_style() {
    wp_register_style( 'my-invalid-style', 'http://localhost/wp-content/themes/my-theme/css/custom.css' );
}

هل لاحظتم أنني وضعت المسار كاملاً؟ ترى هل سيعمل الرابط السابق إن قمنا باستخدام القالب على موقع على الإنترنت بدلاً من الموقع المحلّي؟ بالتأكيد لا!

مثال صحيح:

add_action( 'wp_enqueue_scripts', 'register_valid_style' );

function register_valid_style() {
    wp_register_style( 'my-valid-style', get_template_directory_uri() . '/css/custom.css' );
}

تكون النتيجة في المتصفح مشابهة للتالي:

<link rel='stylesheet' id='my-valid-style-css'  href='http://localhost:8000/wp-content/themes/my-theme/css/custom.css?ver=4.2' type='text/css' media='all' />

تقوم دالّة ()get_template_directory_uri بإرجاع رابط القالب الفعّال (active)، مثلاً: http://example.com/wp-content/themes/my-theme، بحيث يكون اسم النطاق حسب الموقع الحالي، ثم يقوم المطوّر بإضافة مسار الملّف الذي يريده بعد رابط القالب الفعّال.

إن أردنا تسجيل وصفّ الملفات ضمن الإضافات بدلاً من القوالب، نقوم باستخدام دالّة ()plugins_url بدلاً من الدالّة السابقة الخاصة بالقوالب.

صف ملف CSS

لصفّ ملف CSS نستخدم دالّة wp_enqueue_style، محدّدات الدالّة هي نفسها محدّدات دالّة wp_register_style، باستثناء:

• محدّد handle$ هو المحدد الوحيد المطلوب في حال استخدامنا لمعرّف ملف مُسجّل مسبقاً.
• محدد src$ غير مطلوب في حال نقوم باستخدام معرّف لملف مُسجّل مسبقاً، ومطلوب إن كنا نريد استخدام الدالّة لصفّ ملفّ غير مسجّل. فعوضاً عن تسجيل الملف بدالّة منفصلة ثم صفّه بدالّة أخرى، نقوم بصفّه مباشرة في هذه الدالّة.

مثال عن صفّ ملف مسجّل مسبقاً:

add_action( 'wp_enqueue_scripts', 'enqueue_style' );

function enqueue_style() {
wp_enqueue_style( 'my-valid-style' );
}

مثال عن صفّ ملف جديد دون تسجيل:

add_action( 'wp_enqueue_scripts', 'register_enqueue_style' );

function register_enqueue_style() {
    wp_enqueue_style( 'my-valid-style', get_template_directory_uri() . 'my-theme/css/custom.css' );
}

نلاحظ أننا في المثال الثاني استخدمنا دالّة wp_enqueue_style بشكل مماثل لدالّة wp_register_style. 

الفرق الرئيسي بين الطريقتين، أن الأولى تسمح لنا باستخدام الملف المُسجل في عدة أماكن، وتتيح مرونة أكبر بالتعامل مع الملفات.

إلغاء صفّ أو إلغاء تسجيل ملف CSS

قد نحتاج لإلغاء صفّ ملف، أو إلغاء تسجيله (كما سنرى في نهاية المقال)، تتيح ووردبريس دالّتين لهذين الغرضين هما: wp_dequeue_style لإلغاء صفّ ملف و wp_deregister_style لإلغاء تسجيل ملف.

في كلا الدالّتين نقوم بتمرير محدّد واحد هو المعرّف الخاص بالملف الذي نريد إلغاء صفّه أو إلغاء تسجيله، لإلغاء صفّ إطار عمل Bootstrap مثلاً، نضع الأسطر التالية في ملف functions.php:

add_action( 'wp_enqueue_scripts', 'dequeue_bootstrap' );

function dequeue_bootstrap() {
    wp_dequeue_style( 'bootstrap' );
}

تسجيل وصفّ ملفات جافاسكريبت

آلية تسجيل وصفّ ملفات جافاسكريبت هي مماثلة جداً للتعامل مع ملفات CSS، مع بعض الفروقات البسيطة التي سنستعرضها الآن.

تسجيل ملف جافاسكريبت

نقوم باستخدام دالّة wp_register_script، التي تقبل المحدّدات التالية:

• handle$: مطلوب، هو المعرّف الخاص بالملف، الذي سيتم استخدامه عند صفّ الملف (enqueue).
• src$: مطلوب، هو رابط (URL) ملف جافاسكريبت المطلوب تسجيله، مثل:http://example.com/js/myscript.js، لكن يجب ألا يتم استخدام الرابط بهذا الشكل، بل يجب أن يكون مرناً باستخدام ()get_template_directory_uri.
• deps$: مصفوفة من المعرّفات، التي تمثّل متطلبات الملف الذي نقوم بتسجيله، كي يتم صفّها قبل صفّ الملف المُسجَّل. 
  القيمة الافتراضية: مصفوفة فارغة ()array.
• ver$: إصدار الملف المُسجَّل، تقوم ووردبريس بوضعه كرقم بعد رابط الملف، على الشكل:custom.js?ver=123، إن لم يتم وضع قيمة لهذا المحدّد، فسيتم وضع إصدار ووردبريس الحالي بدلاً منه، لعدم وضع أي رقم نضع قيمة المحدّد null. 
  القيمة الافتراضية: false.
• in_footer$: بشكل افتراضي يتم صفّ ملفات جافاسكريبت وملفات CSS ضمن وسم <head>، لكن يمكن بوضع قيمة هذا المحدد true أن يتم صفّ ملفات جافاسكريبت في نهاية المستند، قبل إغلاق وسم <body/>، وهو الأفضل للأداء بالنسبة لزوار الموقع. 
  القيمة الافتراضية: false.

ملاحظة: صفّ ملفّات جافاسكريبت و CSS يتطلب وجود خطّاف ()wp_head ضمن القالب، وصفّ ملفات جافاسكريبت مع محدّد in_footer$ بقيمة true يتطلب وجود خطّاف ()wp_footer في القالب، قبل إغلاق وسم <body/>.

صفّ ملف جافاسكريبت

الاستخدام مشابه تماماً لصفّ ملف CSS، لكنه يتم عن طريق دالّة wp_enqueue_script، والتي تشابه بمحدداتها دالّة التسجيل wp_register_script.

الفرق بين محددات دالة الصفّ ودالّة التسجيل الخاصة بملفات جافاسكريبت هي كالفرق بين محددات دالة الصف والتسجيل الخاصة بملفات CSS. محدّدات دالّة wp_enqueue_script هي نفسها محدّدات دالّة wp_register_script، باستثناء:

• محدّد handle$ هو المحدد الوحيد المطلوب في حال نقوم باستخدام معرّف لملف مُسجّل مسبقاً.
• محدد src$ غير مطلوب في حال نقوم باستخدام معرّف لملف مُسجّل مسبقاً، ومطلوب إن كنا نريد استخدام الدالّة صفّ ملفّ غير مسجّل. فعوضاً عن تسجيل الملف بدالّة منفصلة ثم صفّه بدالّة أخرى، نقوم بصفّه مباشرة في هذه الدالّة.

إلغاء صفّ أو إلغاء تسجيل ملف جافاسكريبت

طريقة إلغاء صفّ أو إلغاء تسجيل ملف جافاسكريبت هي مشابه للطريقة في ملفات CSS، لكن باستخدام دالّتي: wp_deregister_script و wp_dequeue_script.

أمثلة وحالات استخدام

بالمثال يتضح المقال، سنمرّ معاً على أربعة أمثلة وحالات استخدام لنرى من خلالها كيف يمكننا التعامل ثم الاستفادة من تسجيل وصفّ ملفات JavaScript و CSS:

1. عند استخدام إضافة رديئة الجودة

لنفرض لسبب ما أنك تستخدم إضافة رديئة -لا تتبع المعايير ولا تستخدم أحد الإصدارات من المكتبات-، تتطلب هذه الإضافة وجود إصدارٍ قديم من مكتبة jQuery، بينما قالبك يستخدم الإصدار اﻷحدث منها. هل من المنطقي وجود نسختين من المكتبة في القالب؟ بالتأكيد لا.

لحلّ هذه المشكلة نحن أمام ثلاثة خيارات:

1. إن كانت الإضافة ليست رديئة الجودة كثيراً، وتقوم بصفّ مكتبة jQuery، فهذا شيء جيّد، يمكننا ببساطة إلغاء المكتبة من الصفّ وتنتهي المشكلة.
2. إن كانت الإضافة رديئة كما وصفناها ولا تقوم بصفّ مكتبة jQuery، عندها يجب على المطوّر أن يقوم بالتعديل على ملفات الإضافة يدوياً لإلغاء تحميل مكتبة jQuery. وهناك احتمال كبير أن المطور سينسى التعديل الذي قام به، ومع مرور الأيام يقوم بتحديث الإضافة إلى إصدار جديد ويذهب التحديث اليدويّ الذي قام به! أو إن كان ذو ذاكرة قوية، سيقوم بالقيام بالتعديل اليدوي ذاته في كل مرة يظهر إصدار جديد من الإضافة. لكم أن تتخيلوا المعاناة التي ستصبح على كاهل المطوّر.
3. الخيار الثالث والأسرع هو القيام بحذف هذه الإضافة رديئة الجودة والبحث عن واحدة أفضل منها تتبع المعايير والقواعد وتستخدم أحد الإصدارات من ملفات JavaScript و CSS.

الخيار الثالث هو الأفضل لتقليل استخدام مسكنات ألم الرأس.

من المهم اتباع المعايير والقواعد المتفق عليها حتى لا يقع المطوّر في الحُفر التي وُضعت تلك المعايير والقواعد من أجل تلافيها.

2. استخدام المكتبات الموجودة في ووردبريس

ربّما حدّثتك نفسك في أحد الأيام أن تستعرض ملفات ووردبريس وترى محتواها، إنْ حدث ذلك فلا بدّ أنك رأيت الكثير من مكتبات جافاسكريبت مثل jQuery، jQuery UI، Backbone وغيرها.

إن كانت هذه الملفات موجودة ضمن ووردبريس، فلمَ لا نقوم باستخدامها عند الحاجة إليها؟ 
لو كان القالب يحتاج إلى مكتبتيّ jQuery و jQuery UI فبدلاً من تحميل نسخة من كل مكتبة من الإنترنت ثم وضعها ضمن ملفات القالب واستخدامها، يمكننا بشكل مباشر استخدام نسخة jQuery و jQuery UI الموجودتان ضمن ووردبريس. بهذا نضمن الحصول على إصدار حديث من المكتبة يأتي مع كل تحديث لووردبريس بالإضافة لعدم التكرار (Don’t Repeat Yourself).

من المكتبات الشهيرة المضمّنة في ووردبريس:

• jQuery
• jQuery UI
• Backbone
• jQuery Suggest
• Thickbox
• TinyMCE
• Underscore

للاطلاع على كامل القائمة يمكن زيارة صفحة التوثيق.

3. استخدام jQuery بشكل مباشر من شبكة توصيل المحتوى (CDN)

لا بدّ أنك سمعت بشبكة توصيل المحتوى (Content Delivery Network). تعريفها على ويكبيديا:

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

هناك موقع مخصص لاستخدام مكتبات JavaScript عن طريق شبكات توصيل المحتوى هو jsDelivr، سنقوم باستخدام رابط مكتبة jQuery منه (//cdn.jsdelivr.net/jquery/2.1.3/jquery.min.js) لنقوم بصفّها واستخدامها ضمن القالب، عوضاً عن استخدام النسخة المتضمنة في ملفات ووردبريس.

للقيام بهذا نحتاج لوضع الأسطر القليلة التالي في ملف functions.php الخاص بقالبنا:

add_action( 'wp_enqueue_scripts', 'register_jquery' );
function register_jquery() {
    wp_deregister_script( 'jquery' );
    wp_register_script( 'jquery', ( '//cdn.jsdelivr.net/jquery/2.1.3/jquery.min.js' ), false, null, true );
    wp_enqueue_script( 'jquery' );
}

قمنا بإلغاء تسجيل jQuery (كانت مسجلة مع الملف المتضمَّن في ووردبريس)، ثم قمنا بتسجيلها مع رابط الملف من شبكة توصيل المحتوى (CDN)، وأخيراً قمنا بصفّها (enqueue) ليتم إدراجها في القالب.

4. صفّ ملف جافاسكريبت يعتمد على jQuery

في معظم الحالات نحتاج في القوالب لإضافة جافاسكريبت، سواء لإضافة حركات معيّنة أو لتعديل شيءٍ ما، وبسبب شهرة مكتبة jQuery فمعظم المطورين يعتمدون عليها كقاعدة أساسية لبناء ملفات جافاسكريبت الخاصة بقوالبهم.

على فرض أن الملف الذي نريد إضافته يعتمد على مكتبة jQuery وهو موجود مع ملفات القالب في المسار: js/custom.js، لصفّ هذا الملف نقوم بإضافة الأسطر التالية إلى ملفfunctions.php:

add_action( 'wp_enqueue_scripts', 'enqueue_custom_js' );
function enqueue_custom_js() {
    wp_register_script( 'my-custom-js', get_template_directory_uri() . '/js/custom.js', ['jquery'] );
    wp_enqueue_script( 'my-custom-js' );
}

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

تكون النتيجة في المتصفح مشابهة للتالي:

<script type="text/javascript" src="//cdn.jsdelivr.net/jquery/2.1.3/jquery.min.js?ver=4.2"></script>
<script type="text/javascript" src="http://localhost:8000/wp-content/themes/my-theme/js/custom.js?ver=4.2"></script>

ونلاحظ أن ووردبريس قامت بصفّ مكتبة jQuery قبل الملف الذي قمنا بتسجيله، وذلك كي يقوم المتصفح بقراءة ملف المكتبة في البداية وتكون متوفرة للاستخدام، وعند قراءة المتصفح للملف الخاص يمكن للملف استخدام مكتبة jQuery بعد أن أصبحت متوفرة.

تمرير متغيّرات من PHP للجافاسكريبت

ماذا لو أردنا استخدام متغيّرات ما ضمن جافاسكريبت؟ قد يتهيؤ للبعض أن يقوم بعمل طلب AJAX أو وضع ما يريد استخدامه في جافاسكريبت بداخل ملف خارجي. قد تعمل هذه الحلول، لكنها لن تجدي نفعاً إن أردنا تمرير متغيّرات تتبدّل قيمتها باستمرار كأن تكون من قاعدة البيانات مثلاً.

توفّر ووردبريس حلّاً سهلاً ومناسباً لهذه المشكلة، وذلك باستخدام دالّة wp_localize_script، اسم الدالّة قد يوحي أنها مخصصة للترجمة، لكن يمكن استخدامها لتمرير جمل الترجمة وأي نوع آخر من المتغيّرات إلى جافاسكريبت.

محددات الدالّة هي: 
- handle$: معرّف لملف جافاسكريبت الذي نريد تمرير المتغيّرات له، يجب أن يكون الملف مسجّلاً قبل استخدام الدالّة. 
- name$: اسم متغيّر جافاسكريبت الذي سيتم وضع البيانات بداخله. 
- data$: مصفوفة المتغيّرات التي نريد تمريرها إلى جافاسكريب.

مثال: لنقم بتمرير متغيّرين هما سلسلة نصية ورقم إلى ملف جافاسكريبت ذو المحدد my-custom-js:

add_action( 'wp_enqueue_scripts', 'enqueue_custom_js' );
function enqueue_custom_js() {
    wp_register_script( 'my-custom-js', get_template_directory_uri() . '/js/custom.js', ['jquery'] );

    $translation_array = array(
        'some_string' => 'A String to be using inside JS',
        'a_value' => '10'
    );

    wp_localize_script( 'my-custom-js', 'object_name', $translation_array );
    wp_enqueue_script( 'my-custom-js' );
}

كي نصل إلى المتغيّرات من داخل ملف custom.js، نستخدم شيئاً مشابهاً:

alert( object_name.some_string);

يجب أن تظهر رسالة تنبيه (Alert) بداخلها النصّ الذي استخدمناه.

صفّ الملفات في لوحة التحكم

كل ما مرّ معنا من تسجيل وصفّ الملفات هو خاص بواجهة الموقع (Front-end)، أي الذي يراه الزوار. إن أردنا تسجيل وصفّ الملفات في لوحة التحكم (Dashboard) يمكننا ذلك بنفس الطريقة، لكن باستبدال حدث wp_enqueue_scripts بحدث: admin_enqueue_scripts. 
مثلاً لصفّ مكتبة jQuery Suggest في لوحة التحكم (المكتبة معرّفة مسبقاً في ووردبريس)، نستخدم الأسطر التالية:

add_action( 'admin_enqueue_scripts' , 'enqueue_jquery_suggest' );

function enqueue_jquery_suggest() {
    wp_enqueue_script( 'suggest' );
}

ملاحظة: من المناسب وضع شروط معيّنة قبل صفّ الملفات وقصرها على صفحاتٍ معينة، كي لا يتم وضع الملف في كل صفحات لوحة التحكم.

الخاتمة

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

أرجو أن يكون الشرح واضحاً ومفيداً، إن كان لديكم سؤال أو فكرة فلتشاركونا إياها في التعليقات.