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

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

• مدير: يملك جميع الخصائص والوظائف الإدارية في الموقع.
• محرر: يمكنه نشر وإدارة مقالات جميع المستخدمين، بما في ذلك مقالاتهم الخاصة.
• مؤلف: يمكنه نشر وإدارة مقالاته الخاصة.
• مساهم: يمكنه كتابة وإدارة مقالاته الخاصة ولكن لا يمكنه نشرها.
• مشترك: يمكنه فقط إدارة نبذته الخاصة.

لِم نستخدم رتب الأعضاء المُخصَّصة؟

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

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

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

وظائف ووردبريس الأساسية

لإدارة الرتب والصلاحية بكفاءة، هناك خمس وظائف بسيطة:

• ()add_role: تتيح لك إضافة رتبة مُخصَّصة.
• ()remove_role: تتيح لك حذف رتبة مُخصَّصة.
• ()add_cap: تتيح لك إضافة صلاحيات جديدة إلى الرتبة.
• ()remove_cap: تتيح لك حذف صلاحيات من الرتبة.
• ()get_role: تعرض لك معلومات عن رتبة ما بالإضافة إلى الصلاحيات المُلحقة بها.

سنستخدم فقط وظيفة ()add_role في هذا المقال عند إنشاء رتبة مُخصَّصة لعميلنا الخيالي.

تحديد صلاحيات رتبة العضو

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

أولًا، نحتاج لتسمية رتبة العضو خاصتنا. ويمكننا تسميتها ببساطة "عميل Client”.

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

• إنشاء المقالات.
• تعديل المقالات.
• تعديل مقالات الآخرين.
• إدارة التصنيفات.
• تعديل الصفحات.

وفي الوقت ذاته لا نريده أن يستطيع فعل الآتي:

• تعديل القوالب.
• إضافة أو حذف الإضافات.
• تحديث البنية الأساسية.

كتابة النص البرمجي

سنضيف هذا النص البرمجي إلى ملف functions.php التابع لقالبنا الفعّال. لذا دعنا نبدأ بإضافة الآتي:

// إضافة رتبة عضو مُخصَّصة
$result = add_role( 'client', __('عميل' ), array( ) );

هكذا أنشأت بإضافة ذلك النص البرمجي رتبة عضو جديدة (يمكنك العثور عليها في القائمة المنسدلة في صفحة أضف عضو جديد). لكن هذه الرتبة لا تمتلك صلاحيات بعد. لذا فالخطوة التالية بالطبع ستكون إضافة صلاحيات تفي بالمتطلبات التي ذكرناها سابقًا. فقط أضف نص المتتالية array إلى النص السابق الذي قمت بإدخاله في ملف functions.php.

// إضافة رتبة عضو مُخصَّصة
$result = add_role( 'client', __('عميل' ), array(
    'read' => true, // تسمح بصلاحية القراءة
    'edit_posts' => true, // تسمح للمستخدم بتعديل مقالاته الخاصة
    'edit_pages' => true, // تسمح للمستخدم بتعديل الصفحات
    'edit_others_posts' => true, // تسمح للمستخدم بتعديل مقالات الآخرين
    'create_posts' => true, // تسمح للمستخدم بإنشاء مقالات جديدة
    'manage_categories' => true, // تسمح للمستخدم بإدارة التصنيفات
    'publish_posts' => true, // تسمح للمستخدم بنشر المقالات، أو ستُحفظ كمسودّات
)
);

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

// إضافة رتبة عضو مُخصَّصة

$result = add_role( 'client', __('عميل' ), array(
    'read' => true, //  تسمح بصلاحية القراءة
    'edit_posts' => true, // تسمح للمستخدم بتعديل مقالاته الخاصة
    'edit_pages' => true, // تسمح للمستخدم بتعديل الصفحات
    'edit_others_posts' => true, // تسمح للمستخدم بتعديل مقالات الآخرين
    'create_posts' => true, // تسمح للمستخدم بإنشاء مقالات جديدة
    'manage_categories' => true, // تسمح للمستخدم بإدارة التصنيفات
    'publish_posts' => true, // تسمح للمستخدم بنشر المقالات، أو ستبقى كمسودّات

    'edit_themes' => false, //  تمنع المستخدم من تعديل القوالب
    'install_plugins' => false, // لا يستطيع المستخدم تنصيب إضافات جديدة
    'update_plugin' => false, // لا يستطيع المستخدم تحديث الإضافات
    'update_core' => false // لا يستطيع المستخدم تحديث البنية الأساسية
)
);

كيف تتأكد أن رتبة العضو قد أضيفت بشكل صحيح

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

كما ترى، الأدوات المتاحة لهذا العضو قد قلت كثيرًا نتيجة للصلاحيات التي تم منحها ومنعها. يمكنك أن ترتاح الآن كمطور/مدير للموقع أنك لن تستقبل رسالة من العميل يقول فيها "لا أعرف ماذا حدث، ولكن فجأة لم يعد موقعي موجوداً".

مترجم بتصرف من مقال How to Create Custom User Roles in WordPress لكاتبه Al Davis.

توجد الكثير من المقالات التّتي تتحدّث عن ترجمة إضافات Plugins ووردبريس، إلّا أنّ القليل منها يتطرّق لتفاصيل عمليّة التّرجمة عندما تكون مهمَّة يوميّة.

مالّذي يحدُث عند تغيير جزء من الشّفرة البرمجيّة Code؟ مالّذي يحدُث عند إضافة سلاسل محارف Strings جديدة؟ مالّذي يحدُث عند تحديث إضافة إلى إصدار جديد؟

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

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

إنشاء إضافة

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

ستعمل الإضافة على كتابة نصّ تحفيزي في التّرويسة Header.

أولًا أنشئ مجلَّدًا جديدًا ضمن مجلَّد الإضافات وسمِّه wp-admin-motivation. ثمّ أنشئ ملفًّا ضمن هذا المجلّد وسمِّه wp-admin-motivation.php. في ما يلي الشّفرة الّتي يجب وضعها في الملفّ:

<?php
/*
Plugin Name: Admin Motivation
Plugin URI: http://danielpataki.com
Description: Shows motivational messages in the admoin bar
Author: Daniel Pataki
Version: 1.0
Author URI: http://danielpataki.com
Text Domain: wp-admin-motivation
*/
function get_motivation_text() {
$motivation = array(
'You are awesome',
'This website is boss',
'You look great today',
'Your earlobes are well rounded, good job!'
);
shuffle( $motivation );
return $motivation[0];
}
add_action( 'admin_notices', 'show_motivation_text' );
function show_motivation_text() {
$text = get_motivation_text();
echo "<p id='wp-admin-motivation'>$text</p>";
}
add_action( 'admin_enqueue_scripts', 'motivation_assets' );
function motivation_assets($hook) {
wp_enqueue_style( 'motivation-styles', plugin_dir_url( __FILE__ ) . 'styles.css' );
}

تخلِط الدّالّة الأولى ()get_motivation_text مصفوفة Array من العبارات التّحفيزيّة باستخدام دالّة shuffle الموجودة في PHP، ثمّ بعد الخلط تختار العبارة الأولى من المصفوفة. يُمكن عدّ دالّة ()get_motivation_text وسيلةً لتوزيع العبارات التّحفيزيّة عشوائيًّا.

نربُط في الخطوة التّاليّة بين دالّة ()show_motivation_text والخطّاف Hook المسمَّى admin_notices. تحصُل دالّة ()show_motivation_text على عبارة تحفيزيّة عشوائيّة عن طريق ()get_motivation_text ثمّ تطبع العبارة داخل فقرة ذات معرّف wp-admin-motivation.

تكون العبارة التّحفيزيّة، بالوصول إلى هذه النّقطة، مرئيّة؛ ولكنّنا سنغيّر موضعها لتكون إلى جانب تبويب خيّارات/مساعدة (Options/help). نستخدم CSS لهذا الغرض.

تكتفي بعض الإضافات بوضع بضعة أسطر CSS في التّرويسة، إلّا أنّ الطّريقة الصّحيحة للتّعامل مع CSS هيّ إدراج الأسطُر ضمن الطّابور Queue؛ وذلك عن طريق ربط دالّة ()motivation_assets بالخطّاف admin_enqueue_scripts وإدراج CSS في الطّابور هناك.

يحدّد النّمط مواضع النّصّ مع أخذ اتّجاه الكتابة من اليمين إلى اليسار Right-to-left, RTL في الحسبان.

#wp-admin-motivation {
float: right;
padding-right: 15px;
padding-top: 7px;
margin: 0;
font-size: 11px;
}

.rtl #wp-admin-motivation {
float: left;
padding-left: 15px;
}

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

تدويل Internationalizing إضافة

يهدف تدويل الإضافات في الأساس إلى جعلها جاهزةً لتُترجَم. يتطلّب التّدويل تغليفَ سلاسل المحارف Strings في دوالّ خاصّة تُسخدَم لتحميل التّرجمات الصّحيحة.

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

تأخذ الدّالّة ()__ معطييْن: النّص الّذي نُريد ترجمته ونطاق النّصّ Text domain. في ما يلي الصّيغة العامّة لاستخدام هذه الدّالّة:

<?php $greeting = __( 'Hello There!', 'text-domain' ); ?>

نحصُل بعد استخدام دالّة ()__ على ترجمة النّصّ إن كانت موجودة، وإلّا فإنّ الدّالّة تُعيد النّصّ الأصليّ. تستخدم الدّالّةُ اللّغةَ الحاليّة لتحديد التّرجمة المطلوبة. يُمكنك الانتقال بين لغات ووردبريس في الإعدادات. تُطبَّق اللّغة المُختارة في الإعدادات على جميع التّرجمات.

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

يجب أن يكون نطاق النّصّ، بالنّسبة للإضافات، مطابقًا لاسم مجلّد الإضافة. يعني هذا، في مثالنا، أنّ نطاق النّصّ يجب أن يكون wp-admin-motivation. كلّ ما ياوجّب علينا فعله، من أجل تدويل الإضافة، هو تغليف سلاسل المحارف بالدّالّة ()__.

