تطوير ووردبريس للمبتدئين تطوير ووردبريس للمبتدئين: برمجة إضافة – المعلقات، الأفعال والمرشحات

هل أنت مهتّمٌ بإنشاء إضافة ووردبريس خاصّة بك من الصّفر؟

إن لم تكُن قد قمت ببرمجة إضافة خاصّة بك من قبل فقد يبدو لك ذلك كالتوغل في عالم مجهولٍ، خاصّة إن لم تكُن تثق بمهاراتك في لغة PHP. التحدّي الذي ستواجهه سيكون معرفتك من أينَ ستبدأ، بالإضافة إلى قدرتك على تقبّل إمكانيّة ارتكابك لعدّة أخطاءٍ طيلة مسار التعلّم. الإضافات تسمح لك بإضافة جميع أنواع الوظائف الممكنة للووردبريس، انطلاقًا من إضافة استمارة تواصلٍ بسيطةٍ إلى صفحة ما لتعزيز حماية موقعك وُصولًا إلى إضافة قدرات تجارةٍ إلكترونية. تقريبًا يوجد إضافة لأيِّ شيءٍ يخطُر على بالك، إن لم يكن كذلك فيمكنك دائمًا إنشاء واحدة وفق تصوّراتك وحاجاتك. في هذا الدّرس ستتعلّمٌ طريقة برمجة إضافتك الخاصّة لكي تتمكّنً من تعديل وظائف: موقعك الووردبريس أو الإضافات الأخرى أو حتّى القوالب إن أردت.

المعلِّقات، الأفعال و المرشِّحات (Hooks, Actions, Filtres )

قبل البدء بإنشاء إضافة خاصّة، فلنبدأ أوّلًا بإلقاء نظرةٍ مفصّلةٍ على المعلِّقات "hooks"، الأفعال "actions" والمرشِّحات "filtres". إنّها تلك العناصر التي يترّكز عليها نظام الإضافة بالكامل والتّي ستُساعدك بشكلٍ كبيرٍ لفهم ما يحدث خلف الستار حول طريقة عمل الووردبريس. لنلقِ نظرة على هذا المثال. ماذا لو أردتَ إنشاء إضافةٍ تقوم بإضافة شفرة تتبُّع تحليليّةٍ لموقعك؟ في العادة هذا النوع من البرمجيّات يتمُّ إضافته في نهاية صفحة الموقع مباشرة فوق وسمِ الإغلاق. هذه الشفرة يجب أن تبقى في ذلك المكان حتّى وإن تمّ تغيير القالب ويجب أن تعمل على أيّ موقع ووردبريس، إذًا كيف ستجعل هذه الشفرة تعمل دائمًا إن لم تكن لديك أية سلطة تحكّم مباشر على القوالب؟ تذكّر أنّه في درس تطوير ووردبريس للمبتدئين: برمجة القوالب قمت بذكر دوال ()wp_head و ()wp_footer و الطريقة التي يجب عليك إضافتها بها في قالبك. مثالنا هذا يبيّن بالتحديد لماذا يجب أن توضع هذه الدّوال بالطريقة المحدّدة سلفًا. دالّة ()wp_footer يمكنها أن تقوم بتشغيل دوالٍّ أخرى محدّدة بواسطة الإضافات. إليك مثال كود يمكنك أن تستمتع بالتجريب عليه:

<?php 
function my_tracking_code() {
  echo 'Paste tracking code from Google Analytics here';
}
add_action( 'wp_footer', 'my_tracking_code' );

