WordPress Settings API – The Options Page

WordPress Settings API – WordPress 2.7 में एक नया Settings API Add किया गया है, जिसके API Functions का प्रयोग करके हम Plugin के Option Page से सम्बंधित विभिन्न प्रकार की जरूरतों को बडी ही आसानी से पूरा कर सकते हैं।

जब हम इस API के Functions का प्रयोग करते हैं, तब हमें wp_options Table में Store होने वाले Data की Security के विषय में किसी प्रकार की कोई चिन्ता करने की जरूरत नहीं होती है, क्योंकि Security Related विभिन्न Issues को ये API Functions स्वयं ही अपने स्तर पर Automatically Handle कर लेते हैं।

जब हम हमारे Plugin से सम्बंधित Options को wp_options Table में Store करना चाहते हैं, तो सबसे पहले हमें add_menu_page() या add_submenu_page() API Functions अथवा इसके विभिन्न Wrapper Functions में से किसी का प्रयोग करके एक Option (Configuration or Settings) Page से सम्बंधित Menu Option Create करना होता है, जिस पर Click करके हम हमारे Plugin से सम्बंधित Configuration Page को Open करते हैं और Option Page Create करने के लिए हम निम्नानुसार Code Use कर सकते हैं:

add_action('admin_menu', 'my_custom_plugin_menu');
function my_custom_plugin_menu() {
    add_menu_page(
        'Title of MyCustomPlugin ',
        'MyCustomPlugin',
        'delete_posts',
        'my_custom_plugin',
        'my_custom_plugin_function'
    );
}

ध्‍यान दें कि यहां हमने ‘admin_menu‘ Hook का प्रयोग किया है, जो उस समय Fire होता है, जब WordPress Admin Panel के सभी Default Menu Panels Create हो चुके होते हैं।

चूंकि हम चाहते हैं कि जब WordPress के Admin Panel में MyCustomPlugin नाम का ये नया Menu Panel Create हो, तब Admin Panel के Initialize होते समय ही हमारे Plugin से सम्बंधित जरूरी Options wp_options Table में Store हो जाऐं।

इस जरूरत को पूरा करने के लिए हम WordPress के admin_init Hook (Event) का प्रयोग कर सकते हैं और इस Event के Response में custom_plugin_register_settings() नाम का एक Custom Function Call कर सकते हैं, जो कि हमारे Plugin के Custom Settings को wp_options Table में Store करने का काम करता है।

चूंकि ये काम तभी होना चाहिए, जबकि WordPress में Custom Top Level Menu Option Create किया जा रहा हो, इसलिए हम उपरोक्त Code को Modify करते हुए निम्नानुसार भी लिख सकते हैं:

	add_action('admin_menu', 'my_custom_plugin_admin_page');
	function my_custom_plugin_admin_page() {
		add_menu_page(
			'Title of MyCustomPlugin ',
			'MyCustomPlugin',
			'delete_posts',
			'my_custom_plugin',
			'my_custom_plugin_function'
		);
	
	add_action('admin_init', 'custom_plugin_register_settings');
	function custom_plugin_register_settings(){
		// Plugin's Settings code here...
	} 
}

register_setting() API Function

ये Function किसी Setting को Register करता है यानी wp_options नाम की WordPress Table में Store करता है तथा Callback Function को Sanitize करता है, यानी अवांछित स्थितियों को Remove करता है। इस Function का Syntax निम्नानुसार होता है:

        register_setting( $option_group, $option_name, $sanitize_callback );

ये Function हमारी Settings को Register करते हुए Automatically wp-admin Settings Page Generate करने का काम करता है तथा Output को Control करने के लिए Automatically कुछ Callbacks करता है।

इस Function का प्रयोग Settings को Register करने के लिए भी किया जा सकता है, जिनका प्रयोग Default WordPress Settings Page पर Show करने के लिए होता है। जब एक बार Settings Register हो जाते हैं, उसके बाद हम add_settings_field() Function का प्रयोग करके इन्हें किसी Existing Section में Add कर सकते हैं या हम add_settings_section() Function का प्रयोग करके नया Section Create कर सकते हैं और Registered Settings को उस नए Section में Add कर सकते हैं।

$option_group Parameter

register_setting() API Function के पहले Argument के रूप में हमें एक Group Name को Specify करना होता है। इस Group Name का register_setting() API Function को Call करने से पहले Exist होना जरूरी होता है। साथ ही Group Name का settings_fields() API Function में Match होना भी जरूरी होता है।

$option_name Parameter

इस Parameter के रूप में हमें उस Option को Specify करना होता है, जिसे हम Sanitize व Save करना चाहते हैं।