$motivation = array(
__( 'You are awesome', 'wp-admin-motivation'),
__( 'This website is boss', 'wp-admin-motivation'),
__( 'You look great today', 'wp-admin-motivation'),
__( 'Your earlobes are well rounded, good job!, 'wp-admin-motivation')'
);

تنفيذ التّرجمات

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

add_action('plugins_loaded', 'wan_load_textdomain');
function wan_load_textdomain() {
load_plugin_textdomain( 'wp-admin-motivation', false, dirname( plugin_basename(__FILE__) ) . '/lang/' );

تعدّ دالة ()load_plugin_textdomain أساسيّةً هنا ويجب أن تُستدعى من دالّة مربوطة بالخطّاف plugins_loaded. أوّل معطى لدالّة ()load_plugin_textdomain هو اسم نطاق النّصّ الّذي تحدّثنا عنه سابقًا، الثّاني مهجور Deprecated، والثّالث هو مجلّّد اللّغة.

ستكون أسماء ملفّات التّرجمات على صيغة plugin_name-locale.mo. حيثُ plugin_name اسم الإضافة وlocale المحلّيّة. سنرى في ما بعد كيفيّة إنشاء هذه التّرجمات. تذكّر، في الوقت الحاليّ، أنّك يجب أن تضع ملفّات التّرجمات هنا.

ملحوظة: المحليّة Locale هي مجموعة من المُعطيات تحدّد لغة المستخدم، دولته، وأيّ تفضيلات خاصّة قد يودّ المستخدم رؤيتها في لغة الواجهة. سنختار ترجمة العبارات التّحفيزيّة الموجودة في الإضافة إلى اللّغة العربيّة؛ لذا سيكون المفّ باسم wp-admin-motivation-ar.mo.

بالوصول إلى هذه النّقطة سيعمل كلّ شيء بالطريقة المرجوَّة، ينقُصُنا فقط إنشاء التّرجمات.

إنشاء التّرجمات

توجد طُرُق متعدّدة لإنشاء ترجمات إلّا أنّ النّتيجة في النّهاية متطابقة. ستحصُل على ملفّين، أحدهما بامتداد po. والآخر بامتداد mo. الأوّل يُمكن للأشخاص قراءته، ويُمكنك فتحه بأيّ محرّر نصوص والتّعديل عليه. أمّا الملفّ ذو الامتداد mo. فهو نتاج تحويل ملفّ po. إلى صيغة مقروءة بالنّسبة للآلة، ذات حجم أصغر بكثير إلّا أنّه لا يمكن للإنسان قراءتها.

في ما يلي مثال على ملفّ PO غير مُترجَم. توجد في أعلى الملفّ معلومات أساسيّة عن التّرجمة، المترجِم والمشروع؛ تليها سلاسل محارف تُمكن ترجمتها متبوعة بأماكن التّرجمات المنتظَرة.

msgid ""
msgstr ""
"Project-Id-Version: WP Admin Motivation 1.0.0\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2015-04-27 13:09+0100\n"
"PO-Revision-Date: 2015-04-27 13:09+0100\n"
"Last-Translator: Daniel Pataki <contact@tastique.org>\n"
"Language-Team: Daniel Pataki <hello@danielpataki.com>\n"
"Language: Hungarian\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"X-Poedit-KeywordsList: __;_e\n"
"X-Poedit-Basepath: .\n"
"X-Poedit-SearchPath-0: ..\n"

#: ../wp-admin-motivation.php:20
msgid "You are awesome"
msgstr ""

#: ../wp-admin-motivation.php:21
msgid "This website is boss"
msgstr ""

#: ../wp-admin-motivation.php:22
msgid "You look great today"
msgstr ""

#: ../wp-admin-motivation.php:23
msgid "Your earlobes are well rounded, good job!"
msgstr ""

الصّيغة العامّة للأسطُر في ملفّ التّرجمة هي التّاليّة:

#: مسار الملفّ الّذي توجد به السّلسلة:رقم السّطر حيثُ توجد السّلسلة
msgid "السّلسة المطلوبة ترجمتها"
msgstr "التّرجمة"

قد تظنّ أنّ كون أماكن تواجد السّلاسل مذكورة مباشرةً بعد ذكر رقم السّطر الّذي تتواجد به يجعل من إنشاء وصيّانة ملفّات التّرجمة أمرًا شاقًّا. لهذا السّبب توجد أدوات مخصًّصة للمساعدة. تُساعد أدوات المدير Admin tools في توليد ملفّات po. للإضافات الموجودة في مستودع ووردبريس. كما يُمكن أيضًا إنشاء ملفّات po. عبر البرنامج الرّائع Poedit.

نزّل Poedi وشغّله؛ انقُر على File (ملفّ) ثمّ New catalog (مسرَد جديد). أدخل المعلومات المطلوبة في النّافذة المنبثقة. لا تهتّم بطقم المحارف (Charset) وصيّغ الجمع (Plural forms)؛ سنكتفي الآن بالمعلومات الأساسيّة.

• ضبط المسار القاعديّ Base path على القيمة /.. (المجلَّد الأب) وإعطاء القيمة . (المجلَّد الحاليّ) لمربَّع المسارات Paths.
• ضبط قيمة المسار القاعديّ Base path على قيمة المجلَّد الحاليّ . وقيمة مربَّع المسارات Paths على المجلَّد الأب /...

يُخبر الخيّار الأوّل Poedit أنّ الشّفرة البرمجيّة للإضافة موجودة في المجلَّد الأب لمجلَّد اللّغة lang؛ أي أنّ البرنامج سيذهب للمجلَّد الأب ويبحث في ذلك المجلَّد. أمّا الخيّار الثّاني فيقول إنّ المجلَّد الّذي يوجد به الملفّ الحاليّ هو مجلَّد اللّغة؛ وأنّ الملفّات الّتي يجب التّحقّق منها توجد في المجلَّد الأعلى، لذلك استخدمنا /.. في مربَّع المسارات Paths. سنعتمد في هذا الدّرس الخيّار الثّانيّ.

الخطوة التّاليّة هي ضبط الكلمات المفتاحيّة في تبويب Sources keywords (الكلمات المفتاحيّة للمصادر). نحدّد في هذا التّبويب أسماء دوالّ التّرجمة المستخدَمة. في المثال هنا نحتاج فقط لإضافة دالّة __. في أغلب الحالات ستحتاج لإدراج دالتّيْن إلى ثلاث؛ راجع التّرجمة المتقدّمة أدناه.

لم يبق إلّا الموافقة على البيانات المُدخَلة. سيطلُب منك البرنامج مكان حفظ الملفّ؛ اختر مسار المجلَّد lang إن كنت اعتمدت الخيّار الثّاني في إعداد المسارات أعلاه. سيبحث Poedit في ملفّات الإضافة ويعثُر على السّلاسل الجاهزة للتّرجمة.

ستظهر العبارات التّحفيزيّة باللّغة العربيّة؛ بعد وضع ملفّ اللّغة في مجلَّد اللّغات ضمن الإضافة وتفعيل اللّغة العربيّة في إعدادات ووردبريس.

صيّانة التّرجمات

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

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

تُشبه ملفّات POT ملفّات PO؛ إلّا أنّها لا تحتوي على أيّ ترجمات، فكلّ ما تحتويه هو الجمل والعبارات الجاهزة للتّرجمة؛ أيّ أنّها قوالب فقط. تكون التّرجمات سهلة ما دام ملفّ القالب محدَّثًا ويحوي رقم السّطر الصّحيح لكلّ سلسلة محارف.

إذا احتجت إلى تحديث ملفّ لغة فكلّ ما عليك فعله هو فتحه عن طريق Poedit ثمّ النّقر على أيقونة التّحديث Update وسيُشعرك البرنامج بالسّلاسل الجديدة والمُعدَّلة ويمكنك بعدها التّعديل عليها.

قبول التّرجمات

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

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

أستضيف كلّ مستودعاتي على Github وهو ما يسهّل على المترجمين إرسال ملفّات التّرجمة لي باستخدام طلبات السّحب Pull requests. كلّ ما عليّ فعله بعدها هو الضّغط على زرّ وإنشاء إصدار جديد من مستودع ووردبريس.

التّرجمات المتقدّمة

تعرّفنا في ما سبق على طريقة ترجمة سلاسل محارف قاعديّة عن طريق دالّة ()__. توجد 14 دالة ترجمة في ووردبريس يُمكن استخدامها لتدقيق ضبط ترجماتك. على الأرجح لن تحتاج إلّا إلى 3 أو 4 منها. نبدأ بالأشهر من بينها.

1- ()__

هذه هي الدّالّة الأساسيّة للتّرجمة. تأخذ سلسلة محارف وتُعيد التّرجمة إن كانت موجودة.

2- ()e_

نفس عمل الدّالّة السّابقة تقريبًا، إلّا أنّها بدلًا من إرجاع التّرجمة تعرضها مباشرةً.

3- ()n_

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

<?php
$messages = get_message_count();
// الاستعمال المبَسَّط: لا تُظهر الدّالة العدد الفعليّ
$text = _n( 'You have one message', 'You have lots of messages', $messages, 'my-message-app' );
// في طريقة الاستعمال هذه نُظهر العدد الفعليّ للرّسائل
$text = sprintf( _n( 'You have one message', 'You have %s messages', $messages, 'my-message-app' ), $messages )
?>

في هذا المثال نحصُل على عدد الرّسائل ضمن متغيّر messages ثمّ نستخدم هذا المتغيّر في دالّة ()n_ الّتي تعتمد على قيمة المتغيّر لاختيّار سلسلة المحارف الّتي تعرضها (بصيغة المفرد أو الجمع). في طريقة الاستعمال المبسَّط للدّالة لا يظهر عدد الرّسائل ضمن سلسلة المحارف المعروضة حيثُ توجد عبارتان، الأولى للعرض إذا كانت قيمة messages مفردة وتُعرَض الثّانيّة في حالة الجمع. إذا أردنا عرض العدد نستخدم عبارة s% في المكان الّذي نُريد أن يُعرض فيه العدد.

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

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

لأخذ هذه التّغييرات في الحسبان عند إنشاء ملفّ التّرجمة نُخبر Poedit بعدد صيّغ الجمع الموجودة لدينا، بالنّسبة للعربيّة:

nplurals=6; plural=n==0 ? 0 : n==1 ? 1 : n==2 ? 2 : n%100>=3 && n%100<=10 ? 3 : n%100>=11 ? 4 : 5;

قبل البدء في البحث عن سلاسل المحارف نُضيف الدّالة n_ في تبويب Sources keywords (الكلمات المفتاحيّة للمصادر) حتى يتعرّف عليها البرنامج؛ إضافةً للدّالّة __ السّابقة.

ملحوظة: من المهمّ جدًّا كتابة الدّالّة بالصّيغة n:1,2_ الّتي تعني أنّ المُعطى الأوّل (الرّقم 1) يعبّر عن صيغة المفرد وأنّ المعطى الثّاني لصيغة الجمع.

يمكننا الآن إنشاء ملفّ اللّغة وترجمة العبارات الواردة فيه مع أخذ الجمع بالحسبان.

4- ()x_

تهدف هذه الدّالّة إلى الوقاية من الخلط بين الكلمات مختلفة المعنى الّتي تُكتَب بنفس الطّريقة. مثلًا إذا كنت تستخدم كلمة pair بمعنى “زوج أشخاص” وبمعنى “ربط بجهاز بلوتوث” فيُمكن أن يشتبه المعنى. لمنع الاشتباه ولمساعدة المترجم على اختيّار العبارة المناسبة في لغته استخدم دالّة ()x_.

_x( 'Pair', 'A pair of people', 'my-plugin-textomaind' );
_x( 'Pair', 'As in: pairing devices', 'my-plugin-textomaind' );

5- ()ex و ()nx

يُشبه عمل هاتيْن الدّالتيْن عمل دالّة ()x_ أعلاه. الفرق هو أنّ ()ex_ تعرض النّتيجة مباشرةً في حين أنّ nx_ تُضيف إمكانيّة تحديد صيغة للجمع.

تخليص Escaping التّرجمات

تتيح الدّوال السّتّ التّاليّة إمكانيّة تخليص التّرجمة من أجل الاستخدام الآمن في نصوص HTML (الثّلاث الأخيرة) أو خاصيّاته attributes (الثّلاث الأولى).

• ()esc_attr__
• ()esc_attr_e
• ()esc_attr_x
• ()esc_html__
• ()esc_html_e
• ()esc_html_x

ترجمات Noop

تسجّل دوالّ Noop سلاسل المحارف بصيغة الجمع في ملفّ POT دون أن تترجمها. يعود السّبب في ذلك إلى أنّ العدد غير معروف سلفًا، وهو ما يعني أنّنا سنحتاج لدالّة أخرى للحصول على العدد وبالتّالي اختيّار صيغة المعدود (الجمع). لهذا السّبب نستخدم دالّة Noop ثمّ نترجم القيمة الحقيقيّة لاحقًا بعد الحصول على العدد. راجع المقال التّالي للمزيد.

تستخدم الدّوال التّاليّة لهذا الغرض:

• ()n_noop_
• ()nx_noop_
• ()translate_nooped_plural

ترجمة Javascript

ربّما ننساءل ماذا عن سلاسل المحارف الموجودة ضمن شفرة Javascript؟ يقدّم ووردبريس الحلّ عبر دالّة ()wp_localize_script. تأخذ هذه الدّالّة ثلاثة معطيات: مِقبض Handle (معرّف) السّكريبت الّذي نُريد ترجمته، اسم كائن Object للاستخدام داخل السّكريبت ومصفوفة التّرجمة. في ما يلي مثال على ترجمة سلاسل محارف ضمن Javascript:

add_action( 'admin_enqueue_scripts', 'motivation_assets' );
function motivation_assets($hook) {
wp_enqueue_script( 'motivation-scripts', plugin_dir_url( __FILE__ ) . 'scripts' );
wp_localize_script( 'motivation-scripts', 'wma', array(
'section_title' => __( 'Today's motivation', 'wp-admin-motivation' )
));
}

بعد إضافة التّرجمات يُمكنك استخدامها في ملفّ Javascript المُسجَّل. يجب عليك استخدام اسم الكائن ومفاتيح مصفوفة التّرجمة:

jQuery.html( "<h2>" + wma.section_title + "</h2>" );

خاتمة

يستخدم ملايين الأشخاص لغاتِهم للتّعامل مع ووردبريس، فلمَ لا تساعدهم في عمل نفس الشّيء مع منتجاتك؟ فلا جعل الإضافات جاهزة للتّرجمة أمر صعب ولا صيّانتها تُمثّل كبير إزعاج.

يُساعد تجهيز سلاسل المحارف للتّرجمة وإنشاء ملفّات po وmo الجميع كما أنّه يزيد من جودة المنتج.

ترجمة بتصرّف لمقال Everything You Need to Know About Translating WordPress Plugins لكاتبه Daniel Pataki.

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

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

قاعدة عامة: إياك أن تعدّل في البنية الأساسية لووردبريس (WordPress Core)

ربما قد تكون سمعت تلك العبارة الخالدة مرارًا من متمرسي ووردبريس: “لا تعدّل في البنية الأساسية" “Don’t hack core". ما يعنيه هذا هو أنك يجب ألا تلمس الملفات الأساسية، وهي الملفات المسؤولة عن عمل ووردبريس.

لم هذا؟ حسنًا، هناك العديد من الأسباب، لكن دعنا نكتف باثنين من أهمها هنا:

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

إذًا الآن تعرف لم لا يجب تعديل البنية الأساسية، دعنا نر ما المتاح تعديله بأمان.

بنية ملفات ووردبريس

هذه لقطة توضح بنية ملفات موقع ووردبريس نموذجي.

سترى أن هناك ثلاث مراحل عليا من المجلدات ومجموعة من الملفات.

المجلدات المسماة wp-admin وwp-include محظورة، يجب ألا تلمس شيئًا هناك. أما مجلد wp-content فإنه يحوي القوالب، الإضافات، وأي صورة أو مستند نصي رفعتها على الموقع. ويمكنك أن تجري تعديلات على قالبك الخاص عن طريق ملف functions.php.

وبالنسبة لملفات المستوى الأعلى، فالملف الوحيد المسموح بالتعديل فيه هو ملف wp-config.php. سنغوص في بعض الأمثلة لكيفية تعديل كلا الملفين لاحقًا، لكن دعنا نتحدث عن بعض من أفضل الممارسات قبل أن نفعل.

أفضل الممارسات لتعديل ملفات ووردبرس

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

المظهر > المحرر أو Appearance > Editor

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

1. هذا المحرر ليس محررًا نصّيّا برمجيًا كامل الوظائف، ويمكن بسهولة ارتكاب أخطاء تنتج عنها "شاشة الموت البيضاء".
2. حين تضغط على زر الحفظ، ليس هناك زر للرجوع. ليس هناك إمكانية لإعادة المحاولة. معظم محررات النصوص البرمجية الجيدة تُتيح لك إمكانية التّراجع عن التغييرات التي أجريتها في حال لم تعمل كما يجب.

إذًا، ما هو البديل؟ حسنًا، إذا أردت استخدام محرر نص برمجي، فستحتاج دراية بـ FTP .

FTP هو اختصار لـ File Transfer Protocol بروتوكول نقل الملفات. ولنشرح ذلك بأنه عبارة عن نقل الملفات من جهازك إلى خادم الويب الذي يوجد عليه موقعك. ستحتاج للاتصال بموقعك عن طريق عميل FTP، ثم تحمّل نسخة من الملف الذي تريد تغييره، أجرِ التغييرات ثم ارفعه إلى الخادم، وسيحل محل النسخة القديمة في الخادم.

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

حان الوقت لتعديل بعض ملفات ووردبريس

سنجري بعض التعديلات البسيطة على ملفين wp-config.php وfunctions.php وهي ملفات غير تابعة للقالب، غالبًا ما ستحتاج إلى تعديلها.

تعديل ملف wp-config.php

ملف wp-config.php هو واحد من أهم الملفات في موقع ووردبريس الخاص بك. ولا يأتي مع النسخة الأساسية لووردبريس؛ إذ أنك تنصب ملفًا يُدعى wp-config-sample.php. ويُنشأ ملف wp-config.php أثناء عملية التنصيب (تحديدًا عند إدخال معلومات قاعدة البيانات الخاصة بموقعك)، أو يمكنك ببساطة إعادة تسمية ملف wp-config-sample إلى wp-config وإضافة معلومات قاعدة البيانات إلى الملف.

ستجد كلّا الملفين في الجذر الأساسي لمسار الويب. إذا أتممت عملية التنصيب (لقطة لها بالأسفل)، بما في ذلك إعدادات قاعدة البيانات الخاصة بالموقع، فإنك بالفعل قد أنشأت ملف wp-config.php. الآن، دعنا نفتحه في محرر النص البرمجي المفضل لديك لنجري بعض التغييرات.

مثال نص برمجي مفيد: تعطيل التحديثات التلقائية

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

/* تعطيل تحديثات ووردبرس الة */
define( 'WP_AUTO_UPDATE_CORE', false );

عندما أضيف نصًا برمجيًا إلى ملف wp-config، فإنني أتأكد دومًا من وضعه في مكان يسهل الرجوع إليه عند الحاجة. انظر إلى السطر 85 في ملف wp-config.php (من السهل الوصول إليه باستخدام محرر النص البرمجي)، ستجد هذه الجملة:

/* That's all, stop editing! Happy blogging. */

بمعنى:

/* هذا هو المطلوب! توقف عن التعديل. نتمنى لك التوفيق في موقعك! */

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

تعديل ملف functions.php

ملف functions.php يسمح لك بتعديل وظائف ووردبريس. إذ يعمل هذا الملف كإضافة، فينشء خصائص ومزايا جديدة في موقع ووردبريس الخاص بك.

وعادة ما تجد الملف موجودًا في مجلد القالب الخاص بك في المسار /wp-content/themes/yourthemename/ (حيث yourthemename هو اسم القالب). إذا لم تمتلك واحدًا، يمكنك بسهولة إنشاءه؛ فقط تأكد من أنك تضعه في القالب المٌفعّل.

إذا بدأت بملف جديد، فستحتاج لبداية نص PHP مستخدمًا php?>. وعلى عكس ملف php التقليدي، فإنك لن تحتاج لإغلاق النص البرمجي (في الواقع، تقل احتمالية الأخطاء إذا تركته مفتوحًا).

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

مثال نص برمجي مفيد: إضافة دعم المُصغّرات thumbnails

إذا كان قالبك لا يدعم المُصغّرات، فيمكنك إضافة النص البرمجي التالي إلى ملف functions.php الخاص بك:

add_theme_support( 'post-thumbnails');

لاستخدامه في قالبك، فقط أضف هذا السطر من الكود إلى الحلقة loop حيث تريد للمُصغرات أن تظهر:

<?php the_post_thumbnail(); ?>

مثال نص برمجي مفيد: تخصيص طول الاقتباسات

الطول الافتراضي للاقتباسات في ووردبريس هو 55 كلمة، ولكن يمكنك تعيين طول الاقتباس حسبما تريد عن طريق إضافة ذلك النص البرمجي إلى ملف functions.php الخاص بك:

//وظيفة تخصيص طول المقتبس
custom_excerpt_length($length) { return 20; }

add_filter('excerpt_length', 'custom_excerpt_length');

فقط كل ما تحتاجه تغيير رقم "20” إلى عدد الكلمات التي تريدها.

الخاتمة

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

مُترجم بتصرف من مقالة How to Edit Your WordPress Website Without Hacking Core Files لصاحبها Tom Ewer.

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

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

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

• إحصاء عدد المشاهدات لكل مقال.
• توفير شيفرة مختصرة 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 تجنبا للإطالة وربما نخصص لها مقالا مفردا بعد نهاية هذه السلسلة إن شاء الله.

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

تعرّفنا في الدرس الأول -من سلسلة الدروس هذه المُكوّنة من درسين- على الأنواع الثّلاثة للمحتوى المُخصّص Custom Content التي نستطيع إنشاءها باستخدام ووردبريس وتحدّثنا عن فائدة كلّ واحدٍ منها.

هذه الأنواع هي:

• المنشورات المُخصّصة Custom posts.
• أنواع التّصنيفات المُخصّصة Custom taxonomies.
• الحقول المُخصّصة Custom fields.

نظرنا بالتفصيل في ذلك الدّرس إلى أنواع المنشورات المُخصّصة custom post types موضّحين كيفيّة إنشائها وعرضها على موقعنا.
سننتقل في الدرس الثاني والأخير من هذه السلسلة إلى أنواع التّصنيفات المُخصّصة Custom taxonomies والحقول المُخصّصة Custom fields، لنتعلّم كيفية إنشائها سواءً باستخدام إضافة plugin أو عبر برمجتها بأنفسنا، وكيفيّة عرضها على واجهة موقعنا، فلنبدأ بأنواع التّصنيفات المُخصّصة.

إنشاء Taxonomy مُخصّص

كما وجدنا مع أنواع المنشورات المُخصّصة بإمكانك أن تستخدم إضافة لإنشاء Custom Taxonomy أو تقوم ببرمجتها بنفسك في قالبك Theme أو حتى بشكلٍ أفضل أن تجعلها على شكل إضافة، إنّ الإضافات التي تستطيع استخدامها لفعل هذا هي نفسها التي استخدمناها لأنواع المنشورات المُخصّصة:

• تزوّدك CustomPress بواجهة لإنشاء أنواع المنشورات المُخصّصة، التّصنيفات والحقول المُخصّصة وهي سهلة الاستخدام كثيرًا، إن كنت تريد إنشاء العديد من أنواع المحتوى المُخصّص ستوفر عليك هذه الإضافة عناء تثبيت أكثر من إضافة.
• إنّ إضافة Custom Post Type UI هي أكثر الإضافات المجانيّة انتشارًا لإضافة أنواع المنشورات المُخصّصة على مستودع الإضافات، فهي تسمح لك بإضافة أنواع المنشورات المُخصّصة وأنواع التّصنيفات ولكن لا تسمح بإنشاء الحقول المُخصّصة، واجهتها ليست سهلة الاستخدام تمامًا مثل واجهة CustomPress، مع المزيد من المصطلحات التقنيّة لكي تتمكّن من فهمها، ولكنّها تقوم بعملها. ولكن إن كنتَ واثقًا من نفسك بما فيه الكفاية لكي تُبرمج Custom taxonomies بنفسك ، فها هي طريقة فعل ذلك.

1. برمجة Custom taxonomy

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

تستطيع إمّا إضافة الشّيفرة إلى ملف دالّات قالبك Theme’s Functions file أو إنشاء إضافة منفصلة، من الأفضل إنشاء إضافة لأنّك لو قمت بتغيير قالبك مستقبلًا فلن تخسر نوع تصنيفاتك Taxonomy، وهذا ما سنقوم به هنا. ابدأ بإنشاء ملف فارغ يُدعى taxonomies.php واحفظه إلى مجلّد plugins الموجود داخل مجلّد wp-content.
افتح الآن ملفك باستخدام مُحرّر شيفرة Code Editor وأضف إليه ما يلي:

<?php
/*Plugin Name: Create Product Category Taxonomy
Description: This plugin registers the 'product category' taxonomy and applies it to the 'product' post type.
Version: 1.0
License: GPLv2
*/
?>

تُخبر هذه الشّيفرة ووردبريس باسم إضافتك وتزوّده بوصف description والذي ستراه عندما تقوم بتفعيل إضافتك لاحقًا.
الآن أضف ما يلي تحت السطر الذي يحتوي على */ وفوق السطر الذي يحتوي على ?> :

function wpmudev_register_taxonomy() {

}
add_action( 'init', 'wpmudev_register_taxonomy' );

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

    // set up labels
$labels = array(
'name' => 'Product Categories',
'singular_name' => 'Product Category',
'search_items' => 'Search Product Categories',
'all_items' => 'All Product Categories',
'edit_item' => 'Edit Product Category',
'update_item' => 'Update Product Category',
'add_new_item' => 'Add New Product Category',
'new_item_name' => 'New Product Category',
'menu_name' => 'Product Categories'
);
// register taxonomy
register_taxonomy( 'productcat', 'product', array(
'hierarchical' => true,
'labels' => $labels,
'query_var' => true,
'show_admin_column' => true
) );

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

• اسم نوع التّصنيفات، productcat، تحتاجه لكي يعمل نوع تصنيفاتك.
• نوع المنشورات الذي ستُطبِّق عليه نوع تصنيفاتك، قمنا هنا بتحديده كمنتج product ولكن بإمكانك استخدام نوع تصنيفاتك مع أكثر من نوع منشورات (بما فيها أنواع المنشورات المُضَمّنة مثل المنشورات posts والصفحات pages والمرفقات attachments) بتضمينها كلّها في مصفوفة array.
• Hierarchical: قم بتعيينه إلى true لكي يسلك نوع تصنيفاتك سلوك تصنيفات categories ويكون بشكلٍ شجري hierarchical، إن لم ترغب أن يكون بشكل شجريًا مثل الوسوم tags فقم بتعيينه إلى false.
• Labels: تُخبر هنا ووردبريس أن يستخدم الـ Labels المُعرّفة مُسبقًا.
• query_var: يعطيك تعيينه إلى true مرونة أكثر إن كنت ترغب بكتابة استعلام مُخصّص custom query لإيجاد المنتجات التي توافق شرط taxonomy term معيّن.
• show_admin_column: يعني تعيينه إلى true أنّك تعرض قائمة من منتجاتك في لوحة تحكم ووردبريس، سيملك نوع التّصنيفات عمودًا من أجلك لكي تعرف أيّة شروط taxonomy تنطبق على أيّة منتجات، سنرى كيف يبدو هذا قريبًا.

الآن احفظ ملفك ، ستبدو كامل الإضافة كما يلي:

<?php
/*Plugin Name: Create Product Category Taxonomy
Description: This plugin registers the 'product category' taxonomy and applies it to the 'product' post type.
Version: 1.0
License: GPLv2
*/

// register two taxonomies to go with the post type
function wpmudev_register_taxonomy() {
// set up labels
$labels = array(
'name' => 'Product Categories',
'singular_name' => 'Product Category',
'search_items' => 'Search Product Categories',
'all_items' => 'All Product Categories',
'edit_item' => 'Edit Product Category',
'update_item' => 'Update Product Category',
'add_new_item' => 'Add New Product Category',
'new_item_name' => 'New Product Category',
'menu_name' => 'Product Categories'
);
// register taxonomy
register_taxonomy( 'productcat', 'product', array(
'hierarchical' => true,
'labels' => $labels,
'query_var' => true,
'show_admin_column' => true
) );
}
add_action( 'init', 'wpmudev_register_taxonomy' );
?>

الآن وقد اكتملت إضافتك تحتاج لتفعيلها، في لوحة تحكّم ووردبريس اذهب إلى: Plugins -> Installed Plugins لترى إضافتك معروضة:

اضغط على رابط التّفعيل Activate لكي تقوم بتفعيل إضافتك، سترى الآن أنّه عندما تضغط على المنتجات Products في قائمة لوحة التّحكّم سيتمّ عرض النّوع الجّديد للتّصنيف:

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

عرض أرشيف شروط taxonomy على موقعك

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

1. تحديث الروابط الدائمة Permalinks

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

1. من لوحة تحكّم ووردبريس اذهب إلى: Settings > Permalinks.
2. تأكد من أنّه تم اختيار post name.
3. اضغط على زر حفظ التغييرات Save Changes.

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

2. إضافة أرشيف شرط taxonomy إلى قائمة التصفح Navigation Menu

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

1. من لوحة تحكم ووردبريس اذهب إلى: Appearance > Menus.
2. سترى على يسار الشاشة قائمة أنواع المحتوى التي تستطيع إضافتها إلى قائمتك، ومنها تصنيفات المنتجات Product Categories (إن لم تكن ظاهرة اضغط على نافذة خيارات الشّاشة Screen Options الموجودة بأعلى وأيمن الشاشة ثم ضع صح في خانة التأشير Checkbox عند Product Categories).
3. اضغط على Product Categories لكي تكشف كل الشروط التي أضفتها.
4. أضف كلّ واحد منها إلى القائمة واسحبها إلى المكان الذي تريده.
5. اضغط على حفظ القائمة Save Menu لحفظ التّغييرات، لا تفوّت هذه الخطوة.

في هذه الصّورة أضفنا تصنيف منتج وأدخلناه تحت رابط المنتجات Products التي قمنا بإنشائها في الدرس الأول من هذه السّلسلة:

عندما تذهب الآن إلى واجهة موقعك وتضغط على روابط أرشيف شروط نوع تصنيفاتك سترى قائمة من المنتجات التي توافق ذلك الشرط :

3. استخدام ملفات قالب Template لأرشيف الشروط

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

عندما يعرض ووردبريس صفحة الأرشيف لشرط نوع التّصنيفات، سيبحث خلال ملفات قالبك باستخدام القالب الشجري template hierarchy ويستخدم أول ملف يصادفه:

1. ملف لعرض الأرشيف بالنسبة لشرط نوع تصنيفات مُحدّد: بالنسبة للشرط الذي يُوافق المنتجات المتميّزة featured يُدعى هذا الملف taxonomy-productcat-featured-products.php، لاحظ أنّنا نستخدم اسم نوع التّصنيف متبوعًا بلاحقة slug لشرط نوع التّصنيف لإنشاء اسم الملف.
2. ملف لعرض أرشيف لشرط نوع التّصنيف لكل الشّروط في taxonomy، يُدعى taxonomy-productcat.php.
3. ملف لعرض أرشيف لكل أنواع التّصنيفات المُخصّصة، يُدعى taxonomy.php.
4. ملف لعرض كل أنواع الأرشيف يُدعى archive.php.
5. ملف عام لكل المحتوى يُدعى index.php.

يعمل ووردبريس من خلال هذه القائمة ويستخدم أول ملف يجده، يعمل موقعنا على قالب the twenty fifteen theme والذي يملك ملف يُدعى archive.php لذا يستخدم هذا الملف.

إن أردت عرض أرشيف نوع تصنيفاتك بشكلٍ مُختلف عن الأرشيف العادي (على سبيل المثال إزالة المقتطفات excerpts وإضافة صور مميّزة featured images) تستطيع إنشاء نسخة من الملف archive.php في قالبك وتقوم بتسميته taxonomy.php ومن ثمّ تحريره لعرض أرشيفك بالطريقة التي ترغب بها، ولكن حتى لو لم تقم بذلك فالأمر الجيّد هنا أنّ ووردبريس سيجد دومًا ملف قالب template file مناسب لعرض أرشيف لشرطك.

فلننتقل الآن إلى النوع الأخير من المحتوى المُخصّص وهو الحقول المُخصّصة.

إنشاء حقول مُخصّصة

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

نجد من بين أفضل الإضافات لإنشاء حقول مُخصّصة:

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

إن لم تكن ترغب باستخدام إضافة، تستطيع إنشاء حقول مُخصّصة باستخدام لوحة تحكّم ووردبريس، وهذه هي الطريقة:

1. إنشاء حقول مُخصّصة باستخدام شاشات لوحة التّحكّم الافتراضية

إن توجّهت إلى شاشة تعديل المنشورات لواحد من منشوراتك (أو كنت تقوم بإنشاء منشور جديد) فقد ترى مربّع بيانات وصفيّة metabox للحقول المُخصّصة تحت جزء التحرير الرئيسي، تستطيع عرضها إن لم تكن ظاهرة بفتح نافذة إعدادات الشّاشة Screen Options الموجودة بأعلى ويمين الشاشة، اضغط على مربّع Custom Fields، أغلق النافذة وسترى مربّع البيانات الوصفيّة metabox قد ظهر أسفل محتواك:

لإضافة حقل مُخصّص تستطيع إمّا اختيار مفتاح موجود مُسبقًا من قائمة منسدلة على الجهة اليسرى أو أضف واحدًا جديدًا بالضّغط على رابط Enter New وكتابته فيها، بعد ذلك تكتب القيمة لحقلك المُخصّص.

قمنا هنا بإنشاء حقل مُخصّص لمنتج أضفناه، والذي مفتاحه هو السّعر Price وقيمته 15.00:

بعد أن قمت بإضافة المفتاح والقيمة يجب أن تضغط على زر إضافة حقل مُخصّص Add Custom Field لحفظ حقلك المُخصّص، فلن يقوم ووردبريس بحفظه عندما تضغط زر نشر Publish لمنشورك. تستطيع إضافة العدد الذي تحتاجه من الحقول المُخصّصة لمنشوراتك لتخزين بياناتك، لا تنسَ أن تحفظ منشورك بعد أن قمت بحفظ حقولك المُخصّصة.

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

عرض الحقول المُخصّصة على موقعك

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

لذا ستحتاج لإضافة وسم قالب template tag لفعل هذا.

إنّ وسم القالب هو عبارة عن نوع دالّة والتي تُدخلها إلى ملف قالب theme file لتُخبر ووردبريس أن يعرض بعض البيانات.

يعطينا ووردبريس خيارًا من وسوم القالب لعرض حقولنا المُخصّصة:

• ()the_meta يعرض كل أنواع الحقول المُخصّصة لمنشور ما، نستخدمه داخل حلقة loop وسيعرض كل مفاتيح وقيم الحقول المُخصّصة بدون أن يُعطينا قدرة على التّحكّم بذلك.
• ()get_post_meta يعطينا تحكّمًا أكثر، يملك مُعاملات parameters نستطيع استخدامها لتحديد أيّ الحقول المُخصّصة نريد أن نحصل عليها وإذا ما كنّا نرغب فقط باسترجاع قيمة واحدة إن كان منشورنا يملك عدّة حقول مُخصّصة بنفس المفتاح، لا يقوم فعليًا بعرض حقولنا المُخصّصة بل يقوم فقط بجلبها، ولكي نعرضها يجب أن نستخدم ()echo get_post_meta.
• ()get_post_custom_values يسمح لنا بجلب كل القيم للحقول المُخصّصة والتي تملك نفس المفتاح الذي نقوم بتحديده، وهي تحتاج أيضًا لاستخدام الأمر echo قبل أن تعرض أي شيء.

تقوم بشكل طبيعي بإضافة واحدة منها إلى ملف القالب template file داخل قالبك والذي يقوم بعرض منشورات مفردة أو أرشيف داخل حلقة loop، وإن أردت بشكلٍ بديل أن تعرض حقول مُخصّصة لعدد من المنشورات في مكان آخر من الموقع تستطيع استخدام ()get_post_meta خارج الحلقة. لن نقلق الآن حيال هذا، بل سننظر بدلًا من ذلك إلى كيفيّة فعل هذا داخل الحلقة.

إن لم تُصادف الحلقة loop من قبل، فهي كتلة من الشيفرة block of code في داخل template files لقالبك والتي تقوم بجلب العنوان والمحتوى لكل منشور من قاعدة البيانات وتقوم بعرضه.

الخطوة الأولى هي أن تفتح ملف single.php في مُحرّر شيفرة code editor وتجد الحلقة، تبدأ الحلقة بسطر من الشيفرة مشابه لهذا:

while ( have_posts() ) : the_post();

ستجد تحت هذا السطر وسوم القالب كـ ()the_title و ()the_content، تحتاج لإضافة حقولك المُخصّصة بينها، سنقوم بإضافة حقولنا المُخصّصة فورًا بعد العنوان.

ملاحظة: إن كنت تعمل على قالب twenty fifteen ستجد أنّه لا يملك الحلقة في ملف single.php، بدلًا من ذلك يقوم بتضمين ملف يُدعى content.php، لتحرير وعرض نوع منشورات المنتج قم بإنشاء نسخة من ملف content.php وقم بتسميتها content-product.php وحرّرها.

لعرض كلّ الحقول المُخصّصة للمنشور أدخل الشيفرة التالية:

the_meta();

احفظ ملف قالبك.

عندما نزور الآن واجهة موقعنا نستطيع رؤية الحقل المُخصّص الذي أضفناه لمنتجنا:

يتم عرضه بشكل افتراضي بطريقة قائمة نقطية bulleted list، تستطيع تنسيق هذه القائمة كما تريد باستخدام CSS.

ولكن ماذا لو أردنا أن نتحكّم أكثر بالطّريقة التي يتمّ بها عرض الحقل المُخصّص؟ نستطيع استخدام ()get_post_meta.

افتح ملف single.php مرة أخرى وقم بإيجاد الشيفرة التي أضفتها ، قم باستبدالها بما يلي:

$price = get_post_meta( get_the_ID(), 'Price', true );
if( ! empty( $price ) ) {
echo '<p>Price: $' . $price . '</p>';
}

دعنا نلقي نظرة على ما تفعله هذه الشّيفرة:

1. في البداية تحصل على الحقل المُخصّص لهذا المنشور الذي يملك المفتاح Price وتقوم بتخزينه في متغير variable يُدعى price$.
2. تتحقق أنّ الحقل المُخصّص ليس فارغًا.
3. إن لم يكن كذلك تقوم بعرض السّعر price داخل وسم فقرة paragraph tag مع بعض النّص قبله.

الآن احفظ الملف وألقِ نظرة على صفحتك ، تبدو الصّفحة لدينا هكذا:

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

ملاحظة: لأننا استخدمنا قالب Twenty Fifteen في هذا المثال فلم نقم بتحرير الملف مباشرة داخل القالب بل قمنا بدلًا من ذلك بإنشاء قالب ابن Child Theme وقمنا بعمل ملفات جديدة، يعني هذا أنّه عندما نقوم بتحديث قالب Twenty Fifteen فلن نخسر الملفات الجديدة التي أضفناها، إن كنت ستقوم بنفس الشيء ننصحك باتباع هذا الدّليل الرائع لإنشاء قوالب أبناء child themes.

الخلاصة

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

تعلّمنا في هذا الدرس كيفيّة تسجيل custom taxonomy وعرض صفحات أرشيفه على موقعنا، وكيفية إنشاء حقول مُخصّصة وعرضها على الموقع أيضًا.

هل تستخدم custom taxonomies والحقول المُخصّصة في موقع ووردبريس الخاص بك؟ لأيّة أشياء تجدها مفيدة أكثر؟ قم بكتابك كلامك في التعليقات.

ترجمة -وبتصرّف لـلمقال Creating Custom Content in WordPress: Taxonomies and Fields لصاحبه Rachel McCollin.

من المتفق عليه عالميًّا الآن أنّ ووردبريس WordPress أكثر من مجرّد منصّة تدوين، بل هو نظام إدارة محتوى Content Management System.

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

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

• أنواع المنشورات المُخصّصة Custom Post Types
• أنواع التّصنيفات المُخصّصة Custom taxonomies
• الحقول المُخصّصة Custom fields

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

فهم واستخدام كل نوع من أنواع المحتوى المُخصّص

من المفيد قبل البدء بإنشاء محتوى مُخصّص أن نعرف ما يفعله كلّ نوع منها وفي أيّة حالات قد نستخدمها، فلنبدأ بأنواع المنشورات المُخصّصة.

1. أنواع المنشورات المُخصّصة

يأتي ووردبريس مُجهّزًا بشكلٍ افتراضي بمجموعة من أنواع المنشورات وهي:

• المنشورات Posts.
• الصفحات Pages.
• المرفقات Attachments.
• عناصر قائمة التّصفّح Navigation menu items.
• المراجعات Revisions.
• الروابط Links (إن كنتَ تستخدم ميّزة المدوّنات blogroll).

تستطيع أيضًا إنشاء أنواع خاصة بك من المنشورات المُخصّصة لتخزين المحتوى الذي لا يندرج تحت أيّ من التصنيفات السابقة، قد تتضمن الأمثلة المنتجات في موقع للتجارة الإلكترونية e-commerce أو الأحداث events في موقع للعروض Listings site، إن كنت استخدمت سابقًا إضافة Plugin لإنشاء متجر، عرض لحدث event listing أو أي نوع آخر من المحتوى الفريد فقد أنشأتَ بالمصادفة نوعًا جديدًا من المنشورات المُخصّصة حتى بدون أن تعرف ذلك.

تستخدم العديد من الإضافات أنواع المنشورات المُخصّصة، نذكر على سبيل المثال:

• MarketPress: تستخدم نوع منشورات مُخصّصة للمنتجات.
• CoursePress Pro: تستخدم أنواع منشورات مُخصّصة للدروس، المدرّبين والطلّاب.
• Support System: تستخدم أنواع منشورات مُخصّصة للتذاكر والأسئلة الشائعة FAQs.

يوجد العديد من الأمثلة الأخرى ولكن تعطينا الأمثلة السابقة فكرة عن استخدامات أنواع المنشورات المُخصّصة.

من الهام أن تتذكر أنّ أنواع المنشورات المُخصّصة هي ليست منشورات، فهي لا تملك أيّة علاقة مباشرة مع المنشورات ويجب أن تفكر بهما بشكل منفصل، يُمكنك إعداد (أو تسجيل) أنواع خاصة بك من المنشورات المُخصّصة لتسلك سلوك المنشورات أو الصفحات، الأمر عائدٌ إليك، فإن تمّ إعدادها كالمنشورات سيكون بإمكانك عرض صفحات الأرشيف الخاصة بها، أمّا إن تمّ إعدادها كالصفحات فستكون بشكلٍ شجري hierarchical، يتم إعداد معظم أنواع المنشورات المُخصّصة لتسلك سلوك المنشورات ولكن لا يعني هذا أنّ أنواعك يجب أن تكون كذلك.

2. أنواع التصنيفات المُخصّصة

وكما وجدنا مع أنواع المنشورات المُخصّصة فإنّ أنواع التّصنيفات المُخصّصة تضيف إلى أنواع التّصنيفات الموجودة مسبقًا في ووردبريس، والتي هي:

• التصنيفات Categories.
• الوسوم Tags.
• هيئات المنشور Post Formats.
• تصنيفات الرابط Link categories (والتي تنطبق على الروابط في المدوّنة blogroll إن كنت تستخدمها).

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

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

تتضمن الأمثلة ما يلي:

• على موقع للتجارة الإلكترونية: تكون أنواع التّصنيفات للمنتج Product غالبًا متعددة كاللون والحجم والنسيج بالنسبة لمتجر ألبسة.
• على موقع لعروض الأحداث: taxonomies لنوع الحدث ومكانه والمزيد من ذلك.
• على قاعدة المعرفة knowledgebase: إنشاء taxonomies لترتيب البيانات بطريقة شاملة، على سبيل المثال إن كانت قاعدة معرفة لتطوير الوِب فربّما تستخدم taxonomies للغات البرمجة، درجة الصعوبة والمنصّات platforms.

نذكر مرّة آخرى أنّ الإضافات تستخدم أنواع التّصنيفات المُخصّصة، يوجد على سبيل المثال في إضافة MarketPress تصنيفات ووسوم للمنتج بشكلٍ مستقل عن تصنيفات ووسوم منشورات المدوّنة Blog posts، يوجد في CoursePress تصنيفات للدرس وفي نظام الدعم توجد أيضًا taxonomies لأنواع التذاكر وتصنيفات للأسئلة الأكثر شيوعًا FAQ.

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

فإن كنّنا نقوم بتطوير موقع للتدريب على سبيل المثال وأردنا استخدام تصنيفات لترتيب المنشورات حسب المهارة أو المعلومات التي يتم تدريسها فبإمكاننا استخدام التصنيفات الشجرية hierarchical categories كما يظهر في هذه الصورة، تستطيع أن ترى هنا أننا نملك ثلاثة تصنيفات في المستوى الأعلى وهي: تطوير الإدارة management development، تطوير شخصي personal development ومهارات تقنيّة technical skills، مع وجود كافة التصنيفات الأخرى تحتها في المستوى التالي.

ولكن ماذا لو تعقّدت الأمور أكثر قليلًا؟ فلنفرض أنّك أردت إضافة سلسلة من المنشورات حول التواصل مع فريقك.

ستكون الأمور أسهل لو استطعنا فصل حقيقة أنّ هذه المنشورات هي للمدراء managers وتتعلّق في نفس الوقت بمهارات التواصل communication skills، لذلك من الأفضل ربّما لو استطعنا إضافة تصنيف taxonomy للجمهور audience واستخدامه لتحديد المنشورات للمدراء managers بدلًا من أن نملك تطوير الإدارة management development كتصنيف، باستطاعتنا إنشاء تصنيف جديد للجماهير audiences، بهذه الطريقة نستطيع تحديد الموضوعات المتعدّدة ومجموعات الجمهور المتعّددة لكل منشور.

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

3. الحقول المُخصّصة

النوع الثالث من المحتوى المُخصّص هو الحقل المُخصّص، يتمّ الإشارة له أيضًا بأنّه البيانات الوصفية Metadata للمنشور.

يتكون الحقل المُخصّص من عنصرين يُمكنك رؤيتهما وتعديلهما في شاشة تعديل المنشور وهما المفتاح key والقيمة value، بإمكانك استخدام نفس المفتاح عدّة مرات للمنشورات المتعدّدة ولكن تملك كل منها قيمة فريدة يُعطي ووردبريس كل حقل مُخصّص تقوم بإنشائه مُعرّف ID فريد خاص به أيضًا، والذي يعني أنّ كلّ حقل مُخصّص لكل منشور هو فريد من نوعه حتى ولو كانت تملك نفس المفتاح والقيمة.

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

ملاحظة: تعطيك بعض الإضافات اختيارًا لكي تنتقي قيمة الحقل المُخصّص من صندوق قائمة منسدلة، ولكنها ستستخدم صندوق وصفي مُخصّص metabox يتم إنشاؤه من قبل الإضافة في شاشة تعديل المنشور بدلًا من واجهة الحقول المُخصّصة المعيارية التي يزودنا بها ووردبريس.

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

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

وهذا ما تفعله إضافة Jobs & Experts، فهي تستخدم تجميعة combination من الحقول المُخصّصة (يُشار إليها بـ “Job Meta”) و taxonomies (يُشار إليها بـ “Category and Skill”) لترتيب البيانات:

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

سنتعلّم كيفية إنشاء حقولنا المُخصّصة في الدرس التالي من هذه السلسلة، سننتقل في هذا الدرس إلى إنشاء أنواع المنشورات المُخصّصة.

إنشاء نوع منشورات مُخصّصة

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

• تزوّدك CustomPress بواجهة لإنشاء أنواع المنشورات المُخصّصة، التصنيفات والحقول المُخصّصة وهي سهلة الاستخدام كثيرًا، إن كنت تريد إنشاء العديد من أنواع المحتوى المُخصّص ستوفر عليك هذه الإضافة عناء تثبيت أكثر من إضافة.
• إنّ إضافة Custom Post Type UI هي أشيع إضافة مجانيّة لإضافة أنواع المنشورات المُخصّصة على مستودع الإضافة plugin repository، فهي تسمح لك بإضافة أنواع المنشورات المُخصّصة وأنواع التّصنيفات ولكن لا تسمح بإنشاء الحقول المُخصّصة، واجهتها ليست سهلة الاستخدام تمامًا كما في CustomPress، مع المزيد من المصطلحات التقنيّة لكي تتمكّن من فهمها، ولكنّها تقوم بعملها.

تستطيع القراءة أكثر عن الإضافات التي تساعدك على إنشاء محتوى مُخصّص في مراجعتنا عن أفضل إضافات أنظمة إدارة المحتوى the best CMS plugins. ولكن إن كنتَ ترتاح ببرمجة الأنواع الخاصّة بك فها هي طريقة تسجيل نوع منشورات مُخصّصة.

1. برمجة نوع المنشورات الخاصة بك

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

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

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

ابدأ بإنشاء ملف فارغ جديد يُدعى post-types.php وقُم بحفظه في مجلّد plugins الموجود في مجلّد wp-content.

أضف الآن الشيفرة التالية إلى ذلك الملف:

<?php
/*Plugin Name: Create Product Post Type
Description: This plugin registers the 'product' post type.
Version: 1.0
License: GPLv2
*/
?>

تفتح هذه الشيفرة ملف الإضافة وتُخبر ووردبريس أنّها عبارة عن إضافة، تُزوّدنا أيضًا بعنوان title ووصف description والذي سيساعدك في تحديد الإضافة عند تفعيلها على موقعك.

أضف الآن هذه الأسطر تحت السطر الذي يحتوي على */  وفوق سطر الإنهاء ?> :

function wpmudev_create_post_type() {

}
add_action( 'init', 'wpmudev_create_post_type' );

سيقوم هذا بإنشاء دالّة تحمل الشيفرة لتسجيل نوع المنشورات الخاصّة بك وسيقوم بإرفاقها إلى init hook باستخدام الدالّة ()add_action، تتأكد هذه الدالّة من أنّ ووردبريس يقوم بتشغيل دالّتك في الوقت المناسب.

تحتاج الآن لإضافة شيفرة النوع الخاص بك من المنشورات المُخصّصة داخل الأقواس curly braces:

// set up labels
$labels = array(
'name' => 'Products',
'singular_name' => 'Product',
'add_new' => 'Add New Product',
'add_new_item' => 'Add New Product',
'edit_item' => 'Edit Product',
'new_item' => 'New Product',
'all_items' => 'All Products',
'view_item' => 'View Product',
'search_items' => 'Search Products',
'not_found' => 'No Products Found',
'not_found_in_trash' => 'No Products found in Trash',
'parent_item_colon' => '',
'menu_name' => 'Products',
);

//register post type
register_post_type( 'product', array(
'labels' => $labels,
'has_archive' => true,
'public' => true,
'supports' => array( 'title', 'editor', 'excerpt', 'custom-fields', 'thumbnail','page-attributes' ),
'taxonomies' => array( 'post_tag', 'category' ),
'exclude_from_search' => false,
'capability_type' => 'post',
'rewrite' => array( 'slug' => 'products' ),
)
);

دعنا نلقي نظرة أقرب على ما تفعله هذه الشيفرة، يخبر المقطع الأول ووردبريس أيّة تسميات labels تريد استخدامها لنوعك من المنشورات، ستقوم هذه التّسميات باستبدال التّسميات الافتراضيّة والتي هي: Posts ،Add Post... إلخ، نقوم بعد ذلك باستدعاء دالّة ()register_post_type والتي تملك المُعامِلات parameters التالية:

• title: لن تعمل الدالّة بدونه.
• labels: التّسميات التي قمتَ بتحديدها مُسبقًا.
• has_archive: عند تعيين قيمته إلى true فأنت تُخبر ووردبريس بأنّه من الممكن إظهار صفحات الأرشفة بالنسبة لنوع المنشور هذا.
• public: قم بتعيين قيمته إلى true لكي تتأكد أنّه بإمكان الناس رؤية صفحة لكل منتج على موقعك.
• supports: عناصر مدير نظام ووردبريس WordPress admin التي يدعمها نوع المنشورات المُخصّصة.
• taxonomies: مصفوفة array من أنواع التّصنيفات التي تريد استخدامها مع نوع المنشورات، لقد قمت باستخدام التصنيفات والوسوم المُضمّنة، على الرغم من أنّك قد ترغب بتركها فارغة وتسجيل taxonomy مُخصّصة للنوع الخاص بك من المنشورات لاحقًا.
• exclude_from_search: قم بتعيين قيمته إلى false لكي تتأكد أنّه يتم تضمين منتجاتك في نتائج البحث.
• capability_type: يتم تعيين قيمة هذا الُمعامل كـ post لأنّ منتجاتنا ستسلك سلوك المنشورات وليس الصفحات.
• rewrite:  يُخبر هذا المُعامل ووردبريس ما هو الـ slug بالنسبة لأرشيف نوع المنشورات، والذي هو النص المُستخدم بعد اسم نطاقك domain كرابط له، بتعيين هذا إلى القيمة products سيكون رابط صفحة منتجك: http://mysite.com/products

قُم الآن بحفظ ملفك، ستبدو شيفرة الإضافة كاملةً كما يلي:

<?php
/*Plugin Name: Create Product Post Type
Description: This plugin registers the 'product' post type.
Version: 1.0
License: GPLv2
*/

// register custom post type to work with
function wpmudev_create_post_type() {
// set up labels
$labels = array(
'name' => 'Products',
'singular_name' => 'Product',
'add_new' => 'Add New Product',
'add_new_item' => 'Add New Product',
'edit_item' => 'Edit Product',
'new_item' => 'New Product',
'all_items' => 'All Products',
'view_item' => 'View Product',
'search_items' => 'Search Products',
'not_found' => 'No Products Found',
'not_found_in_trash' => 'No Products found in Trash',
'parent_item_colon' => '',
'menu_name' => 'Products',
);

//register post type
register_post_type( 'product', array(
'labels' => $labels,
'has_archive' => true,
'public' => true,
'supports' => array( 'title', 'editor', 'excerpt', 'custom-fields', 'thumbnail','page-attributes' ),
'taxonomies' => array( 'post_tag', 'category' ),
'exclude_from_search' => false,
'capability_type' => 'post',
'rewrite' => array( 'slug' => 'products' ),
)
);
}
add_action( 'init', 'wpmudev_create_post_type' );
?>

ستحتاج إلى تفعيل إضافتك الجديدة لكي يعمل النوع الخاص بك من المنشورات، اذهب إلى صفحة الإضافات Plugins في لوحة تحكم موقعك وقم بإيجاد إضافتك الجديدة:

اضغط على رابط التفعيل Activate لكي يتم تفعيلها، سترى الآن نوعًا إضافيًا للمنشورات في قائمة لوحة التحكم:

تستطيع الضغط على رابط المنتجات Products والبدء بإضافة منتجات إلى موقعك بنفس الطريقة التي تفعلها مع المنشورات.

عرض نوع المنشورات الخاصة بك على واجهة الموقع الأمامية Front End:

بمجرّد أن تقوم بإضافة بعض المنتجات ستحتاج أن تكون قادرًا على عرضها على واجهة موقعك.

1. ضبط الروابط الدائمة Permalinks لكي توصلك إلى صفحات نوع المنشورات الخاصة بك

تحتاج في البداية لتحديث الروابط الدائمة Permalinks على موقعك بحيث يستخدم ووردبريس الروابط الصحيحة لعرض المنتجات أو أرشيف المنتجات:

1. في لوحة تحكم ووردبريس اذهب إلى إعدادات: Settings -> Permalinks
2. تأكد من أنّه تم اختيار خيار اسم المنشور “post name”.
3. 3.اضغط على زر حفظ التغييرات Save Changes.

ملاحظة: تحتاج إلى فعل هذا حتى ولو كنت قد قمت بإعداد الروابط الدائمة مُسبقًا لأنّ ووردبريس يحتاج إلى تحديث هذه الإعدادات لأجل مجموعة الروابط الجديدة لمنتجاتك.

2. إضافة نوع المنشورات الخاصة بك إلى قائمة التصفّح

إن كنت ترغب بإضافة منتجات إلى قائمة التصفّح لديك تستطيع الذهاب إلى: Appearance -> Menus

وسترى أنّه يتم عرض المنتجات على اليسار، قم ببساطة بسحب أي منتج إلى قائمتك لكي تُضّمنه إليها.

إنّ إضافة أرشيف منتج أصعب قليلًا ولعمل هذا تحتاج إلى إضافة رابط مُخصّص Custom Link إلى القائمة:

1. بينما لا تزال في شاشة القوائم اضغط على صندوق القوائم Links box على اليسار.
2. في حقل الـ URL اكتب http://mysite.com/products مستبدلًا mysite.com باسم نطاقك الخاص.
3. في حقل نص الرابط Link text اكتب Products.
4. اضغط على زر إضافة إلى القائمة Add to Menu.
5. بعد أن تمّت إضافة الرابط إلى القائمة قم بنقله إلى المكان المناسب وقم بحفظ القائمة.
6. احفظ تغييراتك بالضغط على Save Menu. Don’t miss this step!

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

3. قالب Template لنوع المنشورات الخاصة بك

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

عندما يقوم ووردبريس بعرض منتج واحد سيبحث في قالبك عن كل واحد من هذه الملفات بالترتيب:

1. ملف لعرض منتج وحيد يُدعى single-product.php.
2. ملف لنشر كل المنشورات المفردة من أي نوع منشور كانت ، يُدعى single.php.
3. الملف العام لنشر كل أنواع المحتوى يُدعى index.php.

عندما يعرض ووردبريس أرشيف لمنتج سيعمل من خلال ملفات القالب Template هذه:

1. ملف لعرض أرشيف المنتج يُدعى archive-product.php.
2. قالب أرشيف عام يُدعى archive.php.
3. القالب الافتراضي default template وهو index.php.

سيعمل ووردبريس عبر هذه الشجرة hierarchy ويستخدم ملف القالب الذي يصادفه أولًا، لذا إن كنت تريد إنشاء قالب مُخصّص custom template لمنتجاتك فمن الجيّد أن تبدأ بنسخ ملف single.php وتحفظه باسم single-product.php ومن ثمّ تقوم بتعديله.

على أيّة حال إن لم تكن ترغب بإنشاء ملفات قالب template files سيقوم ووردبريس بكل سرور باستخدام الملفات الموجودة مُسبقًا ضمن قالبك، وهو ما تمّ عمله بالنسبة لي مع ملفات archive.php و single.php على قالب twenty fifteen theme.

ملخّص

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

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

سنتعلّم في الدرس القادم كيف نقوم بإنشاء taxonomies مُخصّصة وحقول مُخصّصة.

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

ترجمة -وبتصرّف- للمقال Creating Custom Content in WordPress: Custom Post Types لصاحبه Rachel McCollin.

sse-examples.zip

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

الهدف

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

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

بناء الإضافة

بإمكانك نسخ كامل النصّ البرمجيّ الذي سنعمل على بناءه في هذا المقال إلى ملف functions.php الخاص بالقالب الذي تستخدمه، لكن الودجت الحقيقية تأتي على شكل إضافة plugin، وباعتبار أن إنشاء واحدة هو أمرٌ سهل فلمَ لا تُكمل معنا خطوةً بخطوة. بدايةً أنشئ مجلد جديد داخل الدليل wp-content/plugins باسم معبّر عن ما سنقوم به، بالنسبة لي فقد أسميته my-featured-content. تاليًا سننشئ الملف الأساسي للإضافة داخل هذا المجلد، وانتبه إلى أن يتطابق اسم الملف المُنشئ مع اسم المجلد بينما يحمل اللاحقة PHP، ففي حالتي هذه يكون اسم الملف my-featured-content.php. افتح الملف الجديد وألصق به النصّ التالي، يُحَلّل هذا التعليق من قبل محرّك WordPress حيث تُستخدم البيانات الواردة ضمنه للتعريف عن الإضافة في قسم الإضافات ضمن لوحة التحكم في موقعك.

<?php / 
  Plugin Name: My Featured Content 
  Version: 1.0 
  Plugin URI: http://danielpataki.com 
  Description: Allows you to add an arbitrary featured item to the sidebar. Includes a title, image, description   and a link. 
  Author: Daniel Pataki Author 
  URI: http://danielpataki.com/ / 

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

مكونات الودجت

إنشاء ودجت لمنصة ووردبريس يتم عبر أربع خطوات:

• بدء وإعداد الودجت.
• العمل على البنية التحتيّة backend للودجت.
• استكمال البنية التحتيّة للودجت وإضافة ما يلزمها من قواعد معالجة rules for processing.
• إضافة واجهة رسومية frontend تدير تعامل المُستخدم مع الودجت. 

جميع هذه الخطوات تُترجم عمليًا على شكل دوال functions محدّدة، لنلقي نظرة على المخطط العام للخطوات الأربع السابقة برمجيًا:

add_action( 'widgets_init', 'mfc_init' ); 

function mfc_init() { 
  register_widget( 'mfc_widget' ); 
} 

class mfc_widget extends WP_Widget { 
  public function __construct() { 
    // Basic widget details 
  } 
  
  public function widget($args, $instance ) { 
    // Widget output in the front end 
  } 
      
  public function update( $new_instance, $old_instance ) { 
    // Form saving logic - if needed 
  } 
  
  public function form( $instance ) { 
    // Backend Form 
  } 
}

وكما ترى فإننا أنشأنا فئة ممتدة class extending باسم WP_Widget، إذا لم يكن لديك فكرة عن معنى ذلك؛ فلا تقلق، إذ لا يلزمك هنا معرفة البرمجة الشيئيّة في PHP، كل ما يلزمنا حتى الآن هو بدء إعداد الودجت بشكل صحيح من خلال الفئة السابقة. انتبه أيضًا إلى أننا ضمنّا الدالة ()mfc_init داخل الحدث widgets_init، ومن خلال هذه الدالة نستخدم دالة أخرى هي ()register_widget لبدء إعداد الودجت بتمرير اسم الفئة mfc_widget لها. الأحرف الثلاثة الأولى في اسم الفئة "mfc" تشير إلى "My Featured Content"، يدعى هذا القسم بـ "بادئة اسم الدالة" function prefixing" ويهدف إلى إنشاء الدوال بأسماء مميزة تمامًا درءًا لمشكلة التعارض بين أسماء الدوال المستخدمة في مختلف الإضافات. نودّ الإشارة هنا أيضًا إلى الفرق بين ما يسمى بـ "الطريقة" method و"الخاصيّة" property، "الطريقة" هي دالة مضمّنة ضمن فئة class أو شيء object، فإذا أنشأنا الدالة خارج فئة أسميناها "دالة"، بينما نطلق عليها اسم "طريقة" فيما لو وضعت ضمن فئة، وتسمى المتغيرات Variables المعرّفة ضمن فئة ما بـ"الخصائص" properties. حاليًا لا يوجد أهمية على التفريق بينهما، إلا أنه من الجيد أن ترتب مفاهيمك بشكل صحيح.

بنية الودجت

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

$widget_details = array( 'classname' => 'mfc_widget', 'description' =>h 'Creates a featured item consisting of a title, image, description and link.' ); 
parent::__construct( 'mfc_widget', 'Featured Item Widget', $widget_details ); 

نموذج البنية التحتيّة

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

<?php public function form( $instance ) { 
  $title = ''; 
  if( !empty( $instance['title'] ) ) { 
    $title = $instance['title']; 
  } 

  $description = ''; 

  if( !empty( $instance['description'] ) ) { 
    $description = $instance['description']; 
  } 

  $link_url = ''; 

  if( !empty( $instance['link_url'] ) ) { 
    $link_url = $instance['link_url']; 
  } 

  $link_title = ''; 

  if( !empty( $instance['link_title'] ) ) { 
    $link_title = $instance['link_title']; 
  } 
?>
<p> 
    <label for="<?php echo $this->get_field_name( 'title' ); ?>">
        <?php _e( 'Title:' ); ?>
    </label> 
    <input class="widefat" id="<?php echo $this->get_field_id( 'title' ); ?>" name="<?php echo $this- >get_field_name( 'title' ); ?>" type="text" value="<?php echo esc_attr( $title ); ?>" /> 
</p>

<p> 
    <label for="<?php echo $this->get_field_name( 'description' ); ?>"><?php _e( 'Description:' ); ?></label>    
    <textarea class="widefat" id="<?php echo $this->get_field_id( 'description' ); ?>" name="<?php echo $this->get_field_name( 'description' ); ?>" type="text" ><?php echo esc_attr( $description ); ?></textarea> </p>

<p> 
    <label for="<?php echo $this->get_field_name( 'link_url' ); ?>"><?php _e( 'Link URL:' ); ?></label> 
    <input class="widefat" id="<?php echo $this->get_field_id( 'link_url' ); ?>" name="<?php echo $this->get_field_name( 'link_url' ); ?>" type="text" value="<?php echo esc_attr( $link_url ); ?>" /> 
</p>

<p> 
    <label for="<?php echo $this->get_field_name( 'link_title' ); ?>"><?php _e( 'Link Title:' ); ?></label> 
    <input class="widefat" id="<?php echo $this->get_field_id( 'link_title' ); ?>" name="<?php echo $this->get_field_name( 'link_title' ); ?>" type="text" value="<?php echo esc_attr( $link_title ); ?>" /> 
</p>

 يبدو النصّ البرمجي السابق طويلًا لاستخدامنا أربع حقول كما أسلفنا، حيث بدأنا بالإعلان عن قيمة كل حقل، المتغيّر instance$ يضم القيم الافتراضية للحقول تحسبًا لتركها فارغة من قبل المستخدم، ثم أنشأنا لكل حقل عنصرين، مربع لإدخال النصّ المطلوب وعنوان له label يوضّح وظيفته، استخدمنا برمجيًا لذلك كل من دالة ()get_field_name ودالة ()get_field_id. قد يتساءل هنا البعض؛ لماذا استخدمنا دوال للحقول الأربع بدل كتابة الأسماء والقيم بأنفسنا مباشرة؟ يعود ذلك لتجنب التعارض فيما إذا كان هناك ودجات مشابهة مستخدمة، وهكذا يتولى ووردبريس بآلياته الداخلية إدارة ذلك بشكل تلقائي. عنصر الإدخال الأخير يحمل الاسم link_url بدلًا من link فحسب. هذه هي الطريقة التي يعالج بها ووردبريس وجود مساحة متعدّدة للودجات، وأشرطة جانبية متعددة، وودجات متعددة. الكود السابق يجب أن يظهر على شكل نموذج ضمن قسم الودجات، والذي يمكن استخدامه لملئ الودجت بالمعلومات المطلوبة.

معالجة بيانات النموذج

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

public function update( $new_instance, $old_instance ) { 
  return $new_instance; 
} 

عرض الودجت

تعرض الدالة ()widget الودجت الخاصة بنا، يمكننا هنا إضافة وسوم HTML لتظهر على الشريط الجانبي. تأخذ هذه الدالة محدّدين Arguments؛ يحتوي الأول على بيانات متعلقة بمنطقة تموضع الودجت، بينما يضم الآخر القيم الافتراضية لمتغيرات الودجت. يتم إعداد منطقة تموضع الودجت بتعريف عدد من المعاملات Parameters، أهمها المحتوى قبل وبعد الودجت، وقبل وبعد عنوان الودجت. للتأكّد من توافق الودجت مع منصة ووردبريس ومع الإضافات الأخرى يمكنك استخدام الإطار التالي عندما تنشئ إضافة:

echo $args['before_widget']; 
if ( ! empty( $instance['title'] ) ) { 
    echo $args['before_title'] . apply_filters( 'widget_title', $instance['title'] ). $args['after_title']; 
} 
// Rest of the widget content 
echo $args['after_widget'];

داخل هذا الإطار نضيف قيمة حقل "الوصف" وحقل "الرابط" والذين حصلنا عليهما من حقلي link_url و link_title، شيء كهذا:

<div class='mfc-description'> 
  <?php echo wpautop( esc_html( $instance['description'] ) ) ?> 
</div>

<div class='mfc-link'> 
  <a href='<?php echo esc_url( $instance['link_url'] ) ?>'>
    <?php echo esc_html( $instance['link_title'] ) ?>
  </a> 
</div>

لا تنسَ أخيرًا استخدام دالة الهروب escaping functions والتي ستحمي البيانات قبل تقديمها للمستخدم. للمزيد حول هذا الموضوع يمكنك قراءة المقال التالي من مركز WordPress Codex.

إضافة صورة

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

add_action( 'admin_enqueue_scripts', array( $this, 'mfc_assets' ) ); 

إذا لم يكن لديك معرفة بالبرمجة الشيئية مع PHP فقد تختلط عليك الأمور قليلًا هنا، البارامتر الثاني للدالة ()add_action عادةً ما يكون سلسلة string تشير إلى الدالة المطلوبة، نفس الشيء يحدث هنا لكننا نبيّن أننا نريد الدالة ()mfc_assets محليًا ضمن الفئة التي أنشأناها، وليس دالة بمجال عام global scope. الخطوة التالية هي إنشاء الدالة ()mfc_assets داخل الفئة، ومن ثم إدراج نصوص JS و CSS اللازمة بداخلها:

public function mfcassets() { 
    wpenqueue_script('media-upload'); 
    wp_enqueue_script('thickbox'); 
    wp_enqueue_script('mfc-media-upload', plugin_dir_url(__FILE) . 'mfc-media-upload.js', array( 'jquery' )) ; 
    wp_enqueue_style('thickbox'); 
}

كما ترى، فإننا أضفنا كلًا من media-upload و thickbox وهي سكربتات JS مُقدّمة من ووردبريس تدير تعامل المستخدم مع الوسائط، كما أضفنا السكربت الخاص بنا mfc-media-upload.js، وهو ملف بسيط للغاية يدير عملية رفع الصور (سنتكلم عن ذلك بعد قليل)، أخيرًا وليس آخرًا أضفنا ملف التصميم CSS المطلوب من قبل الدالة thickbox. سنعود الآن خطوة إلى الوراء لتعديل عملنا السابق بإضافة حقل إضافة الصورة، حيث سيلزمنا معرفة قيمة حقل الصورة، وخرج عنصر التحكم بها، تمامًا كما فعلنا من قبل:

$image = ''; 
if(isset($instance['image'])) { 
    $image = $instance['image']; 
}
<p>
    <label for="<?php echo $this->get_field_name( 'image' ); ?>"><?php _e( 'Image:' ); ?></label>
    <input name="<?php echo $this->get_field_name( 'image' ); ?>" id="<?php echo $this->get_field_id( 'image' ); ?>" class="widefat" type="text" size="36" value="<?php echo esc_url( $image ); ?>" />
    <input class="upload_image_button" type="button" value="Upload Image" />
</p>

وكما ترى فإن عملنا هنا مشابه تمامًا لما سبق، الإضافة الوحيدة هي زر إدخال input مع الفئة upload_image_button. أنشئ الآن ملفًا جديدًا باسم mfc-media-upload.js، سيضم هذا الملف نصّ جافا سكربت يعمل على إظهار مربع اختيار صورة عند الضغط على الزر، داخل الملف ضع الكود التالي:

jQuery(document).ready(function($) { 
    $(document).on("click", ".upload_image_button", function() {
        jQuery.data(document.body, 'prevElement', $(this).prev());
        window.send_to_editor = function(html) { 
             var imgurl = jQuery('img',html).attr('src'); var inputText = jQuery.data(document.body, 'prevElement');

             if(inputText != undefined && inputText != '') { inputText.val(imgurl); 
        }

        tb_remove(); 
     };
tb_show('', 'media-upload.php?type=image&TB_iframe=true'); return false; }); 
});

بعد تحديد الصورة سيُمرر رابط الصورة إلى عنصر الإدخال السابق input element كي يحفظ. أخيرًا ينبغي تمرير قيمة الحقل لإظهار الصورة ضمن الودجت:

<p> <img src='<?php echo $instance['image'] ?>'> </p>

النتيجة النهائية ينبغي أن تكون شيئًا مشابها لما يلي:

خاتمة

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

 ما هي الاستخدامات التي تفكّر بها لهذه الودجت؟ دعنا نطلع على أفكارك في التعليقات.

 تُرجم وبتصرف من المقال Creating a Featured Content Widget – With its Own Image Uploader لصاحبه Daniel Pataki.

الانتشار الكبير في استخدام لغات تصميم الويب أدى إلى ظهور بعض إطارات العمل (Frameworks) الجاهزة التي تسهل وتسرع عملية تطوير الواجهات كذلك فإن الانتشار الواسع لووردبريس والطلب الكبير لقوالبه دفع بعض المطورين والشركات إلى تطوير العديد من الأدوات الجاهزة التي تسهل بصورة أو أخرى عملية تطوير قوالب ووردبريس، إحدى هذه الأدوات الجيدة جدا هي قالب Underscores _s والذي يتمتع بمجموعة من المميزات (كما سنرى) تجعله من أفضل الأدوات المعينة لمطور قوالب ووردبريس. وفي هذا المقال سنتعرف على بعض مميزات قالب _s  وطريقة استخدامه والاستفادة منه، لكن دعنا في الأول نلقي نظرة سريعة على  بعض الأدوات المتاحة لمطوري قوالب ووردبريس (من قبل شركات أو مطورين أخرين) وأنواعها وفي أي الأنواع يمكن تصنيف قالب Underscores _s.

أطر عمل قوالب ووردبريس WordPress Theme Frameworks

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

التعريف المبسط لإطار العمل Framework في مجال تطوير الويب

هو عبارة عن مجموعة من الأدوات الجاهزة (عادة شيفرات برمجية) تؤدي بعض المهام الشائعة وتغنيك هذه الإطارات من كتابة هذه الشيفرات بنفسك. بالطبع فإن التعريف يمكن أن يكون أعم من ذلك لكن هذا ما نحتاجه في هذا المقال.

إطارات عمل قوالب ووردبريس Themes Framework

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

1. القالب الأب Parents Themes (البعض يطلق عليها Themes Framework) هذا النوع من الأدوات عبارة عن قالب جاهز يمكنك الاستفادة منه من خلال صنع قالبك كقالب ابن Child Theme له وذلك بالاستفادة من هذه الميزة (القالب الابن) التي يوفرها ووردبريس. عادة عند إطلاق كلمة إطار عمل قوالب Themes Framework فإن المقصود هو هذا النوع من القوالب، ومن أشهر هذه القوالب هو إطار العمل Genesis ومن الإطارات ذات التطوير العربي هنالك إطار العمل ممتاز  وليس المقام هنا لسرد القوالب المتوفرة تحت هذا النوع من الأدوات.
2. إطارات عمل لوحة تحكم القوالب Theme Options Framework هذا النوع من الأدوات كما يظهر من أسمه يستخدم لتسهيل مهمة إنشاء لوحة تحكم للقالب فهو يسهل عملية إضافة واسترجاع خيارات القالب وعادة ما يوفر مجموعة من الحقول المتقدمة التي تتطلب برمجتها بدونه بعض الوقت والجهد. البعض أيضا يطلق كلمة إطار عمل (هكذا بإطلاقها) على هذا النوع من الأدوات، ومن أشهر هذه الإطارات إطار عمل Redux.
3. المكتبات المساعدة Dropin Libarary  هذه مجموعة من الملفات التي تقوم بتضمينها في قالبك للاستفادة من الدوال والأصناف الموجودة فيها وبالرغم من أن كثير من إطارات عمل لوحة التحكم يمكنها العمل بنفس الطريقة (تضمين ملفاتها في قالبك) لكن هذه المكتبات توفر عادة أكثر من مجرد تسهيل لعمل لوحة التحكم بل تتيح لك المزيد من التسهيلات فيما يتعلق بتطوير القالب ككل. من هذه المكتبات إطار العمل Hyprid.
4. القالب الابتدائي Starter Theme  عبارة عن قالب جاهز بنسبة كبيرة تقوم بتطوير قالبك بالتعديل عليه مباشرة لا عن طريق استخدام قالب ابن كما في الرقم 1 من هذه القائمة، ويوفر هذا القالب عادة التركيبة الأساسية لملفات قوالب ووردبريس وبعض الدوال والإعدادات الأساسية للقالب بحيث يجعل المصمم يركز على التصميم (CSS) أو تحويل التصميم الجاهز. قالب Underscores والذي نحن بصدد التعرف عليه يقع تحت هذا النوع من إطارات العمل وتستطيع استخدامه في تطوير قالبك من الخلال التعديل المباشر عليه كما سنرى لاحقا إن شاء الله.

مميزات قالب Underscores

هنالك عدة مميزات تجعل من الجيد إختيار هذا القالب كنقطة بداية لتطوير قالبك، ومن هذه المميزات:

• القالب مفتوح المصدر ومطور من قبل مجموعة من المبرمجين المحترفين وعلى رأس التطوير شركة Automatic الراعية لووردبريس، وهذا يضمن لك توافقية عالية بين ووردبريس وقالب Underscores وكذلك احترافية في تطويره.
• القالب يعتمد على HTML5 كما أنه موثق بصورة جيدة ويحتوي على نسبة مناسبة من الشيفرات (بالتالي لن تفقد الكثير من الأساسيات الموجودة في أي قالب كما أنك لن تضطر لمسح الكثير من الشيفرات).
• يحتوي على مثال لتطبيق خاصية الترويسة المخصصة Custom header التي يوفرها ووردبريس.
• مجموعة مخصصة من وسوم القالب Template Tags (يشير هذا المصطلح الى مجموعة من الدوال تستخدم في جلب بيانات المقال) يمكنك استخدامها لتجنب تكرار الشيفرات البرمجية.
• مجموعة من تنسيقات CSS الأساسية تحتوي على توضيح لبعض فئات العناصر CSS Classes التي يولدها ووردبريس.
• يتبع الCoding standard الخاصة بووردبريس وموثق بصورة ممتازة، حيث يمكنك أن تتعلم الكثير منه.
• مجموعة من الدوال والإعدادات الأساسية في ملف functions.php.
• يشجع على استخدام مخصص القوالب Theme Customizer وهذا أمر مهم جدا خصوصا وأنه قبل أيام قليلة من نشر هذا المقال أصبح إستخدام مخصص القوالب لإعدادات القالب أمر إجباري لكل القوالب في مستودع القوالب الخاص بووردبريس وهذا قد يشير إلى توجه في مجتمع ووردبريس نحو المخصص ومحاولة جعلها Standerd في مسألة خيارات القالب، ولذلك في نهاية هذه السلسلة سنلقي نظرة إلى طريقة إستخدام مخصص القوالب في خيارات القالب.

طريقة استخدام Underscores

في البداية عليك التوجه لموقع القالب وقم بكتابة اسم القالب الذي تود تطويره في الخانة المخصصة ويمكنك الضغط على Advanced Options لإدخال المزيد من الخيارات مثل اسم المطور ورابط موقعه ووصف القالب، وسيقوم الموقع باستخدام هذه المعلومات ويولد لك القالب والذي سيبدأ التحميل مباشرة فور الضغط على Generate. طبعا ستجد أن المعلومات التي قمت بكتابتها تم استخدامها في الترويسة الأساسية للقالب والموجودة في ملف style.css وكذلك في اسم مجلد القالب. بعد ذلك يمكنك تنصيب القالب على الموقع الذي قمت بإعداده لتطوير القالب ومن الجيد أن تقوم بفتح مجلد القالب على محرر الشيفرات المفضل بالنسبة لك حتى تتابع معنا شرح بعض خصائص القالب.  

التركيبة الأساسية للقالب (المجلدات والملفات)

ستلاحظ أن مجلد القالب يحتوي على الملفات الأساسية لقوالب ووردبريس وهي:

Style.css, index.php, functions.php, single.php, page.php, archive.php, search.php, 404.php, header.php, footer.php, sidebar.php, comments.php, rtl.css 

بالإضافة الى مجموعة من الملفات التي يبدأ اسمها بـ content وهي:

Content.php, content-single.php, content-page.php, content-search.php, content-none.php

وهذه الملفات تستخدم لوضع محتويات الحلقة The Loop لبعض ملفات القالب الأساسية التي تحتوي على حلقة لجلب المقالات مثل ملف single.php مثلا، حيث يتم تضمين ملف conent المناسب (مثلا content-single.php) في ملف القالب المناسب (single.php) من خلال إستخدام الدالة get_template_part وتستخدم بهذه الطريقة:

<?php get_template_part( 'content', 'single' ); ?> 

حيث أن المعامل الأول للدالة هو بداية اسم الملف والمعامل الثاني هو نهايته (ما بعد الفاصلة) وهذا يوضح لك سبب تسمية الملفات التي تبدئ بـ content بهذه الطريقة. واستخدام هذه الدالة من الأمور الجيدة في هذا القالب لما تتميز به من مميزات وحتى تحافظ على مقروئية جيدة للشيفرة البرمجية فبدلا من وضع كل الشيفرات في ملف single.php او index.php يتم فصل محتويات الحلقة -والتي عادة ما تحتوي على الكثير من شيفرات html- في ملف لوحدها ثم تضمينها. وأيضا يمكنك استخدامها مع الدالة get_post_format لتضمين الملفات اعتمادا على بنية المقال. من الملفات أيضا في المجلد الرئيسي للقالب ملف README.md وصورة screenshot.png ولا أظن أنهما يحتاجان إلى شرح.

مجلد inc

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

require get_template_directory() . '/inc/template-tags.php'; 

حيث أن الدالة ()get_template_directory ترجع مسار القالب الحالي ومن الجيد استخدام دوال ووردبريس التي يوفرها فيما يتعلق بمسارات القالب، وهذه أحد الأشياء التي عليك تعلمها من قالب Underscores بالإضافة الى العديد من الممارسات الجديدة Best Practice الأخرى كما سنرى. تضمين هذه الملفات في ملف functions.php بدلا عن كتابة كل الشيفرات الوظائفية الخاصة بالقالب في ملف functions.php يجعل القالب أكثر تنظيما ويسهل التعديل عليه فيما بعد بالإضافة لفصل الدوال والشيفرات على حسب وظائفها. لاحقا سنتطرق الى تفاصيل بعض هذه الملفات بعد أن نلقي نظرة سريعة على ملف functions.php، لكن الأن دعنا نكمل الاطلاع على تركيبة القالب.

مجلد js

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

بقية المجلدات

كما تلاحظ هنالك أيضا مجلد language الذي به ملفات اللغة، وملف layout وهو يحتوي على ملفي CSS يستخدمان لتوفير خيارين في تخطيط الموقع، وملف sass وبه بعض الملفات المفيدة في حالة كنت تستخدم SASS.

خاتمة 

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

من أهم الأمور التي ينبغي على مطور ووردبريس الإلمام بها ومعرفتها هي قاعدة بيانات ووردبريس حيث أنها المستودع الرئيسي للبيانات في نظام إدارة المحتوى كما أنها تعكس التركيبة الخاصة بووردبريس وأهم محتوياته الأساسية وطريقة تمديده بصورة مثالية ويظهر هذا جليًَا عند اطلاعنا على جداول meta في الفقرات القادمة.

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

جداول قاعدة بيانات ووردبريس

انقر على الصورة لمُشاهدتها بحجمها الكامل

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

جدول wp_options

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

جدول wp_users

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

هذا الجدول مكون من عشرة أعمدة وهي:

• ID: وهو المعرف الخاص بالمستخدم، ويجب أن يكون فريدًا وهو المفتاح الرئيسي للجدول Primary key.

• user_login: اسم المستخدم أو اسم الدخول.

• user_pass: كلمة مرور المستخدم وتحفظ مشفرة في قاعدة البيانات.

• user_nicename: الاسم اللطيف للمستخدم.

• user_email: البريد الإلكتروني للمستخدم.

• user_url: الموقع الإلكتروني للمستخدم.

• user_registered: تاريخ تسجيل المستخدم.

• user_activation_key: المفتاح المستخدم عند استعادة كلمة المرور، يقوم ووردبريس بتوليده عند طلب استعادة المرور ويقوم بمسحه بعد استعماله مباشرة.

• user_status: تم التخلي عن هذا العمود deprecated وربما يتم إسقاطه في النسخ القادمة من ووردبريس.

• display_name: اسم العرض للمستخدم والذي يظهر في واجهة الموقع.

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

جدول wp_usermeta

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

• umeta_id: وهو المعرف الخاص بهذه الـmeta التي تريد إضافتها وهو فريد حيث أنه المفتاح الرئيسي لهذا الجدول.

• user_id: معرف المستخدم الذي تعود له هذه البيانات meta وهو عبارة عن مفتاح أجنبي foreign key يعود إلى جدول wp_user وبهذه الطريقة يتم الربط بين الجدولين كما هو معلوم في قاعدة البيانات العلائقية Relational Database.

• meta_key: مفتاح البيانات meta (اسمها) والذي يتم استدعاؤها به برمجيًّا حيث أن لكل meta مفتاح وقيمة كما هو في الخيارات.

• meta_value: قيمة البيانات meta.

هذه الطريقة المستخدمة في إضافة المزيد للبيانات للمستخدمين بدون التعديل على جدول wp_user وذلك من خلال إتاحة جدول wp_usermeta مستخدمة أيضا مع المقالات post والتعليقات comment حيث يستخدم جداول غير الجداول الأساسية لإضافة بيانات غير البيانات الأساسية لكل من المقالات والتعليقات كما سنرى في الفقرات التالية، ولعل الفكرة العامة لهذه الطريقة وضحت من خلال الجدول الأساسي wp_user وجدوله المساعد wp_usermeta.

جدول wp_posts

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

يحتوي هذا الجدول على ثلاثة وعشرين عمودًا وإليك تفاصيلها

• ID: معرف فريد للمقال.

• post_author: كاتب المقال.

• post_date: تاريخ المقال.

• post_date_gmt: تاريخ المقال بتوقيت جرينتش.

• post_content: محتويات المقال (النّصّ الفعلي للمقال).

• post_title: عنوان المقال.

• post_excerpt: مُقتطف المقال (نصّ اختياري يمكن للمستخدم أن يدخله).

• post_status: حالة المقال (منشور، مسودة، تحت المراجعة، ... الخ).

• comment_status: حالة التّعليقات (هل التعليقات مفتوحة أم مغلقة).

• ping_status: حالة التّنبيه (هل التنبيهات مفعلة أم لا).

• post_password: كلمة مرور للمقال (في حالة كان مغلقا بكلمة مرور).

• post_name: رابط المقال أو ما يسمى بالاسم اللطيف.

• to_ping: روابط المقالات التي سيتم تنبيهها (أي المشار لها في المقال الحالي) وهذه لي حالة أن المقال لم ينشر بعد.

• pinged: روابط المقالات التي تم تنبيهها وهذه في حالة أن المقال قد تم نشره.

• post_modified: تاريخ آخر تعديل للمقال.

• post_modified_gmt: تاريخ آخر تعديل للمقال بتوقيت جرينتش.

• post_content_filtered: تستخدم لتخزين نسخة cache لـpost_content المشار لها سابقا (عادة بعد تطبيق الخطافات المرتبطة بالمُرشح the_content عليها).

• post_parent: معرف المقال الأب لهذا المقال (في حالة كان نوع المقالات هرمي hierarchical مثل الصّفحات.

• guid: اختصار لـGlobal Unique Identifier وهي عبارة عن الرابط الحقيقي للمقال. في حالة الصفحات يكون هذا هو الرابط الفعلي إمّا في حالة الملفّات المرفقة attachments يكون هذا هو الرابط للملف المرفق.

• menu_order: قيمة عددية (0، 1، 2، ...) تُحدّد ترتيب المقال وتعمل مع أنواع المقالات الهرمية مثل الصفحات وليس المقالات العادية.

• post_type: نوع المقال (مقال، صفحة، منتج، ملف مرفق، ..الخ).

• post_mime_type: تعمل فقط مع الملفات المرفقة attachments حيث تحتوي على نوع الميديا للملف MIME type.

• comment_count: عدد التعليقات مضاف إليه عدد التنبيهات pings والتعقيبات trackbacks.

يرتبط جدول المقالات wp_posts مع مجموعة من الجداول وهي

• جدول wp_user: كما تم الإشارة إلى هذا الأمر سابقا حيث أن لكل مقال كاتب.

• جدول التعليقات wp_comments وهذا واضح ليربط كل مقال بالتّعليقات عليه.

• جدول wp_term_relationships وسيتم شرح هذا في الفقرات القادمة.

• جدول wp_postmeta: وهو الجدول التّالي في شرحنا

جدول wp_postmeta

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

يتكون هذا الجدول من أربعة حقول وهي

• meta_id: وهو المعرف الخاص بهذه الـmeta التي تريد إضافتها وهو فريد حيث أنه المفتاح الرئيسي لهذا الجدول.

• post_id: معرف المقال الذي تعود له هذه البيانات meta وهو عبارة عن مفتاح أجنبي foreign key يعود إلى جدول wp_post وبهذه الطريقة يتم الربط بين الجدولين.

• meta_key: مفتاح البيانات meta (اسمها) والذي يتم استدعاؤها به برمجيًّا حيث أن لكل meta مفتاح وقيمة كما هو في جدول wp_usermeta.

• meta_value: قيمة البيانات meta.

يرتبط هذا الجدول بجدول المقالات wp_posts فقط.

جدول wp_comments

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

جدول wp_commentmeta

ومثل هذا الجدول والعلاقة التي تربطه بجدول wp_commetnts هو مثل العلاقة بين كل من wp_posts و wp_postmeta وكذلك wp_users و wp_usermeta. وأظن أن الصورة قد أصبحت واضحة بالنسبة لهذه الطريقة التي يستخدمها ووردبريس في الربط بين البيانات.

جدول wp_links

يستخدم لحفظ البيانات المتعلقة بميزة الروابط links والتي أصبحت ملغية deprecated ورغم أنه يمكنك إعادة تفعيلها من خلال إضافة Link Manager إلا أننا لن نتطرق لشرح هذا الجدول (حتى الإضافة لم تحدث منذ أكثر من عامين).

جدول wp_term_taxonomy

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

إذن يمكن أن نعتبر أن كل نوع Taxonomy عبارة عن أب أو طريقة لتجميع عدد من الـterms أو أن كل term يتبع لنوع معين.

الصورة التالية توضح مفهومي الأنواع Taxonomies وكذلك الـTerms والعلاقة بينهما

انقر على الصورة لمُشاهدتها بحجمها الكامل

هذا الجدول يحتوي على ستة أعمدة وهي

• term_taxonomy_id: معرف العلاقة بين النوع Taxonomy والـterm.

• term_id: معرف الـterm (مثلا 1 أو 7).

• taxonomy: اسم النوع الذي يتبع له هذا الـterm (مثلا تصنيفات أو وسوم).

• description: وصف للعلاقة.

• parent: الأب لهذا الـterm.

• count: عدد المقالات في هذا الـterm.

هذا الجدول يرتبط بجدولي wp_term_relationships وwp_terms التّاليين.

جدول wp_terms

هذا الجدول يعرف فيه الـterms (مثلا التصنيفات أو الوسوم) الموجودة في الموقع ويرتبط بالجدول السابق ليربط كل term مع النوع taxonomy الخاص به.

يتكون هذا الجدول من أربعة عمدة هي

• term_id: معرف الـterm وهذا هو المفتاح الأساسي لهذا الجدول.

• name: اسم الـterm.

• slug: الاسم اللطيف للterm.

• term_group: هذا العمود مضاف لإضافة خاصية تسمح بوجود عدة مسميات لنفس الـterm لكن يبدو أن هذه الخاصية لم تدعم حتى الآن في ووردبريس، وهذا وفقا لأحدى الإجابات على موقع Stack Exchange .

جدول wp_term_relationships

لاحظ أنّه في الجدولين السّابقين كان التركيز على كل من الـterms والأنواع والعلاقة بينهما لكن حتى الآن ليس هنالك ربط فعلي بين التصنيفات والمقالات وعموما بين الـterms والمقالات، وهذه مهمة هذا الجدول حيث يربط المقالات مع معرف جدول wp_term_taxonomy والذي كما ذكرنا يعرف العلاقة بين الأنواع والـterm التابعة لها.

يتكون هذا الجدول من أربعة أعمدة هي

• object_id: وهو معرف المقال الذي يراد ربطه بالـterm الخاص به وهذا هو المفتاح الأساسي لهذا الجدول.

• term_taxonomy_id: وهو عبارة عن مفتاح أجنبي عبارة عن المفتاح الأساسي في جدول wp_term_taxonomy.

• term_order: ترتيب الـterm.

هذا الجدول بالطّبع يرتبط مع جدولي wp_posts وكذلك جدول wp_term_taxonomy وأيضا يرتبط مع جدول wp_links الذي ذكرنا أنه أصبح deprecated.

التعامل مع قاعدة بيانات ووردبريس

بالطبع يمكنك استخدام دوال my_sqli الأساسية المتاحة مع لغة php للتّواصل مع قاعدة البيانات أو حتى استخدام فئة PDO لكن يفضل دوما استخدام الطرق التي يقدمها ووردبريس ما دام ذلك مُمكنًا للحصول على توافقية أكبر للإضافة مع بقية مكونات ووردبريس بالإضافة للاستفادة من الفئات والتسهيلات التي يوفرها ووردبريس، وإليك طريقتين يُوفرهما ووردبريس للتعامل مع قاعدة بياناته:

1- استخدام الحلقة The Loop

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

<?php if ( have_posts() ) : // التحقق من وجود المقالات ?>
<?php /* بدء الحلقة */ ?>
<?php while ( have_posts() ) : the_post(); // تجهيز بيانات المقال ?>
// هنا يتم استخدام وسوم القالب لجلب البيانات المتعلقة بالمقال الحالي
// لاحظ أن ما بداخل الحلقة يتكرر في كل مرة حتى يصل إلى عدم تحقق الشرط في السطر الأول
<?php endwhile; ?>
<?php endif; ?>

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

<?php $args = array(); // هنا يتم تعريف المعاملات التي ستمرر في الأسفل ?>
<?php $query = new WP_Query($args); // تعريف الكائن الذي سيستخدم لجلب المقالات في الحلقة ?>
<?php if ( $query->have_posts() ) : // التّحقق من وجود المقالات ?>
<?php /* بدء الحلقة */ ?>
<?php while ( $query->have_posts() ) : $query->the_post(); // تجهيز بيانات المقال ?>
// ما بداخل الحلقة مشابه للحلقة الأساسية
<?php endwhile; ?>
<?php endif; ?>

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

2- استخدام صنف wpdb

هذا الصّنف يحتوي على مجموعة من الدّوال يستخدمها ووردبريس في التعامل مع قاعدة بياناته، ويمكنك الوصول لهذه الدّوال من خلال استخدام الكائن $wbdb وهو عبارة عن global object وهذا مثال لطريقة استخدامه

global $wpdb; $results = $wpdb->get_results( 'SELECT * FROM wp_options WHERE option_id = 1', OBJECT );

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

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

خاتمة

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

بعد أن تطرّقنا في هذه السّلسلة حول أساسيات تطوير قوالب ووردبريس إلى تحويل صفحة HTML إلى قالب ووردبريس ثم إلى كيفية إضافة Pagination (أو ما يُعرف بالتّصفيح) إليها، سنتطرّق اليوم إلى خاصّيّة أخرى لا تقل أهمّية. قوائم التنقّل (Navigation Menu) هي إحدى ميزات القوالب، توفّر ووردبريس طريقة سهلة للتحكم بالقوائم المخصصة للقالب من داخل لوحة تحكم ووردبريس، وكل ما تحتاجه هو إضافة بضعة أسطر برمجية لتضيف دعم القوائم في قالبك.

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

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

تسجيل القوائم

بدايةً في ملف functions.php ضمن ملفات القالب نحتاج لإضافة دالّة تقوم بتسجيل أسماء القائمة (أو القوائم) التي تريد إضافتها. كالتالي:

add_action('init', function() {
    register_nav_menu('our-custom-menu', 'القائمة الرئيسية');
});

بعد ذلك يمكن التأكد من صحة إضافة القائمة عن طريق الذهاب من لوحة التحكم إلى المظهر (Appearance) ثم القوائم (Menus)، ستظهر لدينا قائمة باسم القائمة الرئيسية في تبويب إدارة موضع القوائم.

تأخذ دالّة register_nav_menu محدّدين هما: المكان (Location) والوصف (Description).

محدّد المكان يستخدم كمعرّف للقائمة، حيث يتم طلب محتوى القائمة ضمن ملفات القالب عن طريق محدّد المكان (location) الذي قمنا بتعيينه أثناء تسجيل القائمة. في حالتنا قمنا بوضع قيمة المحدد هي: our-custom-menu.
والوصف يتم استخدامه عند عرض القائمة في لوحة التحكم ليكون أنسب وأسهل للقراءة من محدد المكان، في حالتنا قمنا بوضع قيمة الوصف هي: القائمة الرئيسية.

يمكننا تسجيل أكثر من قائمة في آن واحد عن طريق استخدام دالّة register_nav_menus التي تستخدم بشكل مشابه لدالّة register_nav_menu لكن المحدّدات تكون على شكل مصفوفة اسميّة (Associative Array)، كل عنصر في المصفوفة يمثّل قائمة واحدة بحيث يكون مفتاح العنصر هو محدّد المكان وقيمة العنصر هي محدّد الوصف.

في قالبنا لا نحتاج سوى لقائمة واحدة، في ما يلي كيفية تسجيل أكثر من قائمة معًا:

add_action('init', function() {
    register_nav_menus([
        'our-custom-menu' => 'القائمة الرئيسية',
        'our-second-menu' => 'القائمة الفرعية',
    ]);
});

كما ننوه إلى وجود دالّة معاكسة لدالّة تسجيل القوائم هي unregister_nav_menu لكننا لن نتطرّق إليها الآن.

إظهار القائمة في القالب

الخطوة الأخيرة ضمن القالب هي عرضه في المكان المناسب.
في القالب الذي نستعمله نجد أن موقع القوائم أصبح في ملف header.php، في السطر 30 من الملف نجد وسم <section class="top-bar-section">، نريد أن نضع القائمة بدلاً من وسم <ul> الموجود بداخله.

نقوم بحذف وسم <ul> مع محتواه، ثم نستخدم السطر البرمجيّ التالي لعرض القائمة:

<?php wp_nav_menu(['theme_location' => 'our-custom-menu']); ?>

تقبل دالّة wp_nav_menu مُحدداً واحداً هو مصفوفة تحوي عددًا من الإعدادات، الإعداد الوحيد الضروري هو theme_location ويتم استخدامه كما في السطر البرمجي السابق. يمثل هذا المحدّد قيمة محدّد المكان السابقة التي استخدمناها أثناء تسجيل قائمة جديدة والتي كانت: our-custom-menu.
في حال لم يتم إدخال هذا المحدّد تقوم ووردبريس باستخدام قيمة إعداد menu (سنأتي إليه في الفقرة التالية)، وإن لم تجد قيمة فسيتم عرض أول قائمة غير فارغة تجدها ووردبريس، وفي حال عدم وجود أي قوائم غير فارغة وعدم تمرير محدّد المكان فلا يتم عرض شيء.

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

في الفقرة التالية سنتعرف على بقية الإعدادات التي يمكن أن نستخدمها مع دالّة wp_nav_menu والتي ستمكننا من إظهار القائمة على الشكل الأنسب.

إعدادات دالة wp_nav_menu

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

<?php
$defaults = array(
    'theme_location'  => '',
    'menu'            => '',
    'container'       => 'div',
    'container_class' => '',
    'container_id'    => '',
    'menu_class'      => 'menu',
    'menu_id'         => '',
    'echo'            => true,
    'fallback_cb'     => 'wp_page_menu',
    'before'          => '',
    'after'           => '',
    'link_before'     => '',
    'link_after'      => '',
    'items_wrap'      => '<ul id="%1$s" class="%2$s">%3$s</ul>',
    'depth'           => 0,
    'walker'          => ''
);

wp_nav_menu( $defaults );

?>

theme_location

• مكان القائمة ضمن القالب، كما تم تحديده أثناء تسجيل القائمة باستخدام دالّة register_nav_menu، ليكون بإمكان المستخدم تحديد القائمة المطلوبة للمكان الذي تم تسجيله (دون تقييد المستخدم بقائمة واحدة).
• القيمة الافتراضية: '' (سلسلة نصية فارغة)

menu

• القائمة المطلوب عرضها، تقبل قيمة المعرّف الرقمي (ID)، أو الاسم اللطيف (slug)، أو الاسم الخاص بالقائمة (وليس مكان القائمة ضمن القالب).
• القيمة الافتراضية: '' (سلسلة نصية فارغة)

container

• لتحديد إن كان مطلوبًا من ووردبريس إحاطة وسم <ul> بوسم آخر أم لا، القيمة المسموحة هي div أو nav، وفي حال عدم الرغبة بإحاطة القائمة بوسم نجعل القيمة false.
• القيمة الافتراضية: 'div'

container_class

• الصنف الخاص بوسم html المحيط بالقائمة، بشكل افتراضي يأخذ الصنف الشكل: menu-{menu slug}-container حيث يكون {menu slug} هو الاسم اللطيف للقائمة.
• القيمة الافتراضية: '' (سلسلة نصية فارغة)

container_id

• معرّف CSS (ID) الذي يتم تطبيقه على الوسم المحيط (container).
• القيمة الافتراضية: '' (سلسلة نصية فارغة)

menu_class

• الصنف الذي يتم تطبيقه على وسم القائمة <ul>، يمكن أن يتم وضع أكثر من صنف يتم الفصل بينهم بفراغات (space).
• القيمة الافتراضية: 'menu'

menu_id

• معرّف (ID) CSS الذي يتم تطبيقه على وسم القائمة <ul>. بشكل افتراضي تكون قيمته: menu-{menu slug} حيث {menu slug} هو الاسم اللطيف للقائمة؛ في حال حدوث تكرار بالاسم يتم إضافة إشارة - مع رقم مميز يبدأ من 1 ويزيد عند كل تكرار، مثلًا: menu-{menu slug}-1، menu-{menu slug}-2، إلخ.
• القيمة الافتراضية: '' (سلسلة نصية فارغة)

echo

• فيما إن كنا نريد إظهار القائمة مباشرة في مكان استخدام دالّة wp_nav_menu أو نريد إرجاعها (return).
• القيمة الافتراضية: true

fallback_cb

• دالّة ليتم استخدامها في حال لم تكن القائمة موجودة، نضع قيمتها false في حال لم نكن نريد استخدام دالّة. ويتم تمرير محدّد $args للدالّة التي يتم استخدامها.
• القيمة الافتراضية: 'wp_page_menu'

before

• إظهار نصّ قبل وسم <a>.
• القيمة الافتراضية: '' (سلسلة نصية فارغة)

after

• إظهار نصّ بعد وسم </a>.
• القيمة الافتراضية: '' (سلسلة نصية فارغة)

link_before

• إظهار نصّ قبل نصّ الرابط.
• القيمة الافتراضية: '' (سلسلة نصية فارغة)

link_after

• إظهار نصّ بعد نصّ الرابط.
• القيمة الافتراضية: '' (سلسلة نصية فارغة)

items_wrap

• يتم تفسيرها بنفس الطريقة التي يتم تفسير محدّد الهيئة (format) لدالّة sprintf.
• يحدث تعاون بين المحددات الأخرى عن طريق رموز رقمية. %1$s تُستبدل بقيمة محدد menu_id، %2$s تُستبدل بقيمة محدد menu_class، و %3$s تُستبدل بقيمة عناصر القائمة (وسوم <li>).
• إن تم استبعاد أي رمز رقمي من هذا المحدّد، سيتم استبعاد المحدّد المرتبط به من وسوم القائمة.
• القيمة الافتراضية: '<ul id="%1$s" class="%2$s">%3$s</ul>'

depth

• يمثل عدد المستويات الهرمية التي سيتم استخدامها، حيث رقم 0 يعني جميع المستويات. ويتم استخدام قيمة -1 لتحويل جميع المستويات إلى مستوى واحد فقط.
• القيمة الافتراضية: 0

walker

• يتم تمرير عنصر هو نسخة من صنف Walker_Nav_Menu أو من صنف يرث من ذلك الصنف.
• الهدف من هذا المحدد هو التحكم بشكل كامل بالأصناف (classes) والمحدّدات (IDs) ووسوم HTML للقائمة. يمكن العودة لتوثيق WordPress للاطلاع على المثال المقدم
• القيمة الافتراضية: '' (سلسلة نصية فارغة)

تحسين ظهور القائمة في القالب

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

إن شاهدنا مصدر HTML للصفحة الرئيسية من المتصفح، نجد أننا نحتاج لإزالة الوسم المحيط بالقائمة (container)، ونحتاج لإضافة صنف right لوسم <ul> المحيط بعناصر القائمة.

يمكننا تعديل السطر البرمجي في ملف header.php ليصبح:

<?php wp_nav_menu([
    'theme_location' => 'our-custom-menu',
    'container' => false,
    'menu_class' => 'right',
]); ?>

قمنا بجعل قيمة الوسم المحيط (container) تساوي false ﻷننا لا نريد إحاطة القائمة بأي وسم، فنحن من البداية نقوم بإحاطة القائمة بوسم <section> في قالب HTML الذي نستخدمه.
وقمنا أيضًا بإضافة قيمة محدد menu_class لتساوي: right، ليتم إضافة صنف right لوسم القائمة <ul> ليظهر بشكل جيّد.

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

الشريط الجانبي

الأشرطة الجانبية (Sidebars) هي إحدى ميزات القوالب، هو بشكل بسيط عمود شاقولي يقوم القالب بتزويده لعرض معلومات مختلفة عن المحتوى الأساسي للموقع، تقوم الأشرطة الجانبية بعرض ودجات/مربعات (widgets) يقوم مدير المدونة بالتحكم بها.

التعامل مع الشريط الجانبي يشبه إلى حدّ كبير التعامل مع القوائم.

تسجيل شريط جانبي

لنقم معاً بإضافة ما يلي إلى ملف functions.php لتعريف شريط جانبيّ جديد:

add_action('widgets_init', function() {
    register_sidebar();
});

إن قمنا بزيارة لوحة التحكم، نجد أن هناك عنصراً جديداً في قائمة المظهر (Appearance) هو الودجات (Widgets)، بداخله يظهر لنا الشريط الجانبي الجديد بعنوان الشريط الجانبي 1، إن قمنا بإضافة شريط جانبي آخر سيأخذ نفس الاسم لكن بزيادة الرقم بمقدار واحد. والسبب أننا عندما قمنا بتسجيل الشريط الجانبي لم نحدد له اسماً أو معرّفاً. سنقوم بهذا الآن بعد أن نتعرف على إعدادات هذه الدالّة.

إعدادات دالّة register_sidebar

الإعدادات الافتراضية:

$args = array(
    'name'          => sprintf( __( 'Sidebar %d' ), $i ),
    'id'            => "sidebar-$i",
    'description'   => '',
    'class'         => '',
    'before_widget' => '<li id="%1$s" class="widget %2$s">',
    'after_widget'  => "</li>\n",
    'before_title'  => '<h2 class="widgettitle">',
    'after_title'   => "</h2>\n",
);

شرح الإعدادات:

name

اسم الشريط الجانبي (القيمة الافتراضية هي ترجمة كلمة ‘Sidebar’ مع معرّف رقميّ).

id

معرّف الشريط الجانبي - يجب أن يكون بأحرف صغيرة (lowercase), دون فراغات (القيمة الافتراضية هي معرّف رقمية يتم زيادته تلقائياً ).

description

وصف نصّي لماهيّة/مكان الشريط الجانبي. يظهر في واجهة إدارجة الودجات في لوحة التحكم. (القيمة الافتراضية: فارغة)

class

صنف CSS ليتم إسناده للشريط الجانبي في صفحة إدارة الودجات، ولن يتم استخدام هذا الصنف في القالب.

ملاحظة: سيتم إضافة كلمة “sidebar” إلى قيمة الصنف. مثلاً: إن وضعنا اسم الصنف: tal ستكون قيمة الصنف هي: sidebar-tal. (القيمة الافتراضية: فارغة).

before_widget

وسم/وسوم HTML ليتم وضعها قبل كل واحد من الودجات (widget) (القيمة الافتراضية: ‘<li id="%1$s" class="widget %2$s">‘).
ملاحظة: يتم استخدام دالّة sprintf لاستبدال المتحولات.

after_widget

وسم/وسوم HTML ليتم وضعها بعد كل واحد من الودجات (widget) (القيمة الافتراضية: '\n').

before_title

وسم/وسوم HTML ليتم وضعها قبل كل عنوان (القيمة الافتراضية: <h2 class="widgettitle">).

after_title

وسم/وسوم HTML ليتم وضعها بعد كل عنوان (القيمة الافتراضية: “</h2>\n“).

عرض الشريط الجانبي في القالب

نتوجه إلى ملف sidebar.php، ونقوم بتعديله ليصبح كالتالي:

<div class="large-4 columns sidebar">
    <?php dynamic_sidebar(); ?>
</div>

قمنا باستبدال النصّ الموجود مسبقاً “Sidebar” بدالّة ()dynamic_sidebar التي وظيفتها عرض محتويات الشريط الجانبي في المكان المحدد.

يمكن أن نمرّر قيمة واحدة لتلك الدالّة إما أن تكون اسم (name) أو معرّف (ID) الشريط الجانبي. وفي حال عدم تمرير أي قيمة يتم عرض الشريط الجانبي الأول.

تخصيص الشريط الجانبي

كما لاحظنا فشكل ودجات الشريط الجانبي غير مقبولة، لنقم معًا بتحسين مظهرها عن طريق إحاطة كل واحدة من الودجات (widgets) بوسم <div class="card"> الذي كان موجودًا في ملف sidebar.php قبل استخدام دالّة عرض الشريط الجانبي.

لنقم باستخدام إعدادات دالّة ()register_sidebar التي مرّت معنا في الفقرات السابقة، في ملف functions.php نقوم بتعديل الدالّة لتصبح:

register_sidebar(['before_widget' => '<div class="card">', 'after_widget' => '</div>']);

قمنا بتمرير إعدادَين فقط لإضافة وسم div قبل واحدة من الودجات وإضافة إغلاق الوسم بعد كل واحدة منها.

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

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

عند وجود عدد كبير من المقالات في المدوّنة، فلن يتم عرضها جميعاً في صفحة واحدة، بل يتم تقسيمها على عدد من الصفحات، بشكل افتراضي يتم عرض 10 مقالات في الصفحة الرئيسية أو الأرشيف (تصنيف أو وسم)، ويمكن تغيير رقم المقالات في الصفحة الواحدة من لوحة التحكم.

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

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

Pagination

تقدّم ووردبريس دالّة مخصّصة لعرض أرقام الصفحات هي ()paginate_links. سنقوم بالاطلاع على كيفية استخدامها وخياراتها، وننوه بوجود طرق أخرى لعرض أرقام الصفحات، مثل إضافة WP-PageNavi.

يتم استخدام الدالّة بهذه الطريقة:

<?php echo paginate_links($args);?>

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

الإعدادات الكاملة هي كالتالي بقيمها الافتراضية:

<?php
$args = array(
    'base'               => '%_%',
    'format'             => '?page=%#%',
    'total'              => 1,
    'current'            => 0,
    'show_all'           => False,
    'end_size'           => 1,
    'mid_size'           => 2,
    'prev_next'          => True,
    'prev_text'          => __('« Previous'),
    'next_text'          => __('Next »'),
    'type'               => 'plain',
    'add_args'           => False,
    'add_fragment'       => '',
    'before_page_number' => '',
    'after_page_number'  => ''
);
?>

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

سنقوم الآن باستخدام هذه الدالّة ورؤية كيف تظهر الروابط دون وجود إعدادات للدالّة، نضع ما يلي في نهاية ملف index.php فيصبح:

    <div class="row">
        <div class="medium-12 columns">
            <?php echo paginate_links(); ?> 
        </div>
    </div>
</div>
<?php
get_sidebar();
?>

عندما نقوم بزيارة الصفحة الرئيسية للمدونة، نجد أن روابط أرقام الصفحات تظهر بشكل مشابه لهذه الصورة:

سنرى في الفقرة التالية كيف يمكن تخصيص ظهور هذه الروابط.

إضافة Style جديد

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

قد يتبادر للذهن في البداية أن يتم استخدام النسخ واللصق لإضافة Style جديد إلى ملف css الرئيسي. رغم أن هذا ممكن ويؤدي الغرض المطلوب، إلا أن الطريقة الأفضل هي استخدام دالّة تدعى wp_enqueue_style.

1. إضافة دالّة ()wp_head إلى ملف header.php

قبل إغلاق وسم </head> نقوم بإضافة السطر التالي:

<?php wp_head();?>

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

قمنا بإضافة دالّة wp_head ﻷننا نريد استخدام دالّة ()wp_enqueue_style التي ستقوم بإدراج وسم HTML لاستيراد ملف CSS جديد.

2. إضافة ملف CSS الجديد

نقوم بإنشاء ملف جديد هو custom.css، وهو الذي سنقوم باستدعاءه من خلال دالّة ()wp_enqueue_style.

نقوم بنسخ ولصق محتوى هذا الرابط ونضعه ضمن ملف custom.css الذي أنشأناه، وهو ما سيقوم بإضافة الشكل المناسب ﻷرقام الصفحات في القالب.

3. استخدام دالّة ()wp_enqueue_style

لنقم بفتح ملف  functions.php من ملفات القالب، ولنضف عليه ما يلي:

// Enqueue custom style
add_action('wp_enqueue_scripts', function() {
    wp_enqueue_style('custom-pagination', get_template_directory_uri() . '/custom.css');
});

ما قمنا بفعله هو أننا أخبرنا ووردبريس أن تنفذ دالّة ()wp_queue_style عند وصول دورة تنفيذ ووردبريس إلى الحدث (action)  المُسمّى wp_enqueue_scripts وهو المسؤول عن ترتيب وتنسيق وطباعة ملفات جافاسكريبت و CSS وتحليل متطلبات كل ملف -إن وجدت له متطلبات-، وفي النهاية يتم استخدام الملف/الملفات المطلوبة بعد أن يتم طلب جميع متطلباتها.

الآن إن قمنا بفتح المصدر الخاص بالصفحة الرئيسية من المتصفح، نجد أن المصدر أصبح يحوي شيئاً مشابهاً لما يلي:

<link rel='stylesheet' id='custom-pagination-css'  href='http://localhost:8000/wp-content/themes/my_theme/custom.css?ver=4.1' type='text/css' media='all' />

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

لننظر الآن كيف تبدو أرقام الصفحات:

أجمل بكثير من سابقتها أليس كذلك؟

شرح إعدادات دالّة paginate_links

كما أسلفنا، يمكن أن نمرر جزءًا من الإعدادات ويمكن ألا نمرر أي شيء على الإطلاق، فتقوم ووردبريس باستخدام الإعدادات الافتراضية التي أوردناها في الأعلى.

base

• (القيمة اختيارية)، نوعها سلسلة نصيّة.
• القيمة الافتراضية: %_%
• تُستخدم للإشارة إلى الرابط، الذي سيتم استخدامه لإنشاء روابط الصفحات.
• في رابط مثل: http://example.com/all_posts.php%_% يتم استبدال القيمة الافتراضية: %_% بقيمة format التي سنتحدث عنها في الفقرة التالية.

format

• (القيمة اختيارية)، نوعها سلسلة نصيّة.
• القيمة الافتراضية: ?page=%#%
• تُستخدم كهيكل للصفحات. في حال كنا نريد أو كنا نستخدم عناوين نظيفة (pretty permalinks) ستكون القيمة هي /page/%_%، حيث تعبير %_% يتم استبداله برقم الصفحة.

total

• (القيمة اختيارية)، نوعها رقميّ.
• القيمة الافتراضية: 1
• مجموع عدد الصفحات، عند استخدام دالّة ()paginate_links داخل حلقة ووردبريس، تكون القيمة الافتراضية تساوي خاصّية max_num_pages$ في WP_Query.

current

• (القيمة اختيارية)، نوعها رقميّ.
• القيمة الافتراضية: 0
• رقم الصفحة الحالية.

show_all

• (القيمة اختيارية)، نوعها قيمة منطقية (true أو false).
• القيمة الافتراضية: false
• إذا كانت القيمة true عندها سيتم إظهار جميع الصفحات بدلاً من قائمة قصيرة من الأرقام المجاورة لرقم الصفحات الحالية. بشكل افتراضي هذا الخيار تكون قيمته false ويتم التحكم به عن طريق الخيارين end_size و mid_size.

end_size

• (القيمة اختيارية)، نوعها رقميّ.
• القيمة الافتراضية: 1
• عدد الأرقام عند بداية ونهاية أطراف القائمة.

mid_size

• (القيمة اختيارية)، نوعها رقميّ.
• القيمة الافتراضية: 2
• عدد الأرقام على جانبيّ الصفحة الحالية، (مع ملاحظة أن الرقم لا يشمل الصفحة الحالية).

prev_next

• (القيمة اختيارية)، نوعها قيمة منطقية (true أو false).
• القيمة الافتراضية: true
• لتحديد إن كنا نريد روابط التالي والسابق أن يتم استخدامها في القائمة أم لا.

prev_text

• (القيمة اختيارية)، نوعها سلسلة نصّية.
• القيمة الافتراضية: __('« Previous') حيث __() هي دالّة مسؤولة عن الترجمة.
• نص رابط الصفحة السابقة، تعمل فقط إن كان الخيار السابق (prev_next) فعّالاً (قيمته true).

next_text

• (القيمة اختيارية)، نوعها سلسلة نصّية.
• القيمة الافتراضية: __('Next »') حيث __() هي دالّة مسؤولة عن الترجمة.
• نص رابط الصفحة التاية، تعمل فقط إن كان خيار (prev_next) فعّالاً (قيمته true).

type

• (القيمة اختيارية)، نوعها سلسلة نصّية.
• القيمة الافتراضية: ‘plain’
• تتحكم بشكل القيمة التي تقوم الدالّة بإرجاعها. القيمة الممكنة هي:
  • plain: تكون القيمة التي يتم ارجاعها عبارة عن سلسلة نصّية مؤلفة من روابط مفصول بينها بمحرف السطر الجديد.
  • array: تكون القيمة التي يتم ارجاعها عبارة عن مصفوفة من روابط الصفحات لتوفّر تحكم كامل بكيفية الظهور.
  • list: تكون القيمة التي يتم ارجاعها عبارة عن قائمة HTML غير مرتّبة (ul).

add_args

• (القيمة اختيارية)، نوعها مصفوفة.
• القيمة الافتراضية: false
• مصفوفة اسمية من المحددات ليتم إضافتها إلى الرابط، تكون المصفوفة على شكل: اسم => قيمة.

add_fragment

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

before_page_number

• (القيمة اختيارية)، نوعها سلسلة نصيّة.
• القيمة الافتراضية: لا يوجد قيمة.
• نص ليتم إظهاره قبل كل رقم صفحة (النص وليس الرابط).

after_page_number

• (القيمة اختيارية)، نوعها سلسلة نصيّة.
• القيمة الافتراضية: لا يوجد قيمة.
• نص لتتم إضافته بعد رقم الصفحة (النص وليس الرابط).

أزرار التالي والسابق

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

تقدّم ووردبريس دالّة واحدة لعرض الرابطين معاً (التالي - السابق) هي: posts_nav_links.

لنقم بوضع هذه الدالّة بدلاً من دالّة إظهار أرقام الصفحات التي تحدثنا عنها سابقاً:

<?php posts_nav_link(); ?>

يصبح القالب بهذا الشكل:

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

• sep$: (سلسلة نصية)، يمثل النصّ المعروض بين الرابطين.
  • القيمة الافتراضية: ' — '
• prelabel$: (سلسلة نصية)، اسم رابط الصفحة السابقة.
  • القيمة الافتراضية: '« Previous Page'
• nxtlabel$: (سلسلة نصية)، اسم رابط الصفحة التالية.
  • القيمة الافتراضية: 'Next Page »'

لنقم معاً بتعديل هذه الإعدادات لتصبح كالتالي:

<?php
    posts_nav_link(' - ', '&laquo; السابق', 'التالي &raquo;');
?>

تظهر لنا التعديلات في القالب كما يلي:

ما رأيكم لو نختم الدرس بخدعة بسيطة، نقوم من خلالها بجعل روابط التالي السابقة تظهر بشكل مشابه لأرقام الصفحات؟

سأخبركم بتلميح: تكمن الخدعة بالاستفادة من المحدد الأول sep$.

لنضع في البداية وسم ul محيطاً بدالّة ()posts_nav_links يأخذ نفس صنف CSS الموجود في أرقام الصفحات كما يلي:

<ul class="page-numbers">
    <?php
            posts_nav_link(' - ', '&laquo; السابق', 'التالي &raquo;');
    ?>
</ul>

الآن نريد إحاطة كِلا الرابطين بوسم li لكل رابط، يمكن أن نضع داخل وسم ul بداية وسم li ونضع قبل إغلاق وسم ul وسم إغلاق وسم li، فيصبح المصدر كالتالي:

<ul class="page-numbers">
    <li>
    <?php
        posts_nav_link(' - ', '&laquo; السابق', 'التالي &raquo;');
    ?>
    <li>
</ul>

ما فعلناه حتى الآن أننا أحطنا كلا الرابطين بوسم li واحد، لكننا نريد أن نحيط كل واحد من الرابطين بوسم مستقلّ، سنقوم باستبدال المحدد الأول $sep بـ: </li><li>.
بما أن محتوى هذا المحدد سيكون بين الرابطين بشكل دائم، فسنضع فيه إغلاق وسم li الأول يليه بداية وسم li الثاني.
فيصبح المصدر:

<ul class="page-numbers">
    <li>
    <?php
        posts_nav_link('</li><li>', '&laquo; السابق', 'التالي &raquo;');
    ?>
    <li>
</ul>

يصبح شكل الروابط كالصورة التالية:

خلاصة

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

كما تعرفنا بشكل بسيط على كيفية إضافة ملف CSS جديد باستخدام دالّة ()wp_enqueue_style.

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

الواجهة البرمجية للخيارات Options API

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

الدالة add_option

كما هو واضح من اسمها تمكننا دالة add_option من إضافة خيار جديد إلى قاعدة البيانات وهذه هي الصورة العامة لها

add_option( $option, $value, $deprecated, $autoload ); 

حيث:

• $option (مطلوب) : هو عبارة عن اسم الخيار ويجب أن لا يتعدى 64 حرفًا ويُستحسن أن يكون بالإنجليزية ويتم استخدام الشرطة السفلية (_) للفصل بين الكلمات.
• $value (اختياري): قيمة هذا الخيار وهي القيمة الفعلية التي تود استقبالها من المستخدم واستخدمها فيما بعد (وعموما القيمة التي تود حفظها).
• $deprecated (اختياري): تم التخلي عن هذا المعامل في النسخة 2.3 من ووردبريس.
• $autoload (اختياري): هنا تحدد ما إذا أردت أن يتم تضمين الخيار في object cache في كل تحميل للصفحة. وهي متعلقة بما يعرف بالكاش cache.

الدالة delete_option

delete_option عبارة عن الدالة العكسية للدالة السّابقة، حيث تقوم بمسح الخيار من قاعدة البيانات. والصورة العامة لهذه الدالة هي:

delete_option( $option ); 

حيث $option هو اسم الخيار الذي تود مسحه

الدّالة get_option

تستخدم الدّالة get_option لاسترجاع الخيارات من قاعدة البيانات وهذه هي الصورة العامة لاستخدامها

echo get_option( $option, $default );

حيث:

• $option (مطلوب): اسم الخيار الذي تود استرجاعه
• $default (اختياري): القيمة الافتراضية للخيار في حالة لم يتم إيجاد قيمته في قاعدة البيانات.

لاحظ أننا استخدمنا echo لعرض الخيار لكن يمكنك مثلا استرجاع الخيار وحفظه في أي متغير أو إجراء أي عملية عليه.

إذا لم يوجد الخيار المطلوب في قاعدة البيانات ولم يتم تحديد قيمة للمعامل $default يتم إرجاع القيمة FALSE.

هنالك مجموعة من الخيارات الخاصة بووردبريس والمحفوظة في جدول الخيارات يمكنك الوصول إليها من خلال الدالة get_option منها على سبيل المثال:

• admin_email: البريد الإلكتروني لمدير الموقع.
• blogname: اسم الموقع.
• siteurl: رابط الموقع

وغيرها.

الدالة update_option

تستخدم الدالة update_option لتحديث قيمة الخيار في قاعدة البيانات وتأخذ الصورة العامة

update_option( $option, $new_value );

حيث:

• $option (مطلوب): اسم الخيار المراد تحديثه.
• $new_value (مطلوب): القيمة الجديدة للخيار.

هذه الدالة تقوم بفحص ما إذا كان الخيار $option موجودًا مُسبقا في قاعدة البيانات وفي حالة عدم وجوده تقوم باستخدام الدالة add_option لإنشائه بالصّورة التالية

add_option('option_name', 'option_value')

وبالتالي يمكنك استخدامها لاختبار ما إذا كان الخيار موجودًا وإنشائه إن لم يكن موجودًا، لكن لاحظ أنك لن تستطيع تحديد المعامل $autoload عند إنشاء الخيار.

ترجع الدالة update_option القيمة TRUE في حالة تم تحديث قيمة الخيار بنجاح وترجع FALSE إذا لم يتم التحديث بنجاح.

الواجهة البرمجية للإعدادات Settings API

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

• الإعدادات: وهي الخيارات الفعلية والتي يتم حفظها في قاعدة البيانات وتستطيع الوصول إليها بعد ذلك عن طريق الدالة get_option التي تم شرحها أعلاه.
• الحقول Field: وهي حقول النموذج Form الذي يتم عرضه في صفحة الإعدادات والتي تمكن المستخدم من إدخال قيم البيانات.،
• الأقسام Section: وهي عبارة عن طريقة لتقسيم الإعدادات إلى مجموعات، أي أن كل مجموعة من الحقول يتم جمعها تحت قسم.

بعد إنشاء أقسام وحقول الإعدادات التي تريدها (سنرى طريقة عمل ذلك في الفقرات القادمة) عليك أن تقرر ما إذا كنت تريد إضافة هذه الحقول والأقسام إلى:

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

إنشاء صفحة خيارات في لوحة تحكم ووردبريس

يتم ذلك من خلال استخدام الدالة add_options_page التي لها الصورة العامة

add_options_page( $page_title, $menu_title, $capability, $menu_slug, $function);

حيث:

• $page_title (مطلوب): عنوان الصفحة.
• $menu_title (مطلوب): عنوان القائمة والذي سيظهر في لوحة تحكم ووردبريس.
• $capability (مطلوب): صلاحيات المستخدم الذي يستطيع التّعديل على هذه الصفحة.
• $menu_slug (مطلوب): الاسم اللطيف للقائمة (والذي سيظهر في رابط الصفحة).
• $function (اختياري): الدالة المسؤولة من عرض المحتويات في هذه الصفحة، أي التي سيناديها ووردبريس ويعرض ما تخرجه في هذه الصفحة.

يتم مناداة هذه الدالة (بالمعاملات المطلوبة) داخل دالة أخرى مثلا my_plugin_admin وتربط الدالة my_plugin_admin بالخطاف admin_menu وبهذه الطريقة ستظهر الصفحة في لوحة تحكم ووردبريس.

إنشاء قسم إعدادات Setting Section

لإنشاء قسم إعدادات حتى نربط به حقول الإعدادات نقوم باستخدام الدالة add_settings_section والتي لها الصورة العامة:

add_settings_section( $id, $title, $callback, $page );

حيث:

• $id (مطلوب): معرف فريد Unique لهذا القسم.
• $title (مطلوب): عنوان القسم.
• $callback (مطلوب): الدالة التي ستقوم بعرض محتويات هذا القسم من الحقول والتي عليك إنشاؤها لاحقا. ويجب أن تقوم الدالة بعمل echo لمحتويات القسم.
• $page (مطلوب): صفحة الخيارات التي سيتم إضافة هذا القسم لها (مثلا التي أنشأناها في الخطوة السابقة) ويجب أن تطابق قيمة هذا المعامل قيمة المعامل $menu_slug.

ملاحظة: دالة الـ callback تستقبل معاملًا واحدًا اختياريًّا وهو عبارة عن مصفوفة لها ثلاث عناصر، مثال:

add_settings_section(
   'myplugin_setting_section',
   'مثال لقسم إعدادت للإضافة',
   'myplugin_setting_section_callback_function',
   'my_plugin_admin_page'
);
function myplugin_setting_section_callback_function( $arg ) {
   // echo section intro text here
   echo '<p>المعرف: ' . $arg['id'] . '</p>'; // المعرف: myplugin_setting_section
   echo '<p>العناون: ' . $arg['title'] . '</p>'; // العنوان: مثال لقسم إعدادت للإضافة
   echo '<p>دالة الcallback: ' . $arg['callback'] . '</p>'; // دالة الcallback: myplugin_setting_section_callback_function
}

إنشاء حقول الإعدادات Settings Fields

يتم إنشاء حقول الإعدادات عن طريق الدالة add_settings_field والتي لها الصورة العامة:

add_settings_field( $id, $title, $callback, $page, $section, $args );

حيث:

• $id (مطلوب): معرف فريد للحقل.
• $title (مطلوب): عنوان الحقل.
• $callback (مطلوب): الدالة المسئولة من عرض الحقل. يتم تمرير معامل واحد لهذه الدالة وهو المصفوفة $args. ويجب على هذه الدالة أن تقوم بعمل echo لمخرجاتها.
• $page (مطلوب): الصفحة التي سيتم عرض الحقل فيها، ويجب أن يطابق $menu_slug الموجود في الدالة add_options_page.
• $section (اختياري): قسم الإعدادات الذي يتبع له هذا الحقل.
• $args (اختياري): معاملات إضافية يتم تمريرها لدالة الـcallback.

تسجيل الإعدادات

الخطوة التالية هي أن نُعلم ووردبريس بأننا نريد تسجيل إعدادات للإضافة وذلك من خلال استخدام الدالة register_setting والتي لها الصورة العامة:

register_setting( $option_group, $option_name, $sanitize_callback );

حيث:

• $option_group (مطلوب): هذا عبارة عن اسم لمجموعة الخيارات ويستخدم فيما بعد عند عرض render محتويات صفحة الإعدادات.
• $option_name (مطلوب): اسم الخيارات والذي سنستخدمه في الدالة get_option لاسترجاع الخيارات.
• $sanitize_callback (اختياري): الدالة المسؤولة من عمل sanitizes للخيارات.

يجب أن يربط تسجيل الخيارات بالخطاف admin_ini بالصورة التالية

function register_my_setting() {
   register_setting( 'my_options_group', 'my_option_name', 'intval' );
}
add_action( 'admin_init', 'register_my_setting' );

مثال متكامل لإنشاء صفحة الخيارات وإضافة الإعدادات لها

add_action( 'admin_menu', 'my_plugin_menu' );
function my_plugin_menu() {
   add_options_page( 'عنوان صفحة الإضافة', 'عنوان القائمة', 'manage_options', 'my_plugin_admin_page', 'my_plugin_options_page' );
}
// ------------------------------------------------------------------

// أنشاء الحقول والأقسام وتعريف الإعدادات يربط بالخطاف admin_init

// ------------------------------------------------------------------

//
function myplugin_settings_api_init() {
// إضافة قسم الإعدادات لصفحة الخيارات التي عرفناها أعلاه
add_settings_section(
   'myplugin_setting_section',
   'مثال لقسم إعدادات للإضافة',
   'myplugin_setting_section_callback_function',
   'my_plugin_admin_page'
);
// إضافة حقل الخيارات
add_settings_field(
   'myplugin_setting_name',
   'مثال لاسم الحقل',
   'myplugin_setting_callback_function',
   'my_plugin_admin_page',
   'myplugin_setting_section'
);
// تسجيل الخيارات حتى يستطيع ووردبريس حفظ الإعدادات لنا
register_setting( 'my_plugin_admin_page', 'myplugin_setting_name' );
}
// إضافة الدالة أعلاة للخطاف المناسب وهو admin_init
add_action( 'admin_init', 'myplugin_settings_api_init' );
// ------------------------------------------------------------------

// دالة الcallback لقسم الإعدادات

// ------------------------------------------------------------------
function eg_setting_section_callback_function() {
   echo '<p>نص في بداية قسم الإعدادات</p>';
}
// ------------------------------------------------------------------
// دالة الcallback لحقل الإعدادات

// ------------------------------------------------------------------add_options_page
// إنشاء مربع إختيار checkboxز بالطبع يمكنك إنشاء أنواع أخرى من الخقول

function eg_setting_callback_function() {
   echo '<input name="myplugin_setting_name" id="myplugin_setting_name" type="checkbox" value="1" class="code" ' . checked( 1, get_option( 'eg_setting_name' ), false ) . ' /> مصال';
}

// الدالة المسؤولة عن عرض بيانات صفحة خيارات الإضافة كما عرفناها اعلاه
function my_options_page() {
?>

<div class="wrap">
   <h2>صفحة خيارات الإضافة</h2>
   <form action="options.php" method="POST">
      <?php settings_fields( 'my_plugin_admin_pagep' ); ?>
      <?php do_settings_sections( 'myplugin_setting_section' ); ?>
      <?php submit_button(); ?>
   </form>
</div>
<?php
}

في البداية قمنا بإنشاء صفحة الخيارات عن طريق الدالة add_options_page وكما تلاحظ قمنا بوضعها داخل دالة وإضافة الدالة للخطاف المناسب وهو admin_menu.

بعد ذلك قمنا بعمل دالة جديدة وبداخلها قمنا بعمل ثلاثة أشياء وهي:

• إضافة قسم إعدادات عن طريق الدالة add_settings_section، وبالطبع قمنا بتعريف دالة الـcallback الخاصة بهذا القسم والمسؤولة من عرضها وقمنا بإضافتها بعد هذه الدالة.

• إضافة حقل واحد للإعدادات عن طريق الدالة add_settings_field ومررنا لها اسم دالة الـcallback المسؤولة عن عرض هذا الحقل والتي أضفناها بعد هذه الدالة.

• تسجيل الإعدادات عن طريق الدالة register_setting لنخبر ووردبريس عن هذه الإعدادات حتى يقوم بعملية حفظ هذه الإعدادات بالنيابة عنا.

بعد ذلك قمنا بإضافة هذه الدالة إلى الخطاف المناسب وهو الخطاف admin_init.

أخيرًا قمنا بإنشاء الدالة المسؤولة من عرض محتويات صفحة الخيارات وكما تلاحظ استخدمنا فيها الدالة do_settings_sections والتي تضيف أقسام الإعدادات المرتبطة بهذه الصفحة وكذلك الدالة settings_fields المسؤولة عن إخراج ما يعرف ب nonce وهو متعلق بتأمين النموذج form. وأخيرًا قمنا بمناداة الدالة submit_button والتي ستعرض زر الحفظ.

استرجاع البيانات

لاسترجاع بيانات الإضافة حتى تستخدمها يمكنك استخدام الدالة التي عرفناها سابقا وهي get_option حيث سنمرر لها اسم الخيارات $option_name الذي عرفناه سابقا خلال تسجيل الإعدادات من خلال الدالة register_settings.

خاتمة

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

كما ذكرنا في الدرس السابق (مدخل إلى برمجة إضافات ووردبريس) من هذه السلسلة فإن الخطّافات تعد من أهم الخصائص التي يوفرها ووردبريس والتي جعلته مرنًا flexible وقابل للتمدد extensible بصورة قل أن تجد لها نظيرًا في برمجيات الويب حيث يعتمد على توفير نقاط ربط تمكن المطورين من تنفيذ الدّوال التي يريدونها أثناء دورة حياة ووردبريس، وذلك باعتماده على معمارية Event Driven.
يوفر ووردبريس للمطورين الاستفادة من هذه الميزة من خلال ما يعرف بالواجهة البرمجية للإضافة Plugin API والتي نحن بصدد الإطلاع على أهم الدّوال التي توفرها في جانبي الإجراءات Actions والمُرشّحات Filters وبعض الأمثلة التوضيحية التي ترسخ فهم هذه الدّوال والمفاهيم المتعلقة بها.

الإجراءات في ووردبريس

الدالة add_action

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

add_action( $hook, $function_to_add, $priority, $accepted_args );

حيث:

• $hook : هو الحدث الذي تريد أن تربط به الدالة الخاصة بك، أي الحدث التي تريد أن تنفذ دالتك عند حدوثه. ويمكنك الإطلاع على الأحداث التي يوفرها ووردبريس من هنا.
• $function_to_add:اسم الدالة (الإجراء) التي تريد إضافتها للحدث أعلاه. أي التي ستنفذ عند حصول الحدث $hook .
• $priority (اختياري): هذه هي أولوية تنفيذ الدالة عند هذا الحدث، بمعنى أنه إذا كان هنالك أكثر من دالة تم إضافتها باستخدام الدالة add_action إلى نفس الحدث فإن قيمة هذا المعامل ستحدد أي الدّوال ستنفذ أولا وأيها ثانيا وهكذا. قيمة هذا المعامل يجب أن تكون من النوع int، وقيمته الافتراضية 10 والحدث ذو القيمة الأقل سينفذ أولا، بمعنى أن الدالة التي لديها قيمة 5 ستنفذ قبل الدالة التي لديها 20 وهكذا.
• $accepted_args (اختياري): عدد المعاملات التي تقبلها الدالة المطلوب تنفيذها $function_to_add، فمثلا الإجراء publish_post يقوم بتمرير معرف المقال الذي تم نشره للدالة المطلوب تنفيذها. وعادة يتم تحديد هذه من قبل الخطاف نفسه.

استخدام add_action مع الفئات Classes

أحيانًا قد تود استخدام الدالة add_action لإضافة دالة تابعة لفئة أو لكائن Object معين حينئذ ينبغي عليك استخدام add_action كما في المثال التالي:

class MyPluginClass {
   public function __construct() {
      add_action( 'save_post', array( $this, 'myplugin_save_posts' ) );
   }
   public function myplugin_save_posts() {
      // do stuff here...
   }
}
$mypluginclass = new MyPluginClass();

وتلاحظ أننا استخدمنا اسم الحدث save_post وفي المعامل الثاني أشرنا إلى الدالة من خلال المصفوفة

array( $this, 'myplugin_save_posts' )

حيث تشير $this إلى الكائن الحالي وmyplugin_save_posts تشير إلى اسم الدالة التي نود إضافتها للحدث.

الدالة remove_action

تعُتبر دالة remove_action الدالة العكسية للدالة add_action حيث تقوم بحذف الدالة التي تريدها من الحدث الذي تريده وتأخذ الصّيغة العامة التالية:

remove_action( $tag, $function_to_remove, $priority );

حيث:

• $tag : اسم الحدث الذي تم إضافة الدالة إليه
• $function_to_remove : الدالة التي تود حذفها من الحدث $tag
• $priority (اختياري): أولوية الدالة التي تريد حذفها والتي تم تعريفها مسبقا عند إضافة الدالة إلى الحدث عن طريق add_action

الدالة has_action

تستخدم دالة has_action لاختبار إذا كانت دالة معينة قد أضيفت إلى حدث معين، والصّيغة العامة لهذه الدالة هي:

has_action( $tag, $function_to_check )

حيث

• $tag : الحدث الذي تود معرفة إذا ما كانت الدالة قد أضيفت إليه.
• $function_to_check : الدالة التي تود معرفة إذا ما كانت أضيفت إلى الحدث $tag أما لا.
• القيمة المرجعة من الدالة: ترجع هذه الدالة قيمة false إذا كانت الدالة $function_to_check غير مضافة للحدث $tag وترجع أولوية تنفيذها priority إذا كانت مضافة للحدث $tag.

الدالة do_action

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

 do_action( $tag, $arg );

حيث:

• $tag : اسم الإجراء الذي تود تنفيذه. وكما أسلفنا فإن هذه الدالة عند مناداتها ستنفذ كل الدّوال التي تم إضافتها لهذا الحدث $tag.
• $arg (اختياري): المعامل الذي يتم تمريره للدوال المرتبطة بالحدث $tag

هذه الدالة في الأساس يستخدمها ووردبريس ليحدد مكان تنفيذ الأحداث التي يوفرها لكن يمكنك أيضا استخدامها لإنشاء أحداث خاصة بك في حالة أردت مثلا أن تتيح للمطورين نقاط معينة داخل إضافتك (أو قالبك) لينفذوا فيها دوالهم الخاصة، وبهذه الطريقة يمكن إنشاء إضافات قابلة لتشتغل عليها إضافات أخرى أو ما يمكن أن نطلق عليه اسم Extensions وهنالك عدة أمثلة لإضافات ناجحة توفر هذه الميزة نذكر منها على سبيل المثال إضافة Bbpress المشهورة وكذلك إضافة Woocommernce حيث أن هاتين الإضافتين تعمل فوقهما عدة إضافات أخرى تزيد من مميزاتهما، وتقريبا معظم إضافات ووردبريس توفر مجموعة من الخطافات hooks للمطورين، لذلك في حالة فكرت في إنشاء إضافة لنشرها في مجتمع ووردبريس من الجيد أن تجعل نظرتك مستقبلية وتوفر بعض الخطافات للمطورين.
يحسن التنبيه إلى أن الدالة do_action يمكن أن تستدعى بأكثر من معامل بالصّيغة التالية

do_action( $tag, $arg_a, $arg_b, $etc );

وكما أسلفنا في تعريف معاملات الدالة add_action تستطيع تحديد المعاملات التي تقبلها الدالة المضافة إلى add_action، ولتحديد القيمة هناك عليك أن ترى عدد المعاملات الموجودة هنا في do_action.

أمثلة عملية للخطافات في ووردبريس

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

في ووردبريس إذا أردت أن تضيف ملف جافاسكربت للموقع فإن أفضل طريقة -غالبًا- هي استخدام الحدث wp_enqueue_scripts والذي تستطيع من خلاله إضافة ملفاتك إلى بقية ملفات جافاسكربت (أو CSS) وتترك لووردبريس مهمة ربطها في ترويسة الموقع وهذا ما تفعله الشيفرات التالية

function my_scripts_method() {
   wp_enqueue_script(
   'myscript', // اسم ملف جافاسكربت
   plugins_url( '/js/newscript.js' , __FILE__ ) // مكان ملف الجافاسكربت
);
}
add_action( 'wp_enqueue_scripts', 'my_scripts_method' );

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

إضافة قائمة جانبية Sidebar جديدة

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

function create_my_widget() {
 register_sidebar(array(
 'name' => __( 'My Sidebar'), 			// اسم القائمة الجانبية  
 'id' => 'my_sidebar',					// معرف القائمة الجانبية
 ));
}
add_action( 'widgets_init', 'create_my_widget' );

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

إنشاء خطاف إجراء action hook خاص بك

لعمل ذلك كل ما عليك هو إضافة الدالة do_action إلى المكان الذي تود أن تنفذ فيه الدّوال التي تربط بهذا الخطاف وبالطبع ستمرر للدالة do_action الاسم الذي تود أن تسمي به الخطاف، بالصّيغة التالية

do_action('my_action_hook');

وبالطبع يمكنك إضافة بقية المعاملات التي ذكرناها في تعريف الدالة do_action كلما اقتضت الحاجة.

المرشحات في ووردبريس

بنفس الطريقة التي اتبعناها في الأحداث أعلاه سنتعرف على أهم الدّوال الخاصة بالمرشحات التي يوفرها ووردبريس

الدالة add_filter

تستخدم دالة add_filter لإضافة مرشح جديد لأحد المتغيرات وتأخذ الصّيغة العامة:

add_filter( $tag, $function_to_add, $priority, $accepted_args );

لاحظ أن الدالة شبيهة جدا بالدالة add_action وكذلك المعاملات هي نفسها تقريبا، لكن لا باس من إعادة تعريفها:

• $tag: اسم خطاف المرشح filter hook الذي تود أن تضيف له الدالة $function_to_add لكي تعدل على قيمة المتغير الذي يمثله الخطاف.
• $function_to_add: الدالة التي ستتولى عملية التعديل على المتغير الذي يشير اليه الخطاف $tag. وهذه الدالة تقوم بإرجاع القيمة الجديدة للمتغير الذي تستقبله.
• $priority : أولوية التنفيذ للدوال المضافة لنفس الخطاف، حيث تحدد قيمة هذا المتغير ترتيب تنفيذ الدّوال المرتبطة بهذا المرشح. ويأخذ المتغير $priority قيمة من النوع int.
• الدّوال التي لها $priority أقل تنفذ أولا، وإذا كان هنالك أكثر من دالة لها نفس قيمة المتغير $priority حينئذ يتم تنفيذها على حسب ترتيب تعريفها.
• $accepted_args: عدد المعاملات arguments التي تقبلها الدالة $function_to_add. حيث يمكن تعريف أكثر من معامل للخطاف عند تنفيذه من خلال apply_filters كما سنرى في الفقرات القادمة. وعدد المعاملات عادة يتم تحديد من خلال الخطاف نفسه.

الدالة remove_filter

كما يظهر من اسمها فإن remove_filter الدالة العكسية لـadd_filter وتأخذ الصّيغة التالية

remove_filter( $tag, $function_to_remove, $priority );

حيث:

• $tag: اسم خطاف المرشح الذي تود إزالة الدالة عنه.
• $function_to_remove: اسم الدالة التي تود إزالتها.
• $priority (اختياري): أولوية الدالة التي تود إزالتها كما تم تعريفها باستخدام add_filter

الدالة has_filter

تقوم الدّالة has_filter باختبار ما إذا كان هنالك دالة تم إضافتها لخطاف معين، وتأخذ الصّيغة التالية

has_filter( $tag, $function_to_check ); 

حيث:

• $tag: اسم خطاف المرشح.
• $function_to_check: اسم الدالة التي تريد التأكد من وجودها

الدالة apply_filters

تقوم دالة apply_filters  بتنفيذ الدّوال المرتبطة بالخطاف الذي يمرر لها كمعامل وتأخذ الصّيغة العامة

apply_filters( $tag, $value, $var ... ); 

حيث:

• $tag : اسم الخطاف المراد تنفيذ الدّوال التي تم إضافتها له من خلال add_filter
• $value : القيمة الأصلية للمتغير والتي يتم تغيرها من خلال الدّوال المربوطة بالخطاف، أي القيمة التي ترشح من خلال الدّوال.
• $var (اختياري): متغير إضافي أو أكثر يتم تمريرها إلى الدّوال المرتبطة بالخطاف $tag وكنا قد ذكرنا أنه بالإمكان تحديد عدد المتغيرات التي تستقبلها الدالة المربوطة بالخطاف من خلال المعامل $accepted_args للدالة add_filter حيث تقوم بعد المعاملات هنا وتحديد عددها عند إضافة أي دالة لهذا الخطاف.

أمثلة للمرشحات في ووردبريس

تعديل عدد كلمات المقتطف

في هذا المثال سنستخدم الخطاف excerpt_length الذي يوفره ووردبريس للتعديل على قيمة طول نص المقتطف

function excerpt_length_example( $words ) {
 return 15;
}
add_filter( 'excerpt_length', 'excerpt_length_example' );

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

إنشاء خطاف مرشح filter hook لأحد متغيراتك

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

$text = apply_filters("my_text", $text);

بهذه الصورة فإنه سيقوم ووردبريس بتطبيق جميع الدّوال المضافة للخطاف my_text على المتغير $text في الجانب الأيمن من المعادلة قبل إسناده للمتغير في الجانب الأيسر، وهذا هو المطلوب.

أسماء الخطافات المتغيرة Variable Hook Names

الخطافات التي اطلعنا عليها أعلاه ليست كل ما يوفره ووردبريس بل هنالك المزيد من المرونة المتاحة من خلال أسماء الخطافات المتغيرة فمثلا لنلقى نظرة على الخطاف publish_post وهو عبارة عن خطاف حدث action hook يوفره ووردبريس ويتم تنفيذ الدّوال المرتبطة به كلما تم نشر publish مقال post وهذا في الحقيقة خطاف جميل جدا يمكنك من تنفيذ أي دالة تريدها عندما يتم نشر أي مقال لكن ماذا إن أردت تنفيذ دالة معينة عند نشر نوع مقالات مخصص ولتكن مثلا منتجات، أي نريد تنفيذ الدالة my_function عندما يتم نشر publish منتج product، هذا الأمر انتبه له المطورون ولذلك قاموا بإضافة هذا الخطاف ذو الاسم العام

{$new_status}_{$post->post_type}

وكما ترى فإنه يوفر مرونة عالية جدا حيث يمكنك اختيار الحالة التي تريد التنفيذ عنها وأصبح الأمر ليس مقتصرا على النشر فقط publish بل يمكنك مثل تنفيذ شئ معين عند حذف delete مقال أو عموما تغير حالة المقال إلى أي حالة {$new_status}. كما أن الأمر لم يعد مقتصرا على المقالات فقط بل يمكنك تحديد نوع المقال {$post->post_type} وهكذا اصبح الخطاف publish_post حالة خاصة من خطاف أعم له الاسم العام {$new_status}_{$post->post_type}.
هذا مثال واحد فقط لأسماء الخطافات المتغيرة وهنالك خطافات متغيرة غيره يوفرها ووردبريس لإتاحة المزيد من المرونة للمطورين.

خاتمة

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

مقدمة

من أهم أسباب انتشار ووردبريس وسيطرته على سوق أنظمة إدارة المحتوى هو الكم الهائل من إضافاته المجانية والمدفوعة والتي تقدم العديد من الخصائص والمميزات والتحسينات الإضافية التي لا تتوفر بصورة افتراضية في قلب ووردبريس WordPress Core.
في هذا المقال سنتعرف سوّيًا على أساسيات إنشاء إضافة لووردبريس لكن قبل الدخول في لب الموضوع دعنا نجب على سؤال مُهمّ وكذلك تعريف إضافات ووردبريس.

لماذا ننشئ إضافات ووردبريس

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

تعريف إضافات ووردبريس

إضافة ووردبريس عبارة عن دالة أو مجموعة دوال (حزمة شيفرات code package) مكتوبة بلغة php تقوم بإضافة بعض الخصائص لنظام إدارة المُحتوى. وتندمج شيفرات الإضافة معه من خلال واجهة برمجية API يوفرها له.
بالإضافة لملفات php يمكن أن تحتوي الإضافة على ملفات أخرى مثل ملفات JavaScript, CSS وبعض الصور.

إنشاء إضافة ووردبريس

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

اختيار اسم الإضافة

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

إنشاء مجلد الإضافة

بعد اختيار اسم الإضافة تقوم بإنشاء مجلد لها بالاسم الذي اخترناه ويكون هذا المجلد داخل مجلد  plugins الخاص بالإضافات والموجود داخل مجلد wp-content كما موضح بالصّورة.
يمكنك إنشاء ملف php بنفس الاسم بدلًا عن إنشاء مُجلّد كامل لكن يُفضّل أن تنشئ مُجلّدًا خاصًّا حتى يستوعب بقية ملفات الإضافة، ما لم تكن الإضافة تحتوي على ملف php واحد فقط.

إنشاء الملف الأساسي للإضافة

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

    <?php
    /**
     * Plugin Name: هنا تكتب اسم الإضافة والذي يجب أن يكون فريدًا
     * Plugin URI: هنا تكتب رابط موقع الإضافة
     * Description: هنا نبذة مختصرة عن الإضافة
     * Version: رقم نسخة الإضافة، مثلا 1.0.0
     * Author: اسم مطور الإضافة
     * Author URI: رابط موقع مطور الإضافة
     * License: اسم رخصة الإضافة
     */

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

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

قبل أن تبدأ في برمجة الإضافة تحتاج لمعرفة بعض الأمور العامة في برمجة ووردبريس بالإضافة لبعض التسهيلات التي يقدمها ووردبريس للمبرمجين مثل الواجهات البرمجية الجاهزة WordPress API's.

الخطافات في ووردبريس WordPress Hooks ( الدخول الى عمق ووردبريس)

من أهم المفاهيم في ووردبريس مفهوم الخطافات hooks والتي تنقسم إلى قسمين: الأحداث actions والمُرشّحات filters.

1- الإجراءات في ووردبريس WordPress Actions

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

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

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

       add_action('my_action', 'my_function');

1-1مثال للإجراءات في ووردبريس

فلنأخذ هذا المثال الذي يقوم بإرسال بريد إلى مدير الموقع (الدالة المراد تنفيذها) كلما نشر مقالًا جديدًا (الحدث الذي تنفذ عنده الدالة)

           add_action('publish_post', 'email_admin');
        function email_admin(){
                // هنا يتم إرسال البريد الإلكتروني إلى مدير الموقع
        }       

2-المرشحات في ووردبريس WordPress Filters

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

يتم إضافة فلتر معين my_filter  لبيانات معينة my_data  من خلال الدّالة add_filter بالطريقة التالية

    add_filter( 'my_data', 'my_filter' );

حيث أن my_filter هي الدّالة التي ستقوم بالتعديل على البيانات ويتم تمرير البيانات لها من قبل ووردبريس أي أنها يجب أن تستقبل my_data كمعامل parameter.

2-1مثال للمرشحات في ووردبريس
هذا المثال يقوم بتعديل محتوى المقال the_content حيث يقوم بإضافة التّوقيع لمُحتويات كل مقال في الموقع

    add_filter ( 'the_content', 'add_signiture' );
    function add_signiture($the_content){
    // هنا نقوم بإضافة الشيفرات التي تضيف التّوقيع لمحتويات المقال
        return $the_content;   // بعد ذلك تقوم الدّالة بإرجاع القيم الجديدة لمحتويات المقال
    }

هذه نظرة سريعة فقط على الخطافات في ووردبريس ولكن ما زال هنالك العديد من الأشياء المتعلقة بهذه الآلية الرّائعة التي يوفرها ووردبريس منها:

• إمكانية إضافة الـhooks الخاصة بك.
• تعديل أولوية تنفيذ الدّوال التابعة لنفس الـhook.
• ويمكنك التعرف على المزيد حول موضوع الخطافات في التّوثيق الرسمي لPlugin API

وسوم القالب Template Tags

قد تبدو الترجمة الحرفية مُضلّلة نوعًا ما خصوصا إذا علمت أن المقصود من وسوم القالب هو مجموعة من الدّوال الجاهزة التي يوفرها ووردبريس والتي تختصر لك الكثير من العمل، لذلك من الجيد أن تلقي نظرة عليها قبل البدء في برمجة الإضافة الخاصة بك. الجدير بالذّكر أن يتم استخدام كثير من هذه الدّوال داخل الحلقة الخاصّة بجلب المقالات في ووردبريس WordPress Loop والتي تستخدم بكثرة في القوالب، ولعل هذا هو سرّ تسميتها بوسوم القالب.

حفظ بيانات/ الإضافة في قاعدة البيانات

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

1- استخدام آلية "الخيارات options" التي يوفرها ووردبريس

 وهذه الطريقة مناسبة في حالة كون البيانات المراد حفظها صغيرة نسبيا ولا تتغير كثيرا مثل البيانات التي تتوقع من مدير الموقع إدخالها بعد تنصيب الإضافة مباشرة (خيارات الإضافة) والتي نادرا ما تتغير. في هذه الطريقة يتم حفظ بيانات الإضافة في جدول wp_options والذي يستخدمه ووردبريس لحفظ خياراته الخاصة.

2-استخدام البيانات الوصفية الخاصة بالمقالات Post Meta

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

3-استخدام الفئات المخصّصة

 وهذه مناسبة لتصنيف البيانات مثل تصنيف المقالات أو المستخدمين أو التعليقات.

4- إنشاء جدول جديد في قاعدة البيانات

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

الاستفادة من الواجهات البرمجية API's التي يوفرها ووردبريس

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

• Plugin API: تتيح لك الدّوال المستخدمة في الاستفادة من ميكانيكية الخطافات وكذلك الدّوال المساعدة لإنشاء الخطافات الخاصة بك.
• Database API : واجهة برمجية تسهل التعامل مع قاعدة بيانات ووردبريس.
• Rewrite API: تتيح لك إمكانية تغير صيغة روابط المقالات والموقع عموما والتحكم فيها.
• Filesystem API: للتعامل مع نظام الملفات في نظام التشغيل.

وغيرها الكثير من الواجهات البرمجية ويمكنك الإطلاع عليها من هنا

أمور عامة عليك مراعاتها عند برمجة الإضافة

1- الاهتمام بأمن الشيفرة Code Security

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

  defined( 'ABSPATH' ) or die( 'ممنوع الوصول المباشر' );

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

2- ملف اقرأني Readme File

هو ملف تقوم بتضمينه في مجلد الإضافة باسم readme.txt  ويستخدمه مستودع الإضافات لأخذ بعض المعلومات بالإضافة للمعلومات التي تظهر في صفحة الإضافة في المستودع، يمكنك استخدام هذا المُوّلد لإنشائه 

3- جعل الإضافة قابلة للترجمة

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

4- استخدام معايير تطوير وودبريس

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

5- تحديث الإضافة

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

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