WordPress Settings Page

पिछले उदाहरण द्वारा हम आसानी से समझ सकते हैं कि Settings API वास्तव में तीन Steps में काम करता है:

• सबसे पहले इस API का प्रयोग करके हमें WordPress को ये बताना होता है कि हम किस नई Setting को Manage करवाना चाहते हैं। इस बात को Specify करके हम हमारे Settings को वास्तव में Authorized Options की List में Add करते हैं।
• फिर हमें हमारे Setting को Define करना होता है यानी हमें हमारे Settings से सम्बंधित User Interface Elements जैसे कि HTML Input Elements (Textbox, Textarea, Checkbox, etc… Type के Form Elements) Create करने होते हैं।
• और अन्त में हमें WordPress को इस बात का Instruction देना होता है कि वह हमारी Settings को Actual तरीके से Display करे।

Creating Plugin Configuration Page

लेकिन इन तीनों ही Steps को Follow करने से पहले हमें हमारे Plugin के लिए एक Setting Management Page Create करना होता है और इस जरूरत को हम WordPress Admin Panel में सामान्‍यत: एक नया Top Level Menu Panel या Sub-Menu Panel Create करके करते हैं। जैसे:

<?php	
//Adding as submenu option under WP Admin - Settings Panel.
add_action('admin_menu', 'gaAdminMenu');
function gaAdminMenu(){
	add_options_page(
		'Google Analytics Configuration', 
		'Google Analytics Configuration', 
		'manage_options', 
		'ga-configuration',
		'gaConfiguration'
	);
} 

//Draw the Google Analytics Configuration Page
function gaConfiguration(){
?>
<div class="wrap">
	<?php screen_icon(); ?>
	<h2>Google Analytics Configuration</h2>
	<form action="options.php" method="post">
		
	</form>
</div>
<?php }?>

जब हम हमारे Plugin में इस Code को Specify करके WordPress Admin के Settings Panel को Open करते हैं, तो हमें “Google Analytics Configuration” नाम का एक नया Sub-Menu Option दिखाई देता है, जिसे Click करने पर हमारे सामने निम्नानुसार एक नया Configuration Page Open होता है:

Registering New Settings and Defining Sections and Fields

जब पिछले Code के अनुसार हम उपरोक्तानुसार अपने Plugin का Configuration Page Create कर लेते हैं, उसके बाद हमें तीन काम करने होते हैं और तीनों ही काम सामान्‍यत: एक साथ एक ही Event Handler में admin_init Event या Hook के Fire होने के Response में करने होते हैं। ये तीनों काम निम्नानुसार हैं:

• register_setting() API Function के माध्‍यम से New Settings को wp_options Table में Store या Register करना।
• WordPress Admin Panel में Plugin Configuration के लिए Newly Created Page पर नया HTML Input Element Fields के Groups को Create करने के लिए add_settings_section() API Function द्वारा Section Create करना।
• और register_setting() API Function द्वारा wp_options Table में Stored Setting को Get/Set करने के add_settings_field() API Function द्वारा उस Setting से सम्बंधित Field Create करना।

इन सभी कामों को पूरा करने के लिए हम हमारा Plugin Code निम्नानुसार Specify कर सकते हैं:

<?php 
/*
Plugin Name: Google Analytics
Plugin URI: https://www.bccfalna.com/wpplugins/my-plugin/
Description: To Add Google Analytics code to each page of the Site.   
Author: Kuldeep Chand
Version: 1.0
Author URI: https://www.bccfalna.com/
*/
?>

<?php
//Adding as submenu option under WP Admin - Settings Panel.
add_action('admin_menu', 'gaAdminMenu');
function gaAdminMenu(){
	add_options_page(
		'Google Analytics Configuration',
		'Google Analytics Configuration', 
		'manage_options',
		'ga-configuration', 
		'gaConfiguration'
	);
} 

//Draw the Google Analytics Configuration Page
function gaConfiguration(){
?>
<div class="wrap">
	<?php screen_icon(); ?>
	<h2>Google Analytics Configuration</h2>
	<form action="options.php" method="post">
		<?php settings_fields('UniqueID'); ?>
		<?php do_settings_sections('ga-configuration'); ?>
		<input name="Submit" type="submit" value="Save Changes" />
	</form>
</div>
<?php	} ?>

