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

ملفات الإضافة

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

مجلد الإضافة سنسمّيه ossostech-difficulty-field، وملف الإضافة الرئيسي سنسمّيه ossostech-difficulty-field.php.

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

إضافة حقل مخصص إلى صفحة تعديل مقالة

نريد إضافة حقل مخصص عبارة عن قائمة منسدلة لاختيار درجة صعوبة المقالة، ونريده أن يظهر طبعًا عند تعديل أو إنشاء مقالة في لوحة التحكم. من أجل ذلك فإننا سنسجّل على الهوك الأكشن (action hook) المسمى add_meta_boxes وسنستدعي فيه الوظيفة add_meta_box(). انظر الرماز:

add_action('add_meta_boxes', 'ossostech_add_custom_difficulty');

function ossostech_add_custom_difficulty() {
 add_meta_box(
      'ossostech_difficulty_id', // Unique ID
      'Post Difficulty', // Box title
      'ossostech_custom_difficulty_content', // Content callback, must be of type callable
      'post' // Post type
  );
}

في السطر الأول سجّلنا الوظيفة ossostech_add_custom_difficulty على الهوك add_meta_boxes. ثم قمنا بعدها مباشرة بتعريف الوظيفة التي تقوم أساسًا باستدعاء الوظيفة add_meta_box مع تمرير المعطيات المطلوبة. أهم معطى هو Content callback حيث سنمرر اسم وظيفة الاستدعاء الراجع والتي سنقوم بإنجازها بعدها مباشرة كما يلي أسفله:

function ossostech_custom_difficulty_content($post) {
   ?>
   <label for="difficulty_field">اختر درجة صعوبة المقالة، سيتمكن القراء من رؤية هذه المعلومة على صفحة المقالة.</label>
   <select name="difficulty_field" id="difficulty_field" class="postbox">
       <option value="1">سهل</option>
       <option value="2">متوسط</option>
       <option value="3">صعب</option>
       <option value="4">محترف</option>
   </select>
   <?php
}

قم بتفعيل الإضافة من صفحة الإضافات ثم أنشئ أو عدّل أيّ مقالة، سوف ترى أن الحقل الجديد قد ظهر أسفل المقالة.

حفظ وجلب البيانات

بعد أن تمكنّا من إدراج عناصر الواجهة الخاصة بنا ضمن المقالة، نريد الآن حفظ وجلب البيانات حسب كل مقالة. ليست هنالك طريقة وحيدة لفعل ذلك، ويمكنك حفظ بياناتك في أي مكان تشاء حتى ولو كان خارج ووردبرس. لكن بما أن حقلنا يتعلّق بمعلومات المقالة، فإن أبرز مكان يمكن الحفظ فيه هو الجدول postmeta. سوف نقوم بعملية الحفظ هذه على الأكشن save_post، انظر الرماز:

add_action('save_post', 'ossostech_difficulty_save');

function ossostech_difficulty_save($post_id) {
  if (array_key_exists('difficulty_field', $_POST)) {
      update_post_meta(
          $post_id,
          '_difficulty_field',
          $_POST['difficulty_field']
      );
  }
}

أصبحنا نعرف هذه الطريقة جيدًا، نسجّل وظيفة على هوك الأكشن، ثم ننجزها مباشرة تحتها وفيها نستدعي إحدى وظائف مكتبة ووردبرس لإتمام ما نسعى إليه. في هذه الحالة، فنحن سجّلنا الهوك save_post، واستدعينا وظيفة ووردبرس update_post_meta، والتي ستضيف أو تعدّل القيمة _difficulty_field في الجدول postmeta. لكي نجرّب ما إذا كانت تعمل، علينا أوّلًا جعل القيمة الصحيحة للحقل مختارة عند تعديل المقالة.

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

function ossostech_custom_difficulty_content($post) {
  $value = get_post_meta($post->ID, '_difficulty_field', true);
   ?>
   <label for="difficulty_field">اختر درجة صعوبة المقالة، سيتمكن القراء من رؤية هذه المعلومة على صفحة المقالة.</label>
   <select name="difficulty_field" id="difficulty_field" class="postbox">
       <option value="1" <?php selected($value, '1'); ?>>سهل</option>
       <option value="2" <?php selected($value, '2'); ?>>متوسط</option>
       <option value="3" <?php selected($value, '3'); ?>>صعب</option>
       <option value="4" <?php selected($value, '4'); ?>>محترف</option>
   </select>
   <?php
}

استعملنا الوظيفة get_post_meta() لجلب قيمة المفتاح _difficulty_field التي قمنا بحفظها سابقًا، ثم استخدمنا الوظيفة selected() التي تقارن بين القيمتين وترد ‘select’ إذا كانتا متساويتين مما يجعل خيار القائمة محدّدًا. انتهينا من تعديلات لوحة التحكم، سنعمل الآن على عرض هذه القيمة، أي مستوى الصعوبة، على صفحة المقالة في المدونة.

تخصيص صفحة المقالة

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

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

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

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

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

add_filter( 'the_title', 'ossostech_show_difficulty_cb');

function ossostech_show_difficulty_cb($value) {
  $difficulty = ['سهل', 'متوسط', 'صعب', 'محترف'];
  if (!is_admin()) {
    return $value . ' <span style="font-size:14px">' . $difficulty[get_post_meta(get_the_ID(), '_difficulty_field', true)] . '</span>';
  }else {
    return $value;
  }
}

تتحقق الوظيفة ossostech_show_difficulty_cb من أننا أوّلا لسنا على لوحة التحكم، فإذا كنّا كذلك فهي ترد العنوان كما هو، وإلا فإنها تضيف عليه قيمة الصعوبة. سبق وأن حفظنا قيمة الصعوبة على شكل رقم من 0 إلى 3، لذلك وضعنا هنا صفيفة difficuly فيها نصوص القيم ثم استدعينا get_post_meta() لجلب القيمة المحفوظة من قاعدة البيانات.

احفظ وادخل المدوّنة وستجد قيمة الصعوبة مكتوبة بخط صغير أمام عنوان كلّ مقالة.

خاتمة

لقد سلّحناك بالمعرفة اللازمة لتمضي وحدك في طريق تطوير إضافات ووردبرس. تذكّر دائمًا أنّ أكبر جهد ستبذله سيكون في تقرير الهوك المناسب لما تبتغيه والبحث عنه في دليل هوكات ووردبرس. أسفله أعطيك رابطَين الأوّل لدليل هوكات الأكشن، والثاني لدليل هوكات الفلتر.

دليل هوكات الأكشن لووردبرس: https://codex.wordpress.org/Plugin_API/Action_Reference

دليل هوكات الفلتر لووردبرس: https://codex.wordpress.org/Plugin_API/Filter_Reference