إنشاء لوحة تحكم لقالب الووردبريس 2

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

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

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

 <?php register_setting( $option_group, $option_name, $sanitize_callback ); ?>

وكما تلاحظ فإنها تستقبل ثلاثة معاملات وهي:

• option_group: عبارة عن string تمثل إسم مجموعة الخيارات التي تنتمي لها الخيارات التي تود تسجيلها (يمكنك إدراج أكثر من خيار في نفس المجموعة) وهو الإسم الذي سنستخدمه لإسترجاع الخيارات الخاصة بنا بإستخدام الدالة get_option .
• option_name: إسم الخيارات الخاصة بنا.
• sanitize_callback: دالة المناداة المسئولة من عمل Sanitization للخيارات (عملية ال Sanitization في php عبارة عن عملية التأكد من أن البيانات المدخلة لها الصيغة التي نريدها بالضبط) وعموما لن نركز على هذا الامر كثيرا لان مهمتنا شرح الجانب الخاص بالووردبريس وليس php.

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

add_action('admin_init', 'register_and_build_fields');
function register_and_build_fields() {
   register_setting('theme_options', 'theme_options', 'validate_setting');
}

لاحظ اننا أضفنا الدالة register_and_build_fields  الى الحدث admin_init بالتالي سيتم مناداتها عندما يحصل الحدث admin_init أي عندما يبدأ الووردبريس تنفيذ الأكواد المسئولة من عرض لوحة التحكم الخاصة به وهو وقت مناسب لنخبر الووردبريس ان لدينا إعدادات نود تسجيلها (يمكنك الإطلاع على مفهوم الأحداث في هذا الموضوع).
هذه الدالة register_and_build_fields  التي أضفنها للحدث اعلاه قمنا بداخلها بتسجيل الإعدادات الخاصة بنا. حيث أخترنا الإسم theme_options كإسم لمجموعة الخيارات وللخيارات نفسها. كما عرفنا دالة التحقق التي ستقوم بعمل الSanitization وأعطيناها الإسم validate_settings  ومن المفروض ان نعرفها خارج الدالة register_and_build_fields بهذه الطريقة:

function validate_setting($plugin_options) {
  return $plugin_options;
}

وكما ذكرنا فمن المفترض ان تقوم هذه الدالة بإستقبال الخيارات والتحقق منها قبل حفظها في قاعدة البيانات لكننا لن نتطرق لهذا الامر بتوسع (لانه من أساسيات php) وسنكتفي في هذه الدالة بإستقبال الخيارات وإرجاعها كما هي ^^.

حتى الان أصبح الووردبريس يعرف ان لدينا إعدادات إسمها theme_options وسيقوم بحفظها في قاعدة الووردبريس عندما ترسل له كما اننا سنتمكن من إسترجاعها بهذه الطريقة لإستخدامها في القالب:

$options = get_option('theme_options');echo $options['value'];

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

إضافة حقول الإعدادات:

لإضافة الحقول الخاصة بالإعدادات سنقوم بإستخدام الدالة add_settings_field  والتي لها الصورة العامة

<?php add_settings_field( $id, $title, $callback, $page, $section, $args ); ?>

كما تلاحظ تستقبل هذه الدالة 6 معاملات وهي كالأتي:

• id: وهو عبارة عن المعرف الخاص بالحقل ويجب أن يكون فريدا unique.
• title: إسم الحقل وهو بصورة أساسية سيمثل الlabel الخاص بالمدخلات.
• callback: دالة المناداة المسئولة من إنشاء الحقل نفسه، أي أننا سنستخدم هذه الدالة لعمل echo للhtml الخاصة بالحقل.
• page: وهي الصفحة التي يتبع لها هذا الحقل (أي في أي صفحة سيتم إضافة هذا الحقل) لذلك سنستخدم إسم الصفحة التي انشأناها من قبل (صفحة الخيارات).
• section: القسم الذي يتبع له الحقل في الصفحة المعنية حيث أن أي حقل لابد أن يتبع لقسم إعدادات ويتم إضافة قسم الإعدادات من خلال الدالة add_settings_section كما سنرى.
• args: (إختياري) المعاملات التي سيتم تمريرها لدالة الcallback.

سنستخدم هذه الدالة في مثالنا بإضافتها لجسم الدالة register_and_build_fields التي عرفناها سابقا.. أي أنها ستأخذ الصورة التالية:

add_action('admin_init', 'register_and_build_fields');
function register_and_build_fields() {
   register_setting('plugin_options', 'plugin_options', 'validate_setting');
   add_settings_section('main_section', 'الإعدادات الرئيسية', 'section_cb', 'theme_options');
   add_settings_field('banner_heading', 'الإعلان', 'banner_heading_setting', 'theme_options', 'main_section'); // Banner Heading
   add_settings_field('logo', 'الشعار', 'logo_setting', 'theme_options', 'main_section'); // LOGO
}

لاحظ أننا قمنا بإستخدام الدالة add_settings_section  لإضافة قسم إعدادات جديد

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

أما بالنسبة للصورة العامة للدالة add_settings_section فهي تستقبل 3 معاملات هي:

• id: هو عبارة عن المعرف الخاص بالقسم ويجب أن يكون فريدا unique
• title: عنوان القسم والذي سيظهر في صفحة الخيارات في أعلى القسم (أنظر الصورة)
• callback: الدالة المسئولة من إنشاء القسم نفسه، أي أننا سنستخدم هذه الدالة لعمل echo للhtml الخاصة بالقسم.
• page: الصفحة التي سيظهر فيها القسم (في حالتنا هي صفحة خيارات القالب)

(إضغط على الصورة للمشاهدة بحجم أكبر)

بعد ذلك قمنا بإضافة حقلين وهما حقل الإعلان في الهيدر وحقل إضافة الشعار.
وتبقى ان ننشئ دوال الcallback المسئولة من إنشائهما كما ذكرنا في الاعلى وكما عرفناهما في معاملات الدالة add_settings_field لذلك سنعرف الدالتين كالأتي
دالة الإعلان في الهيدر:

// Banner Heading Callback function 
function banner_heading_setting() {
  $options = get_option('theme_options');
    echo "<input name='theme_options[banner_heading]' type='text' value='{$options['banner_heading']}' />";
}

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

دالة إنشاء حقل الشعار:

function logo_setting() {
  echo '<input type="file" name="logo" />';
}

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

مراجعة لما سبق:
قمنا في هذا الدرس بالاتي:

• تسجيل الإعدادات الخاصة بنا من خلال الدالة  register_setting
• إضافة قسم إعدادات لنضيف فيه الحقول من خلال الدالة add_settings_section
• أضفنا حقلين للإعدادات من خلال الدالة  add_settings_field

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

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

لا تنسى مشاركة المقال مع الأصدقاء ^^

[mc4wp_form]

المراجع والمصادر:
http://codex.wordpress.org/Settings_API

http://kovshenin.com/2012/the-wordpress-settings-api/

http://www.sitepoint.com/wordpress-options-panel/