لنقم الآن بتفكيك الكود قطعةً قطعة. أوّلًا لقد قمت بكتابة دالّة تقوم بطبع شفرة التتبّع. هذه الدالّة غيرُ مستخدمة في أيّ مكان، هي فقط موجودة بإضافتي. بعد ذلك استخدمت دالّة ()add_action لإخبار الووردبريس متى يجب تشغيل الدالّة. متى ما وجد ووردبريس بدالّة ()wp_header فإنّه سيجد كلّ الدّوال المعلّقة بها بواسطة ()add_action . عندئذٍ سيقوم الووردبريس بتشغيل هذه الدّوال واحدة بواحدة وصولًا إلى دالّتنا التي تقوم بطبع شفرة التتبّع كنتيجة. هذا هو أساس المعلِّقات "hooks" ولكنّنا سنخوض فيها بشكلٍ أعمق لاحقًا خلال هذا الدَّرس لكي تتعلّم عنهم أكثر وتكون قادرًا على استغلال قدراتهم بشكل أفضل. قبل الانتقال إلى شيء آخر أريد ان ألفت انتباهك الى شيء مهم، دالة ()wp_footer الموجودة في تذييل القالب ليست معلِّقا "hook" بل هي في الحقيقة مجرّد دالّة تحتوي على معلِّق في مكان ما بداخلها. للنداء على معلِّق "hook" نستخدم (’do_action(’wp_footer، لكنّ هذا لم يكن مهمًّا في المثال الأوّل. على كلٍّ ستفهم أكثر عن هذا قريبًا!

المصطلحات

الآن وبعد أن أخذت لمحةً عمَّا سنتحدث عنه، دعني أشرح لك بطريقةٍ مرتّبةٍ المصطلحات التي ستلتقي بها طيلة هذا الدّرس. المعلِّقات "hooks" هي جزء من API إضافات الووردبريس. الأفعال والمرشِّحات "Actions and Filtres" عبارة عن نوع مختلف من المعلِّقات. الأفعال "actions" تسمح لك بإضافة وظائف، أنت في الأساس ستقوم بتحديد دالّة تشتغل في كلّ مرّة يقوم ووردبريس بمعالجة المعلِّق "hook" . المرشِّح "filter" يعمل بشكل مماثل و لكنّه عوض أن يضيف دوالًّا جديدة يقوم بتعديل الدوّال الموجودة مسبقًا بالووردبريس. مثلًا ووردبريس يحتوي على معلِّق يحدّد طول المقتطف إلى 55 كلمةٍ، يمكنك تعديل ذلك باستخدام المرشِّح لجعل عدد كلمات المقتطف أيَّ رقم ترغب به.

كلًّ شيءٍ عن الأفعال:

الآن وبعد أن صِرنا نعرف القواعد، فلنلقِ نظرةً مفصّلةً على دالّة ()add_action لفهمها بشكلٍ أفضل. هذه الدّالة تأخذ أربعة معاملات هم:

• اسم المعلِّق.
• اسم الدالّة التي نريد إضافتها للمعلِّق.
• الأولويّة.
• المعاملات المقبولة.

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

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

مثال عن فعل

ووردبريس لا يوفّر الأفعال للقوالب فقط ولكن أيضًا لواجهة المدير إضافةً إلى أفعال خاصّة بالمستخدمين. معلِّق publish_post يتم تشغيله في كلِّ مرّةٍ يتم نشر مقال ما ليسمح لك بالقيام بشيءٍ ما في تلك المرحلة. الحاجة للمُعاملات تصبحُ ظاهرةً هنا. إذا قمتُ بإضافة دالّةٍ لهذا المعلِّق فكيف لي أن أعرف أيَّ مقالٍ تمَّ نشرهُ وماذا كانت تفاصيلهُ؟ عند قراءة دليل استخدام المعلِّقات يُمكنك أن ترى أنَّ الدالّة تحتوي على معاملين: مُعامِل معرِّف المقال ومُعامِل بيانات المقال. مثلًا لِنقم بإرسال بريدٍ إلكترونيٍّ لكاتب المقال عندما يُنشر مقاله:

<?php 
function our_author_notification( $id, $post ) {
    $author = $post->post_author;
    $name = get_the_author_meta( 'display_name', $author );
    $email = get_the_author_meta( 'user_email', $author );
    
    $link = get_permalink( $id );
    
    $message = 'Hello ' . $name . ", \n\n" . "Your artcile <a href='" . $link . "'>" . $post->post_title . "</a> has been published.";
    wp_mail( $email, 'One of your posts has been published', $message );
    
}
add_action( 'publish_post', 'our_author_notification', 10, 2 );

كلًّ شيءٍ عن المرشِّحات:

كما سبق وأن ذكرته سابقًا، المرشِّحات تعمل بشكلٍ مماثلٍ للأفعال ولكنّها تقوم بتعديل البيانات لذا ستجد نفسك تقوم بإرجاع نتائج داخل دوالّك المعلّقة. لإضافة مرشِّح نستخدم الدالّةَ ()add_filter التي ستستخدم نفس معاملات الدالّة ()add_action.

مثال عن مرشِّح:

أحسن مثالٍ للبدء به سيكون تعديل كلمة “قراءة المزيد” الموجودة بِنهاية المقتطف، في الوضع الافتراضي ستجدها بهذا الشَّكل "[…]". لتعديلها يمكنك القيام بشيء مثل هذا:

<?php 
function our_excerpt_more( $more ) {
    return '... هناك المزيد';
}
add_filter( 'excerpt_more', 'our_excerpt_more' );

لاحظ أنّني لم أحدّد مُعامل الأولويّة ولا مُعامل عدد المُعاملات المقبولة. هذا سيجعل الأولويّة 10 وعددُ المُعاملات المقبولة 1. هنا أنا لا أستخدم المعامل المُمرَّر في الدالة more$ إطلاقًا، أنا فقط أقوم بإرجاع نص خطّيٍ. يمكنك استخدام نفس الطريقة لتضمين إعلانٍ قبل الفقرة الأولى من مقالك. انظر الى المثال التالي:

function in_content_ad( $content ) {
  $ad = '<div class="in-content-ad"><img src="https://placeholdit.imgix.net/~text?txtsize=33&txt=Advertisement&w=250&h=250"></div>';
  return $ad . $content;
}
add_filter( 'the_content', 'in_content_ad' );

مع قليل من الـ CSS لتعويم الإعلان نحو اليمين، يُمكنك الحصول على صندوقِ إعلاناتٍ قياسيٍّ داخل محتوى مقالك خلال ثوانٍ معدودة.

تعريف المعلِّقات:

معرفة كيفيّة تعريف المعلِّقات إضافة إلى معرفةِ الطريقة التي تُنشِئ بها معلِّقاتك الخاصّة سيكون له أثرٌ كبير على فهمك لنظام ووردبريس. فلنفترض أنَّك تريد إنشاء إضافة متجر إلكتروني وأنّك ستقوم بإضافة وظائف لقائمة المنتجات، يمكنك القيام بشيءٍ مشابه لهذا:

<?php 
$products = get_products( 10 );
show_products();

هنا أنت قمت بكتابةِ برمجيّتك بطريقة "إجباريّة" لكي تقوم بعرض فقط 10 منتجات. ولكن ماذا لو حاول شخص ما صنع إضافة لعملك وأراد أن يُظهر فقط ثلاثة منتجات؟ لو أنّك كتبك برمجيّتك بذكاء فإنّك ستسمح للأخرين بتعديلها. دعنا نستخدم معلّقًا للسماح للمطوّرين باستخدام عملنا وتطويره:

<?php 
$product_count = apply_filters( 'product_count', 10 );
$products = get_products( $product_count );
show_products();

باستخدام دالّة ()apply_filters نحن نقوم بإخبار ووردبريس أنّ عندنا معلِّقًا اسمه product_count و أنّنا نريد أن نشغّل جميع الدّوال المربوطة به. في أيّة إضافة أخرى، يمكن للمطوّر أن يغيّر قيمة عدد المنتجات الظاهرة إلى ثلاثةٍ مثلًا باستخدام الطريقة التالية:

<?php 
add_filter( 'product_count', 'carousel_product_count' );
function carousel_product_count( $count ) {
  return 3;
}

سنتابع في الدرس القادم أساسيات إنشاء الإضافة وكيفية إضافة خصائص القالب للإضافات…

ترجمة -وبتصرّف- للمقال WordPress Development for Beginners: Building Plugins لصاحبه Daniel Pataki