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

 

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

تسجيل الاعدادات والاقسام والحقول Settings API

 

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

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

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

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

 

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

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

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

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

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

 

النشرة البريدية

ندعوك للإنضمام إلى 223 مشترك في قائمتنا البريدية

 

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

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

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

This Post Has 5 Comments

  1. لا اعلم كيف اشكرك فالكلمات لا تكفي
    واصل صديقي وانا بانتظار كل ما هو جديد منك

    1. مرحبا عزيزي محمد الحمد لله اولا واخرا
      شكرا على تشجيعك وانتظر المزيد إن شاء الله

  2. بارك الله فيك وجزاك كل خير . لاتسعني الكلمات لشكرك . بانظار باقي الدرس على احر من الجمر .

    1. وجزاك الله خيرا… شكرا على تشجيعك وتسعدني متابعتك.

  3. شكرآ لك اخي على مجهودك ودروسك الجميله ولكن هناك تشتيت نوعآ ما في الدرس …. المفروض بعد الدرس تضع الكود النهائي للدرس او للمشروع عشان الطالب يفهم ترتيب الكود ويعرف الامور كيف ماشيه … اتمنى ان تقبل مني هذا الانتقاد البسيط لان دروسك جميله لكنها خربانه بسبب هذه النقطه

اترك رد

إغلاق القائمة