$sanitize_callback Parameter

इस Parameter के रूप में हमें उस Callback Function को Specify करना होता है, जो Option के रूप में Specified Parameter की Value को Sanitize करता है।

इस तरह से यदि हम चाहें तो इस Function को Use करते हुए अपने पिछले Program Code को निम्नानुसार Modify कर सकते हैं:

add_action('admin_menu', 'my_custom_plugin_admin_page');
function my_custom_plugin_admin_page() {
	add_menu_page(
		'Title of MyCustomPlugin ',
		'MyCustomPlugin',
		'delete_posts',
		'my_custom_plugin',
		'my_custom_plugin_function'
	);
	
	add_action('admin_init', 'custom_plugin_register_settings');
	function custom_plugin_register_settings(){
		register_setting('custom-plugin-settings-group', 'custom_plugin_option_name');
		register_setting('custom-plugin-settings-group', 'custom_plugin_option_email');
		register_setting('custom-plugin-settings-group', 'custom_plugin_option_url');
	} 
}

register_setting() API Function को उपरोक्तानुसार उपयोग में लेकर हम हमारे Options Pages में तीन Options को Configure करने की व्‍यवस्था कर रहे हैं। इस Function का पहला Parameter उस Option Group के नाम को Represent कर रहा है, जिसे wp_options Table में Save करना है।

हम देख सकते हैं कि उपरोक्त Code में register_setting() Function में Specified Group Name का नाम custom-plugin-settings-group है और Name, Email व URL तीनों ही Options के लिए हमने register_setting() नाम के Function में तीनों ही Options के लिए पहले Parameter के रूप बार इसी Group Name को Specify करते हुए Call किया है, ताकि समान Group Name के साथ Associated सभी Options को wp_options Table में एक ही बार में Store किया जा सके।

इस तरह से जब हम हमारे Plugin से सम्बंधित सभी Options को एक Set की तरह custom-plugin-settings-group नाम के Group Name के साथ Register कर देते हैं, उसके बाद हमें हमारा Option Page Create करना होता है और Option Page Create करने के लिए हमें my_custom_plugin_function() नाम का Function Define करना पडता है। क्योंकि add_menu_page() API Function द्वारा WordPress Admin Panel में MyCustomPlugin नाम का नया Menu Option Add करते समय add_menu_page() API Function के अन्तिम Parameter के रूप में हमने यही नाम Specify किया था।

my_custom_plugin_function() नाम का ये Function उस समय Invoke होता है, जब हम add_menu_page() API Function द्वारा Newly Created MyCustomPlugin नाम के Top Level Menu Option को Click करते हैं। अपने Plugin के लिए Option Page बनाने हेतु हम इस Function को निम्नानुसार Define कर सकते हैं:

<?php 
function my_custom_plugin_function() { 
?> 
<div class="wrap"> 
<h2><?php _e('Custom Plugin Options', 'custom-plugin') ?></h2>
<form method="post" action="options.php"> 
<?php settings_fields( 'custom-plugin-settings-group' ); ?>
<table class="form-table">
<tr valign="top"> 
<th scope="row"><?php _e('Name', 'custom-plugin') ?></th>
	<td>
		<input type="text" name="custom_plugin_option_name" 
		value="<?php echo get_option('custom_plugin_option_name'); ?>" />
	</td>
</tr>
<tr valign="top"> 
<th scope="row"><?php _e('Email', 'custom-plugin') ?></th>
	<td>
		<input type="text" name="custom_plugin_option_email" 
		value="<?php echo get_option('custom_plugin_option_email'); ?>" />
	</td>
</tr>
<tr valign="top"> 
	<th scope="row"><?php _e('URL', 'custom-plugin') ?></th>
	<td>
		<input type="text" name="custom_plugin_option_url" 
		value="<?php echo get_option('custom_plugin_option_url'); ?>" />
	</td>
</tr>
</table>
<p class="submit"> 
	<input type="submit" class="button-primary" 
	value="<?php _e('Save Changes', 'custom-plugin') ?>" />
</p>
</form>
</div>
<?php } ?>

इस Code में सबसे पहले हमने निम्नानुसार तरीके से अपने Function के Header को Specify किया है:

