مدخل إلى برمجة إضافات ووردبريس مثال عملي لبرمجة إضافة ووردبريس- الجزء الأوّل

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

التخطيط للإضافة

لنبدأ بتحديد الأمور التي ستقوم بها الإضافة:

• إحصاء عدد المشاهدات لكل مقال.
• توفير شيفرة مختصرة Shortcode لعرض عدد مشاهدات المقال في أي مكان.
• توفير ودجت Widget لعرض المقالات الأكثر مشاهدة.

وذلك من خلال:

• الاستفادة من البيانات الإضافية للمقال Post Meta لإضافة حقل بيانات جديد للمقالات يستخدم في حفظ واسترجاع عدد المشاهدات.
• الاستفادة من Shortcode API التي يوفرها ووردبريس لإنشاء الشيفرة المختصرة.
• الاستفادة من Widget API التي يوفرها ووردبريس لإنشاء الودجت واستخدام صنف WP_Query للحصول على المقالات مرتبة على حسب عدد المشاهدات.

برمجة الإضافة

دعنا في البداية نقوم بالتخطيط لجميع الملفات والمجلدات التي سنقوم بإنشائها لبرمجة الإضافة.

تركيبة الملفات والمجلدات

لنبدأ أولا بإنشاء مجلد للإضافة يحمل الإسم: ha-views-widget وأظن أنه اختصار جيد لاسم الإضافة واستخدامنا في البداية الحرفين ha كاختصار ل Hsoub Academy :). وبالطبع سنضع هذا المجلد في مجلد إضافات ووردبريس (ونحن نفترض أنك قمت بتنصيب ووردبريس مسبقا) والموجود في المسار wp-content/plugins. بعد ذلك سنقوم بإنشاء ملف php بنفس اسم المجلد وهو ha-views-widget.php وهذا الملف هو الملف الأساسي للإضافة وسيحتوي على الترويسة التي بها معلومات الإضافة والتي تعرفنا عليه في الدرس الأول من هذه السلسلة وبالتالي سيحتوي على هذه الترويسة:

/**
 * Plugin Name: Hsoub Views Widget
 * Plugin URI: http://academy.hsoub.com/
 * Description: إضافة صغيرة تقوم بإضافة مربع جانبي لعرض المقالات الأكثر مشاهدة في موقع ووردبريس مع إمكانية عرض عدد المشاهدات في كل مقالة.
 * Version: 1.4.0
 * Author: Adil Elsaeed
 * Author URI: http://adilelsaeed.com
 * Text Domain: ha-widgets
 * Domain Path: /lang/
 * License: GPL2
 */

بالطبع يمكننا أن نكتب جميع شيفرات php الخاصة بالإضافة في هذا المجلد لكن هذه ليست فكرة جيدة خصوصا إذا أردنا إنشاء إضافة سهلة التطوير والمراجعة، لذلك سنخصص ملفًا لإنشاء ومتابعة عدد المشاهدات وليكن باسم views.php وملف آخر لإنشاء الودجت وليكن باسم widget.php (لاحظ أنه داخل مجلد الإضافة يمكنك تسمية الملفات بأي اسم بدون خوف من التعارض مع ملفات ووردبريس الأخرى)، كما أننا سنحتاج لملف آخر لإنشاء الشيفرة المختصرة وليكن باسم shortcode.php ويمكننا أن نضع هذه الملفات الثلاثة داخل مجلد باسم includes للمحافظة على المجلد الرئيسي للإضافة مرتبًا. 

وبالطبع ما دمنا سنكتب بعض شيفرات html فإننا سنحتاج لتنسيقها من خلال CSS وهذا يعني أننا نحتاج لملف لوضع شيفرات CSS هذه، لذلك سنقوم بإنشاء مجلد أخر باسم css وبداخله ملف widget.css. هذه كل الملفات والمجلدات التي سنحتاج إليها في هذه النسخة الأولى من الإضافة.

الملف الأساسي للإضافة

