وردپرس برای ساخت پنل تنظیمات شبیه به پنل تنظیمات پیش فرض خودش API هایی رو قرار داده . Settings API , Options API دو مورد برای ساخت پنل تنظیمات در وردپرس است.

برای ساخت پنل تنظیمات ابتدا نیاز داری تا یک صفحه در پنل ادمین داشته باشید تا در نهایت تنظیمات را روی آن پیاده سازی کنید. برای این منظور مقاله Administration Menus در وردپرس را مطالعه کنید.

برای ساخت تنظیمات در وردپرس دو مرحله کار نیاز دارید :

1. رجیستر کردن تنظیمات
2. پیاده سازی تنظیمات در پنل

رجیستر کردن تنظیمات در وردپرس

برای رجیستر کردن تنظیمات ما به توابع زیر نیاز داریم:

• register_setting : رجیستر کردن تنظیمات
• add_settings_section : ساخت بخش برای تنظیمات و اتصال آن به تنظیمات (setting)
• add_settings_field : ساخت فیلد و اتصال آن به تنظیمات (setting) و بخش (section)

موارد گفته شده رو از پایین به بالا به هم مرتبط و متصل هستند. هر کدام از آن ها یک شناسه دارند که از طریق همان شناسه به هم متصل می شوند.

تابع register_setting

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

• option_group : این پارامتر حکم شناسه تنظیمات را دارد. به وسیله این پارامتر بخش ها (sections) و فیلد ها (fields) را به این تنظیمات متصل می کنیم. همچنین در زمان فراخوانی تنظیمات در پنل با همین شناسه تنظیمات را پیاده سازی می کنیم.
• option_name : این پارامتر همان نام تنظیمات است که به وسیله get_option گرفته می شود. مقادیر کل فیلد های پیاده سازی شده در این تنظیم در سطری از جدول wp_options با نام option_name ذخیره می شوند که هر کدام از فیلد ها با نام خودشون قابل دسترسی هستند.

تابع add_settings_section

<?php add_settings_section( string $id, string $title, callable $callback, string $page ) ?>

• id : شناسه این بخش که قرار است فیلد ها از طریق این شناسه به بخش متصل شوند.
• title : عنوان بخش که در بالای هر بخش قرار می گیرد.
• callback : تابعی که قرار است خروجی بخش را تعیین کند. معمولا متن توضیحات گذاشته می شود.
• page : شناسه تنظیماتی که رجیستر شده . برابر پارامتر option_group در تابع register_setting

تابع add_settings_field

<?php add_settings_field( string $id, string $title, callable $callback, string $page, string $section = 'default', array $args = array() ) ?>

• id : شناسه فیلد
• title : عنوان فیلد
• callback : تابعی که قراره خروجی این فیلد رو بسازه . این تابع پارامتر args  که آخرین پارامتر این تابع است رو به عنوان ورودی میگیره.
• section : شناسه بخش (section) که قراره در اون قرار بگیره رو باید بهش بدید . این همون پارامتر id هست که در تابع add_settings_section دادیم.
• args : آرگومان هایی که قراره به تابعی که قراره خروجی رو برای این فیلد نمایش بده (callback) ، داده بشه در قالب آرایه که میتونه name , id , … و موارد این چنین لازم برای هر ورودی باشه.

بنابراین هر field میتونه به یه section و یک settings متصل باشه و هر section به یک settings متصل هست و در نهایت handler کل اون ها میشه option_group موجود در settings.

یک مثال ساده و کلی از روال بالا :