<?php
function my_custom_plugin_function() {
?>

फिर हमने निम्नानुसार तरीके से एक <div> Element Create किया है, जिसमें Specified class नाम के Attribute में “wrap” मान Specify किया है:

<div class=“wrap”>

इस “wrap” नाम की Class को Specify करने का मुख्‍य फायदा ये होता है कि हमारे Create होने वाले Form पर Default रूप से वे CSS Styling Rules Apply हो जाते हैं, जिन्हें WordPress के विभिन्न WordPress Admin Panel पर Apply करने के लिए Specify किया गया है।

परिणामस्वरूप जब Plugin की File में उपरोक्त Code लिखकर File को Save कर दिया जाता है, तो Save होने के बाद WordPress Admin Panel में Create होने वाले MyCustomPlugin नाम के Newly Created Menu Option को Click करने पर हमें हमारे Plugin का Option Page कुछ निम्नानुसार दिखाई देता है, जहां हम देख सकते हैं कि दिखाई देने वाला हमारा Button Blue Color में ठीक उसी तरह से दिखाई दे रहा है, जैसे WordPress के अन्‍य Default Buttons दिखाई देते हैं:

जैसाकि हम उपरोक्त Output Generate करने वाले Code में देख सकते हैं कि हमने जो <form> Tag Specify किया है, उसके action Attribute में हमने निम्नानुसार options.php File को Specify किया है:

<form method=“post” action=“options.php”>

जो इस बात का Indication है कि इस Form पर दिखाई देने वाले “Save Changes” Button पर Click करने पर इस Form के Name, Email व URL Field में Specified Data को Handle करने का काम options.php नाम की File करेगा। जब हम WordPress के Settings API Functions का प्रयोग करते हुए Plugin के Option Page को Create करते हैं, तब हमें <form> Element के action Attribute में Value के रूप में हमेंशा उपरोक्तानुसार options.php File Name को ही Specify करना जरूरी होता है।

Opening व Closing <form> Element के बीच ही हमें हमारे उन Options Group को Define करना होता है, जिसे हमने register_setting() API Function द्वारा Register किया था। क्योंकि वे Options ही हमें इस Form पर Render करने होते हैं।

चूंकि हमने register_setting() API Function के माध्‍यम से Name, Email व URL के Set को custom-plugin-settings-group नाम के Group Name के साथ Associate किया था। इसलिए निम्न Statement का प्रयोग करके हमने हमारे <form> Element के बीच इस Options Group को Define किया है:

<?php settings_fields( ‘custom-plugin-settings-group‘ ); ?>

settings_fields() API Function

इस Function को हमेंशा Opening व Closing <form> Tag के बीच ही Call किया जाता है और ये Function, wp_options Table में register_setting() API Function द्वारा Register किए गए Group Name से Associated Options के लिए Field Create करने हेतु Available करवाता है। परिणामस्वरूप जब निम्न Code Run होता है:

<input type=“text” name=“custom_plugin_option_name”
value=“<?php echo get_option(‘custom_plugin_option_name‘); ?>” />

तब Name के लिए एक Text Type का Input Element Create होता है। इसी तरह से जब निम्न Statements Execute होते हैं:

<input type=“text” name=“custom_plugin_option_email”
value=“<?php echo get_option(‘custom_plugin_option_email‘); ?>” />

        . . .

<input type=“text” name=“custom_plugin_option_url”
value=“<?php echo get_option(‘custom_plugin_option_url‘); ?>” />

तब Email व URL Field के लिए दो और Text Type के Input Elements Create होते हैं और अन्त में निम्न Code Execute होता है:

<input type=“submit” class=“button-primary”
value=“<?php _e(‘Save Changes‘, ‘custom-plugin‘) ?>” />

जिसके परिणामस्वरूप Submit Type का एक Input Element Create होता है।

जैसाकि उपरोक्त तीनों Text Elements Create करने वाले Codes में हम देख सकते हैं कि हमने get_option() API Function का प्रयोग करके इससे Return होने वाली Value को] Create होने वाले Text Element के value Attribute में Specify किया है। इस Function में हमें Exactly उसी Option को Specify करना होता है, जिसे हमने register_setting() API Function के माध्‍यम से Specific Group Name के साथ Associate किया था।

इतना ही नहीं, इस Code में हमने सभी PHP Codes को echo Statement का प्रयोग करते हुए नहीं लिखा है, बल्कि Localization को ध्‍यान में रखते हुए जिन Texts को अन्‍य Language में Convert किया जा सकता है, उन्हें _e() API Function का प्रयोग करके Specify किया है। जिसकी वजह से हमारा Plugin एक Internationalize Plugin भी है।

जिस तरह से उपरोक्त Code द्वारा WordPress Admin में एक नया Top Level Menu Option Create करता है और उस Menu Option से सम्बंधित एक Option Configuration Page Create करता है।

ठीक उसी तरह से यदि हम चाहें तो Settings API के add_settings_section() API Function को Use करके WordPress Admin Panel के Settings Panel में स्थित विभिन्न Sub-Menu Pages में से किसी भी Page में एक नया Sub-Section Create कर सकते हैं।

continue…