في الملف الأساسي للإضافة سنقوم أولا بتعريف بعض الثوابت التي سنحتاج إليها لاحقا، حيث سنحتفظ بكل من مسار الإضافة ورابطها URL وكذلك النسخة الحالية للإضافة كثوابت بالصورة التالية:

if ( !defined( 'SDG_PLUGIN_DIR' ) ) {
    define( 'HA_VIEWS_DIR', plugin_dir_path( __FILE__ ) );
}

if ( !defined( 'HA_VIEWS_URL' ) ) {
    define( 'SDG_PLUGIN_URL', plugin_dir_url( __FILE__ ) );
}

if ( !defined( 'HA_VIEWS_VER' ) ) {
    define( 'SDG_PLUGIN_VER', '1.1.0' );
}

لاحظ أننا استخدمنا الدالتين plugin_dir_path و plugin_dir_url اللتين يوفرهما ووردبريس حيث تُرجعان مسار الإضافة ورابطها على التوالي. ثانيا سنقوم بتضمين ملفات php التي أنشأناها سابقا حتى ينفذ ووردبريس الشفرات الموجودة فيها ويتم تضمينها من خلال require_once كالآتي:

// الملف المسؤول عن عدد المشاهدات
require_once HA_VIEWS_DIR . 'includes/views.php';

// الملف المسؤول عن الويدجت
require_once HA_VIEWS_DIR . 'includes/widget.php';

// الملف المسؤول عن الكود المختصر
require_once HA_VIEWS_DIR . 'includes/shortcode.php';

ثالثا وأخيرًا سنقوم بصف ملف الCSS الخاص بتنسيق الويدجت من خلال استخدام الحدث wp_enqueue_scripts ويمكنك معرفة المزيد حول التعامل مع ملفات CSS في ووردبريس بالإطلاع على مقال صف و تسجيل ملفات CSS في ووردبريس. وهذه هي الطريقة التي سنصف بها ملف widget.css:

add_action('wp_enqueue_scripts', 'ha_scripts');
function ha_scripts(){
        wp_enqueue_script( 'sdg-admin',  HA_VIEWS_URL . 'css/widget.css', array(), HA_VIEWS_VER);
}

حفظ وتحديث عدد المشاهدات

لننتقل الآن إلى ملف views.php حيث سنقوم بإضافة عداد المشاهدات لكل مقال من خلال بيانات الميتا الخاصة بالمقال post meta حيث سنقوم بإنشاء الدالة ha_set_post_views والتي تقوم بتحديث عدد المشاهدات للمقال عند زيارته ولنضمن تنفيذها عند كل مقال سنقوم بإضافتها للحدث wp_head والذي يتم تنفيذه في ترويسة Header كل صفحات الموقع. ويتم إضافة الدالة إلى هذا الحدث بالصورة التالية:

add_action('wp_head', 'ha_set_post_views');

أما بالنسبة للدالة نفسها فهذه هي صورتها:

function ha_set_post_views() {
    // إذا لم يكن هذا مقال مفرد (صفحة أو مقال) لا تنفذ أي شيء
    if(!is_singular()){
        return;
    }
    // الوصول إلى بيانات المقال الحالي
    global $post;
    $post_id = $post->ID;
    $count_key = 'ha_post_views_count';
    // استرجاع العدد الحالي للمشاهدات
    $count = get_post_meta($post_id, $count_key, true);
    if($count==''){ // هذا يعني أنه لم يتم إنشاء الميتا الخاص بحفظ عدد المشاهدات حتى الان
    $count = 0;
    delete_post_meta($post_id, $count_key);
    add_post_meta($post_id, $count_key, '0'); // إنشاء الميتا الخاص بحفظ عدد المشاهدات
    }else{ 
        // زيادة عدد المشاهدات بمقدار مشاهدة واحدة
    $count++;
    // حفظ الميتا التي حفظنا فيه عدد المشاهدات
    update_post_meta($post_id, $count_key, $count);
    }
}

