تاريخ التسجيل: Feb 2019
الدولة: قلب ابي
العمر: 31
المشاركات: 1,006
التقييم: 10
|
تاريخ التسجيل: Feb 2019
الدولة: قلب ابي
العمر: 31
المشاركات: 1,006
التقييم: 10
استقبال وحفظ خيارات (وبيانات) الإضافة من خلال التعامل مع Setting API وOptions API
استقبال وحفظ خيارات (وبيانات) الإضافة من خلال التعامل مع Setting API وOptions API
كنا قد ذكرنا في الدرس الأول لهذه السلسلة أنّ هناك مجموعة من الطرق يتيحها ووردبريس لحفظ واسترجاع البيانات ومن ضمن هذه الطرق استخدام الواجهة البرمجية للخيارات 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 الكثير من المجهود المُتعلّق بحفظ الخيارات واسترجاعها بالصورة التقليدية والتي تتطلب القيام بكل عمليات الاتصال مع قاعدة البيانات والتأكد من تأمين البيانات والتعامل مع نماذج الحفظ وغيرها من العمليات، لكن في البداية قد تجد صعوبة في التعامل مع هاتين الواجهتين خصوصا فيما يتعلق في حفظ أسماء الدوال ومعاملاتها وارتباطها مع بعضها البعض، لكن سيتغيّر الأمر بعد التّعامل معها لفترة قصيرة.
setting api options api
1 شخص أعجب بهذا
تفاعل الأعضاء
2 تعليقات
أيمن الشرقاوي
أيمن الشرقاوي 0
نشر 9 مارس 2017
السلام عليكم
رجاءاً مراجعة الفقرة التي تبدأ ب
"هذه الدالة تقوم بفحص ما إذا كان الخيار $option موجودًا مُسبقا في قاعدة البيانات وفي حالة عدم وجوده ت"
الدالة الذي تتكلم عنها غير مكتوبه
Hussam Barbour
Hussam Barbour 19
نشر 20 ديسمبر 2017 (مُعدّل)
شكرا لك أخي الكريم على مجهودك ..
هناك عدة أخطاء في المثال وقد قمت بتصحيحها :
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( 'myplugin_setting_section', 'myplugin_setting_name' );
}
// إضافة الدالة أعلاة للخطاف المناسب وهو admin_init
add_action( 'admin_init', 'myplugin_settings_api_init' );
// ------------------------------------------------------------------
// دالة الcallback لقسم الإعدادات
// ------------------------------------------------------------------
function myplugin_setting_section_callback_function() {
echo '<p>نص في بداية قسم الإعدادات</p>';
}
// ------------------------------------------------------------------
// دالة الcallback لحقل الإعدادات
// ------------------------------------------------------------------add_options_page
// إنشاء مربع إختيار checkboxز بالطبع يمكنك إنشاء أنواع أخرى من الخقول
function myplugin_setting_callback_function() {
echo '<input name="myplugin_setting_name" id="myplugin_setting_name" type="checkbox" value="1" class="code" ' . checked( 1, get_option( 'myplugin_setting_name' ), false ) . ' /> مثال';
}
// الدالة المسؤولة عن عرض بيانات صفحة خيارات الإضافة كما عرفناها اعلاه
function my_plugin_options_page() {
?>
<div class="wrap">
<h2>صفحة خيارات الإضافة</h2>
<form action="options.php" method="POST">
<?php settings_fields( 'myplugin_setting_section' ); ?>
<?php do_settings_sections( 'my_plugin_admin_page' ); ?>
<?php submit_button(); ?>
</form>
</div>
<?php
}
|