پیاده سازی تنظیمات پلاگین وردپرس با آپشن ها

وردپرس به آسانی امکان ذخیره سازی و دریافت اطلاعات مورد نیاز پلاگین ها را از طریق توابع داخلی که برای این منظور در نظر گرفته شده اند فراهم می آورد. آپشن ها (options) مجموعه ای از توابع در وردپرس هستند که برای ذخیره سازی و دریافت اطلاعات مرتبط با تنظیمات پلاگین ها می توان از آنها استفاده کرد. این اطلاعات به همراه مجموعه ای از سایر داده های مورد نیاز هسته وردپرس در جدول options وردپرس نگهداری می شوند.

در این بخش از آموزش پلاگین نویسی وردپرس به معرفی توابع آپشن ها و نحوه پیاده سازی تنظیمات پلاگین می پردازیم.

ذخیره سازی آپشن ها

برای ذخیره سازی داده در جدول آپشن ها از تابع add_option استفاده می شود. پارامتر اول این تابع نام آپشن مورد نظر و پارامتر دوم مقدار آن آپشن برای ذخیره سازی است. نامی که برای آپشن انتخاب می شود باید یکتا و مشخص کننده ماهیت آن باشد (به عنوان مثلا my_plugin_settings مشخص کننده آپشن مربوط به تنظیمات پلاگینی با نام my_plugin است. نوع داده ای که قصد ذخیره سازی آن را دارید نیز می تواند از هر نوعی باشد.

<?php
add_option( 'bmpt_myplugin_color', 'red' );
?>   

برای بروزرسانی مقدار آپشن می توان از تابع update_option استفاده کرد. پارامترهای ورودی این تابع همانند تابع add_option است. البته تابع update_option پیش از بروزرسانی آپشن وجود آن را بررسی می کند و در صورت عدم وجود آپشن آن را ایجاد می کند. در حالی تابع add_option تنها برای ایجاد یک آپشن مورد استفاده قرار می گیرد. ذخیره سازی هر آپشن سبب افزودن سطری جدید به جدول options می گردد. برای حفظ کارایی وردپرس و عدم تحمیل سربار اضافی برای بارگذاری سایت، بهتر است مجموعه پارامترها و مقادیر مرتبط با پلاگین را به صورت آرایه ذخیره نمایید.

مثال: ذخیره مقادیر به صورت آرایه

< ?php
$options = array(
    'color'    = >  'red',
    'fontsize' = >  '120%',
    'border'   = >  '2px solid red'
);
update_option( 'bmpt_myplugin_options', $options );
? >  

در هنگام ذخیره سازی آپشن می توانید تعیین نمایید که این آپشن به صورت اتوماتیک در هر بارگذاری وردپرس در دسترس باشد یا خیر. مزیت اتولود بودن آپشن این است که از حجم مراجعات اضافی به دیتابیس برای دریافت مقدار آپشن خواهد کاست. وضعیت اتولود یک آپشن را می توانید از طریق پارامتر سوم ورودی تابع update_option یا پارامتر چهارم تابع add_option تعیین نمایید. (پارامتر سوم تابع add_option همواره مقدار خالی است). مقدار پارامتر اتولود می تواند به صورت true یا false و یا رشته (‘yes’ یا ‘no’ ) باشد. مقدار پیش فرض اتولود ‘yes’ است.

< ?php
add_option( 'bmpt_myplugin_option', $value, '', $autoload );
? >  

دریافت آپشن ها از پایگاه داده

برای دریافت مقدار یک آپشن از دیتابیس از تابع get_option استفاده می شود. این تابع دو پارامتر ورودی می پذیرد: پارامتر اول نام آپشن و پارامتر دوم که اختیاری است مقدار پیش فرض در صورت عدم وجود آپشن است.

< ?php
$option = get_option( 'bmpt_myplugin_option', 'option not found' );
? >

در حالتی که بخواهیم داده ها را به صورت آرایه ذخیره نماییم، می توانیم از طریق کلید به هر مقدار آن دسترسی یابیم:

< ?php
// To store all of them in a single function call:
$myplugin_options = array(
    'color'    = >  'red',
    'fontsize' = >  '120%',
    'border'   = >  '2px solid red'
);
update_option( 'bmpt_myplugin_options', $myplugin_options ) ;
        
// Now to fetch individual values from one single call:
$options  = get_option( 'bmpt_myplugin_options' );
$color    = $options[ 'color' ];
$fontsize = $options[ 'fontsize' ];
$border   = $options[ 'border' ];
? >   

حذف آپشن

به منظور حذف یک آپشن از جدول آپشن ها می توان از تابع delete_option استفاده نمود. این تابع نام آپشن را به عنوان ورودی می پذیرد و در صورت عدم وجود آپشن مقدار false و در غیر این صورت مقدار true را بر می گرداند.

< ?php
delete_option( 'boj_myplugin_options' );
? >   

ایجاد بخش مدیریت (تنظیمات) پلاگین

ایجاد بخش تنظیمات برای پلاگین شامل چند گام برای ثبت تنظیمات، تعریف بخش ها و فیلدهای مورد نظر و نمایش آنها در خروجی می شود.

گام اول: ایجاد صفحه تنظیمات و ثبت تنظیمات

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

<?php
// Add the admin options page
add_action('admin_menu', 'bmpt_myplugin_add_page');
function bmpt_myplugin_add_page() {
    add_options_page( 'My Plugin', 'My Plugin', 'manage_options',
        'bmpt_myplugin', 'bmpt_myplugin_options_page' );
}
        
// Draw the options page
function bmpt_myplugin_options_page() {
    ?> 
     < div class="wrap" > 
     < ?php screen_icon(); ?> 
     < h2 > My plugin < /h2 > 
     < form action="options.php" method="post" > 
     < /form >  < /div > 
     < ?php
}
?>  

اطلاعات فرمی که برای ذخیره سازی تنظیمات پلاگین استفاده می گردد باید به صفحه options.php ارسال گردد.

تابع register_setting برای ثبت تنظیمات مورد استفاده پلاگین استفاده می شود. این تابع سه پارامتر ورودی می پذیرد: پارامتر اول نام گروه برای تنظیمات، پارامتر دوم نام آپشن و پارامتر سوم که اختیاری است شامل آرایه ای از اطلاعات تنظیمات شامل نوع داده، توضیحات و نام تابع اعتبارسنجی داده ها می باشد.

function register_my_setting() {
    $args = array(
            'type' => 'string', 
            'sanitize_callback' => 'sanitize_text_field',
            'default' => NULL,
            );
    register_setting( 'my_options_group', 'my_option_name', $args ); 
} 
add_action( 'admin_init', 'register_my_setting' );

گام دوم: تعریف بخش و فیلدهای تنظیمات

 توابع add_settings_section و add_settings_field به ترتیب برای تعریف بخش تنظیمات و تعریف فیلدهای فرم تنظیمات استفاده می شوند. تابع add_settings_section چهار پارامتر ورودی می پذیرد: پارامتر اول نام مستعار به عنوان آیدی section، پارامتر دوم عنوان section، پارامتر سوم نام تابعی که محتوای آن بین عنوان و فیلدهای section نمایش داده می شود و پارامتر چهارم نام مستعار صفحه تنظیماتی که در آن section به نمایش در می آید. تابع add_settings_field شش پارامتر ورودی می پذیرد: پارامتر اول نام مستعار برای شناسایی فیلد، پارامتر دوم عنوان برچسب فیلد، پارامتر سوم نام تابع خروجی نمایش دهنده خروجی فیلد، پارامتر چهارم نام مستعار صفحه تنظیمات section، پارامتر پنجم نام مستعار section مورد نظر و پارامتر آخر آرایه ای از آرگومانهای اضافی است که برای قالب بندی فیلد در خروجی می تواند استفاده شود. لازم به ذکر است که دو پارامتر آخر این تابع اختیاری است.

// Register and define the settings
add_action('admin_init', 'bmpt_myplugin_admin_init');
function bmpt_myplugin_admin_init(){
    register_setting( 'bmpt_myplugin_options', 'bmpt_myplugin_options',
        'bmpt_myplugin_validate_options' );
    add_settings_section( 'bmpt_myplugin_main', 'My Plugin Settings',
        'bmpt_myplugin_section_text', 'bmpt_myplugin' );
    add_settings_field( 'bmpt_myplugin_text_string', 'Enter text here',
        'bmpt_myplugin_setting_input', 'bmpt_myplugin', 'bmpt_myplugin_main' );
}

// Draw the section header
function bmpt_myplugin_section_text() {
    echo ' < p > Enter your settings here. < /p > ';
}
        
// Display and fill the form field
function bmpt_myplugin_setting_input() {
    // get option 'text_string' value from the database
    $options = get_option( 'bmpt_myplugin_options' );
    $text_string = $options['text_string'];
    // echo the field
    echo " < input id='text_string' name='bmpt_myplugin_options[text_string]'
        type='text' value='$text_string' / > ";
}

گام سوم: اعتبارسنجی داده های ورودی و نمایش فرم

 عملیات اعتبارسنجی داده ها را می توان در تابعی که به عنوان پارامتر سوم register_setting در زمان ثبت تنظیمات معرفی کردیم انجام دهیم. پارامتر ورودی این تابع در واقع آرایه $_POST ارسالی می باشد.

< ?php
function bmpt_myplugin_validate_options( $input ) {
    $valid = array();
    $valid['text_string'] = preg_replace(
        '/[^a-zA-Z]/',
        '',
        $input['text_string'] );
    return $valid;
}? >  

پس از تعریف توابع مورد نیاز، حال نوبت به استفاده از این توابع و نمایش نتیجه در خروجی است. به سراغ کدی که در گام اول برای نمایش صفحه تنظیمات نوشتیم می رویم و تابع نمایش دهنده محتوای صفحه را به صورت زیر تغییر می دهیم:

< ?php
// Draw the options page
function bmpt_myplugin_options_page() {
    ? > 
        
     < div class="wrap" > 
     < ?php screen_icon(); ? > 
     < h2 > My plugin < /h2 > 
     < form action="options.php" method="post" > 
        
     < ?php
    settings_fields('bmpt_myplugin_options');
    do_settings_sections(‘bmpt_myplugin’);
    ? > 
        
     < input name="Submit" type="submit" value="Save Changes" / > 
     < /form >  < /div > 
        
     < ?php
}? >

دو تابع settings_fields و do_settings_sections به کد قبلی اضافه شده اند. تابع settings_field در واقع به آپشنی که توسط تابع register_setting تعریف شده است ارجاع می دهد. فراخوانی این تابع باعث افزودن کنترل های امنیتی به فرم نیز می گردد. فراخوانی تابع do_settings_sections نیز باعث نمایش section ها و فیلدهای تعریف شده می گردد. پارامتر ورودی این تابع نام مستعار section است.