<?php
//Register and Define the Setting
add_action('admin_init', 'gaAdminINIT');
function gaAdminINIT(){
	register_setting('UniqueID', 'UA', 'gaValidateOptions'); //Setting Registration
	
	add_settings_section(					//Adding Section
		'gaAdminMainSection', 
		'Google Analytics - Main Configuration Section', 	
		'gaAdminSectionContent_Callback', 	//Declaring Section's Callback Function
		'ga-configuration'
	);
	
	add_settings_field(
		'txtgaUA', 
		'Google Analytics UA-000000 ID:', 
		'gaInputUAID_Callback',
		'ga-configuration', 
		'gaAdminMainSection'
	);
}

//Defining Section's Callback Function
function gaAdminSectionContent_Callback() {
	echo ' <p> Enter your Google Analytics ID. </p> ';
}

// Display and fill the form field
function gaInputUAID_Callback() {
	// get option 'text_string' value from the database
		$options = get_option( 'UA' );
		$text_string = $options['text_string'];
		
	// echo the field
	echo "<input id='text_string' name='UA[text_string]' type='text' value='$text_string' />";
 }

// Validate user input (we want text only)
function gaValidateOptions( $input ) {
	$valid = array();
	$valid['text_string'] = preg_replace('/[^a-zA-Z]/','',$input['text_string'] );
	return $valid;
}
?>

Registering New Setting

इस Code में UniqueID एक Group Name है जो कि कोई भी String हो सकता है। हमें हमारे Plugin से सम्बंधित जितने भी Options को wp_options Table में Store करना होता है, उन सभी को उपरोक्तानुसार register_setting() API Function Use करते हुए Specify करते हैं, लेकिन सभी Options का Group Name समान रखते हैं।

परिणामस्वरूप WordPress एक ही Group से सम्बंधित सभी Register होने वाले Plugin Related Options को एक ही बार में wp_options Table में Serialized Form में Store कर देता है। इस तरह से चूंकि हम Google Analytics का Unique ID ही wp_options Table में Store करना चाहते हैं, इसलिए हमने उपरोक्त Code में निम्नानुसार तरीके से register_setting() API Function को Use किया है, जो केवल एक ही Setting को Table में Store करने का काम कर रहा है:

        register_setting(‘UniqueID‘, ‘UA‘, ‘gaValidateOptions‘);       //Setting Registration

Defining Section

जब हम कोई बहुत बडा Plugin Create करते हैं, तब एक ही Admin Page पर विभिन्न प्रकार के Options के Group हो सकते हैं। इन समान विषय से सम्बंधित Options के Group को आसानी से Manage करने के लिए WordPress का Settings API हमें हमारे Plugin के Configuration Page को Sections में Divide करने की सुविधा Provide करने के लिए add_settings_section() नाम का API Function Provide करता है, जिसे हम निम्नानुसार Use कर सकते हैं:

	add_settings_section(			//Adding Section
		'gaAdminMainSection-ID', 
		'Google Analytics - Main Configuration Section', 	
		'gaAdminSectionContent_Callback', 	//Declaring Section's Callback Function
		'ga-configuration'
	);

फिर इस Section को Visually Represent करने के लिए हमने निम्नानुसार तरीके से Section के लिए Callback Function को Define किया है:

//Implementing Section’s Callback Function
function gaAdminSectionContent_Callback() {
	echo ' <p> Enter your Google Analytics ID here. </p> ';
}

Defining Fields

Section Define करने के बाद हमें इस Section में wp_options Table के जिन Data को Field के रूप में Display करना होता है, उन्हें उपरोक्त Section में Add करने के लिए हमने निम्नानुसार add_settings_field() Function को Call किया है:

	add_settings_field(			//Adding Field
		'txtgaUA', 
		'Enter Google Analytics UA-000000 ID', 
		'gaInputUAID_Callback',		//Declaring Field's Callback Function
		'ga-configuration', 
		'gaAdminMainSection-ID'
	);

