استقبال وحفظ خيارات (وبيانات) الإضافة من خلال التعامل مع Setting API وOptions API

مهرة النجدية · 24-02-2019, 11:08 PM

استقبال وحفظ خيارات (وبيانات) الإضافة من خلال التعامل مع 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
}

المصدر: منتديات رحيل لكل العرب - من قسم: قسم تطوير المواقع ومحركات البحث والسيو Seo والووردبريس WordPress

عيون المها · 27-07-2019, 11:05 PM

بارك الله فيكِ
وجزاكِ الله خير الجزاء
دمتِ برضى الله وحفظه ورعايته

24-02-2019, 11:08 PM	#1
مهرة النجدية تاريخ التسجيل: Feb 2019 الدولة: قلب ابي العمر: 31 المشاركات: 1,006 التقييم: 10	مهرة النجدية تاريخ التسجيل: Feb 2019 الدولة: قلب ابي العمر: 31 المشاركات: 1,006 التقييم: 10 استقبال وحفظ خيارات (وبيانات) الإضافة من خلال التعامل مع Setting API وOptions API استقبال وحفظ خيارات (وبيانات) الإضافة من خلال التعامل مع 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 } المصدر: منتديات رحيل لكل العرب - من قسم: قسم تطوير المواقع ومحركات البحث والسيو Seo والووردبريس WordPress
	اقتباس

27-07-2019, 11:05 PM	#2
عيون المها تاريخ التسجيل: Jul 2019 المشاركات: 500 التقييم: 10	عيون المها بارك الله فيكِ وجزاكِ الله خير الجزاء دمتِ برضى الله وحفظه ورعايته
	اقتباس

المواضيع المتشابهه
الموضوع	كاتب الموضوع	المنتدى	مشاركات	آخر مشاركة
التعامل مع الإشاعات من خلال السنة النبوية	الفارس	قسم الحديث الشريف والسُنة النبوية	1	07-07-2019 09:37 PM

اسم العضو		حفظ البيانات؟
كلمة المرور

الذين يشاهدون محتوى الموضوع الآن : 1 ( الأعضاء 0 والزوار 1)