لعل التعليقات تشرح الدالة بصورة واضحة لكن دعنا نوضح الأمور أكثر، قمنا في هذه الدالة أولا باستخدام الدالة is_singular والتي تتحقق إن كان المعروض حاليا صفحة مقال مفرد (مقال، صفحة، مقال مخصص) أم لا (صفحة تصنيف مثلا أو أرشيف أو غيرهما) وفي حالة لم يكن المقال مفردًا يتوقف تنفيذ الدالة لأن مهمتها تحديث عدد المشاهدات للمقالات والصفحات والمقالات المخصصة فقط وليس بقية صفحات الموقع (الأرشيفات أو التصنيفات أو غيرها). ثانيا قمنا باستخدام المتغير العام (global) الذي يوفره ووردبريس وهو post$ والذي يحفظ فيه بيانات المقال الحالي (الذي يتم عرضه) حتى نحصل على معرف المقال الحالي من أجل استخدامه في تحديث عدد مشاهداته. ثالثا قمنا باستخدام الدوال update_post_meta، get_post_meta، add_post_meta و delete_post_meta والتي تمكننا من إضافة ميتا مخصصة للمقال واسترجاعها وحذفها وتحديثها على التوالي. وكما تلاحظ قمنا بالتأكد من أن عدد المشاهدات لا يساوي قيمة خالية (غير موجود) وفي حالة أنه غير موجود يتم إنشاؤه وفي حالة أنه موجود يتم زيادته بمقدار واحد وهذه كل مهمة الدالة.

استرجاع عدد المشاهدات

في هذا الملف أيضا (أعني ملف view.php) سنقوم بإنشاء دالة أخرى تقوم باسترجاع عدد المشاهدات للمقال الحالي حتى نستخدمها لاحقا في الشيفرة المختصرة shortcode، وهذه هي الدالة:

function ha_get_post_views(){
    // الوصول إلى بيانات المقال الحالي
    global $post;
    $post_id = $post->ID;
    $count_key = 'ha_post_views_count';
    $count = get_post_meta($post_id, $count_key, true);
    if($count==''){
    delete_post_meta($post_id, $count_key);
    add_post_meta($post_id, $count_key, '0');
    return "0 مشاهدة";
    }
    return $count.' مشاهدة';
}

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

برمجة الشيفرة المختصرة shortcode

في هذه الجزئية سنعتمد على الواجهة البرمجية التي يوفرها ووردبريس حيث سنستخدم الدالة add_shortcode والتي لها الصورة التالية:

<?php add_shortcode( $tag , $func ); ?>

حيث: tag$ هو اسم الشيفرة المختصرة التي سيستخدمها المستخدم في حالتنا هذه سنسميها ha_views وسيقوم المستخدم بإستدعائها بالصورة التالية [ha_views] في المقال أو الصفحة. func$ هي الدالة المسؤولة عن إرجاع محتويات الشيفرة المختصرة أي ما تقوم به الشيفرة المختصرة وفي حالتنا هذه الدالة عبارة عن دالة ترجع عدد المشاهدات للمقال الحالي وهذه هي الشيفرة النهائية في ملف shortcode.php

function ha_views_shortcode( $atts ){
    return ha_get_post_views();
}
add_shortcode( 'ha_views', 'ha_views_shortcode' );

لاحظ أن الدالة ha_views_shortcode تقوم فقط بإرجاع القيمة المرجعة من الدالة ha_get_post_views والتي عرفناها مسبقا في ملف views.php والتي بدورها ترجع عدد المشاهدات للمقال الحالي. ولن نتطرق إلى شرح المزيد من التفاصيل حول الدالة add_shortcode تجنبا للإطالة وربما نخصص لها مقالا مفردا بعد نهاية هذه السلسلة إن شاء الله.

سنكتفي بهذا القدر في هذا الدرس وفي الدرس الأخير من هذه السلسة سنكمل –إن شاء الله- برمجة الإضافة (حيث تبقى فقط برمجة الويدجت الذي يعرض أكثر المقالات مشاهدة)، كما سنلقي بعض الضوء على مجموعة من الأدوات والمواقع المفيدة لمطوري إضافات ووردبريس.