फिर इस Newly Created Field को Page पर Visually Represent करने के लिए हमने निम्नानुसार तरीके से Field की Value को wp_options Table से Get/Set करने के लिए Callback Function को Define किया है जो कि एक Input Element Create करता है:

//Implementing Section’s Callback Function to Display and Fill the Form Field
function gaInputUAID_Callback() {
	//Get option 'text_string' value from the database
	$options = get_option( 'UA' );
	$text_string = $options['text_string'];
		
	//Echo the Field
	echo "<input id='text_string' name='UA[text_string]' type='text' value='$text_string'/>";
}

सरल शब्दों में कहें तो add_options_page(), add_settings_section() व add_settings_field() तीनों API Functions आपस में एक दूसरे से सम्बंधित हैं। क्योंकि तीनों ही API Functions के चौथे Parameter का मान समान होता है, जो कि हमारे Plugin के लिए Create किए गए Configuration Page के Slug को Represent करता है।

जिसकी वजह से WordPress Engine को इस बात का पता चल जाता है कि add_settings_field() API Function द्वारा जो नया HTML Input Element Create किया जाएगा, उसे किस Page Section पर Add करना है और जिस Page Section पर Add करना है, उस Page Section को किस Configuration Page पर Add किया गया है।

जबकि एक ही Configuration Page पर एक ही विषय से सम्बंधित एक से ज्यादा Sections Create किए जा सकते हैं, इसलिए add_settings_field() API Function द्वारा किस Section में नए HTML Input Element को Add करना है, इस बात को तय करने के लिए इस Function के पांचवें Parameter के रूप में add_settings_section() API Function के पहले Parameter के रूप में Specified Value को ही Specify किया जाता है, जो कि उस Section का Unique ID होता है।

add_settings_section() व add_settings_field() इन दोनों API Functions में तीसरे Parameter के रूप में एक Callback Function को Specify किया जाता है। ये Callback Function ही add_settings_section() API Function के माध्‍यम से एक Section Create करता है, जबकि add_settings_field() API Function के माध्‍यम से इस Newly Created Section में एक नया HTML Input Field Create करता है।

add_settings_field() व add_settings_section() इन दोनों API Functions में पहले Parameter के रूप में एक ID Specify किया जाता है। ये ID, इन Functions में Specified Callback Functions द्वारा Newly Create होने वाले Section का Unique ID होता है, जो उस Newly Created Section को Uniquely Identify करने काम करता है। register_setting() API Function के तीसरे Parameter के रूप में भी हमने निम्नानुसार एक API Function को Specify किया है:

        register_setting(‘UniqueID‘, ‘UA‘, ‘gaValidateOptions‘);      //Setting Registration

इस API Function के तीसरे Parameter के रूप में हमने gaValidateOptions() नाम का एक Sanitize Callback Function Specify किया है, जिसे निम्नानुसार Implement किया गया है:

// Validate user input (we want text only)
function gaValidateOptions( $input ) {
	$valid = array();
	$valid['text_string'] = preg_replace('/[^a-zA-Z]/','',$input['text_string'] );
	return $valid;
}

ये Callback Function, Input के रूप में आने वाले Setting की Value को इस बात के लिए Validate करता है कि Input किया गया Content केवल Text ही हो कोई Numerical या Special Symbol Content न हो।

Rendering the Form

उपरोक्तानुसार सारे काम करने के बाद अन्त में हमने अपने Plugin से सम्बंधित Configuration Page को Render करना होता है और इस जरूरत को पूरा करने के लिए हमने हमारे Plugin Code में अपने Form को निम्नानुसार Define किया है:

<?php 
//Draw the Google Analytics Configuration Page
function gaConfiguration(){
?>
<div class="wrap">
	<?php screen_icon(); ?>
	<h2>Google Analytics Configuration</h2>
	<form action="options.php" method="post">
		<?php settings_fields('UniqueID'); ?>
		<?php do_settings_sections('ga-configuration'); ?>
		<input name="Submit" type="submit" value="Save Changes" />
	</form>
</div>
<?php } ?>

इस Code में हमने settings_fields() व do_settings_sections() नाम के दो Settings API Functions को Use किया है।

continue…