<?php
function custom_settings_init(){
    register_setting("option_group_settings", "option_name_settings");
    add_settings_section("section_id", __("General settings"), "settings_section_html", "option_group_settings");
    add_settings_field("field_id", __("label"), "settings_field_html", "option_group_settings", "section_id", array("id" => "post-type, "name" => "post_type"));
}		
add_action('admin_init','custom_settings_init');
function settings_section_html() {}	
function settings_field_html($args) {
    ?><input type="text" name="option_name_settings[<?php echo $args['name']?>]" value="" ><?php
}

نکته : برای این که توابع register_setting , add_settings_section , add_settings_fieds کار کنند باید آن ها را در یک تابع جدا مثلا custom_settings_init قرار داده و بعد آن را به admin_init قلاب کنید.

پیاده سازی تنظیمات در پنل

در این قسمت مقصود ما پیاده سازی همین تنظیماتی هست که در قسمت قبل ساختیم در پنلی که در اختیار داریم. دقت داشته باشید برای ساخت پنل (چه به صورت Top level Menu , Sub level Menu ) باید روال گفته شده را دنبال کنید.

برای پیاده سازی تنظیمات باید یک فرم با action که به برگه options.php می رود با متد POST قرار دهید و در درون آن توابع settings_fields , do_settings_sections , submit_button را فراخوانی کنید.

تمامی توابع زیر به عنوان ورودی پارامتر option_group مربوطه به تابع register_setting را می گیرند.

• settings_fields : این تابع به عنوان ورودی شناسه settings را می گیرد.
• do_settings_sections : این تابع به عنوان ورودی شناسه settings را می گیرد.
• submit_button : این تابع برای ساخت دکمه ذخیره برای پنل تنظیمات شما به سبک دکمه های وردپرس می باشد.
• add_settings_error : این تابع برای نمایش پیغام خطا یا موفقیت ذخیره سازی تنظیمات به کار می رود.

صورت کلی این روال را در زیر مشاهده می فرمایید :

<?php 
if(!current_user_can("manage_options")){
    return;
}
if(isset($_GET['settings-updated']) and $_GET['settings-updated'] == TRUE){
    add_settings_error("option_group_settingss", "option_group_settings" , __("Settings saved") , "updated");
}elseif(isset($_GET['settings-updated']) and $_GET['settings-updated'] == FALSE){
    add_settings_error("option_group_settings", "option_group_settings" , __("Error with saving"));
}
?>
<div class="wrap">
    <h1><?php echo get_admin_page_title(); ?></h1>
    <form action="options.php" method="post">
        <?php 
        settings_fields("option_group_settings");
        do_settings_sections("option_group_settings");
        submit_button(__("save","rng-postviews"));
        ?>
    </form>
</div>

نکته : در ابتدای این روال به وسیله تابع current_user_can چک کردیم که آیا کاربر جاری سطح دسترسی برای ویرایش داره یا خیر.

نکته : تابع get_admin_page_title برای نمایش عنوان صفحه است.

نکته : به عنوان یک تمرین خوب کل صفحه رو در یک div با کلاس wrap قرار میدیم.

گرفتن تنظیمات با استفاده از تابع get_option

ما زمانی که داشتیم register_setting می کردیم یه پارامتر (option_name ) بهش دادیم که با استفاده از همون می تونیم به تمامی تنظیمات دست پیدا کنیم.

<?php
$settings = get_option("option_name_settings"); 
$post_type = $settings['post_type'];
?>

خوب حالا ما یه متغیر داریم با نام settings که یه آرایه است که شامل تمامی تنظیمات ماست . هر جا ما فیلدی اضافه کردیم یه نام براش گذاشتیم که حالا اون فهرستی از آرایه ماست . با استفاده از نام فیلد به مقدار فیلد دست پیدا کنید. (به نحوه پیاده سازی فیلد ها در مثال بالا دقت فرمایید)

مزیت های استفاده از settings api در وردپرس :

• با پاک کردن تنها یک فیلد تمامی تنظیمات از پایگاه داده حذف میشه و این روال حذف پلاگین رو راحت تر میکنه برامون.
• عملیات ذخیره سازی و بروزرسانی به صورت خودکار انجام می شود.
• استایل آن به صورت منعطف برای پنل های راست چین و یا چپ چین می باشد.