Create an Options Page

WordPress 2.7 introduced a new Settings API that you will be using for all of the option methods you use in this section. The Settings API is a powerful set of functions to help make saving options in WordPress easy and secure. One of the major benefits of the Settings API is that WordPress handles the security checks, meaning you don't need to include a nonce in your form.

The first option page method you'll explore is creating a unique option page for your top-level menu. Remember that when using the add_menu_page and add_submenu_page functions you defined your menu item function name to display your options page. To create an options page you need to create this function to display your options. First set up your plugin menu:

// create custom plugin settings menu add_action('admin_menu', 'gmp_create_menu');

function gmp_create_menu() {

//create new top-level menu add_menu_page('GMP Plugin Settings', 'GMP Settings', 'administrator', __FILE__, 'gmp_settings_page', plugins_url('/images/wordpress.png',__FILE__));

//call register settings function add_action( 'admin_init', 'gmp_register_settings' );

Notice you've added a new Action hook for admin_init to execute your gmp_register_settings function as shown in the following code:

<?php function gmp_register_settings() { //register our settings register_setting( 'gmp-settings-group register_setting( 'gmp-settings-group register_setting( 'gmp-settings-group

Using the Setting API's register_setting function you define the three options you are going to offer on your plugin options page. The first parameter is the options group name. This required field needs to be a group name to identify all options in this set. The second parameter is the actual option name and must be unique. Now that you've registered your options you need to build your options page. To do so you'll create the gmp_settings_page function as called from your menu:

<div class="wrap">

<h2><?php _e('GMP Plugin Options', 'gmp-plugin') ?></h2>

<form method="post" action="options.php">

<?php settings_fields( 'gmp-settings-group' ); ?> <table class="form-table"> <tr valign="top">

<th scope="row"><?php _e('Name', 'gmp-plugin') ?></th> <td><input type="text" name="gmp_option_name" value="<?php echo get_option('gmp_option_name'); ?>" /></td> </tr>

<th scope="row"><?php _e('Email', 'gmp-plugin') ?></th> <td><input type="text" name="gmp_option_email" value="<?php echo get_option('gmp_option_email'); ?>" /></td> </tr>

', 'gmp_option_name' ) ; ', 'gmp_option_email' ); ', 'gmp_option_url' );

<th scope="row"><?php _e('URL', 'gmp-plugin') ?></th> <td><input type="text" name="gmp_option_url" value="<?php echo get_option('gmp_option_url'); ?>" /></td> </tr> </table>

<p class="submit"> <input type=Msubmit" class="button-primary"

value="<?php _e(1 Save Changes', 'gmp-plugin') ?>" />

As you can see this looks like a standard form with a couple noticeable differences. The <form> tag must be set to post to options.php. Inside your form you need to define your settings group, which you set to gmp-settings-group when you registered your settings. This establishes the link between your options and their values. You do so with this line of code:

Next you build the table to display your form options. Notice the name of the form field needs to be exactly the same as the option names you registered. You also use the get_option function to retrieve the value of your plugin option. The Settings API will store all option values in wp_options so you can retrieve your option values anywhere inside of WordPress using get_option:

After you have displayed all of your form fields you need to display a Submit button to post the form and save your options. That's it! You have just created a very basic plugin options page using the Settings API in WordPress. Listing 7-1 shows the entire code to build an options page.

LISTING 7-1: Building the Options Page

//execute our settings section function

// create custom plugin settings menu add_action('admin_menu', 'gmp_create_menu');

function gmp_create_menu() {

//create new top-level menu add_menu_page('GMP Plugin Settings', 'GMP Settings', 'administrator' ,__FILE__, 'gmp_settings_page', plugins_url('/images/wordpress.png',__FILE__));

//call register settings function add_action( 'admin_init', 'gmp_register_settings' );

function gmp_register_settings() { //register our settings register_setting( 'gmp-settings-group', 'gmp_option_name' );

register_setting( 'gmp-settings-group', 'gmp_option_email' );

register_setting( 'gmp-settings-group', 'gmp_option_url' );

<?php settings_fields( 'gmp-settings-group' ); ?>

<input type="text" name="gmp_option_email" value="<?php echo get_option('gmp_option_email'); ?>" />

Available for download on Wrax.com

<div class="wrap">

<h2><?php _e('GMP Plugin Options', 'gmp-plugin') ?></h2>

<form method="post" action="options.php">

<?php settings_fields( 'gmp-settings-group' ); ?> <table class="form-table"> <tr valign="top">

<th scope="row"><?php _e('Name', 'gmp-plugin') ?></th> <td><input type="text" name="gmp_option_name" value="<?php echo get_option('gmp_option_name'); ?>" /></td> </tr>

<th scope="row"><?php _e('Email', 'gmp-plugin') ?></th> <td><input type="text" name="gmp_option_email" value="<?php echo get_option('gmp_option_email'); ?>" /></td> </tr>

<th scope="row"><?php _e('URL', 'gmp-plugin') ?></th> <td><input type="text" name="gmp_option_url" value="<?php echo get_option('gmp_option_url'); ?>" /></td> </tr> </table>

<p class="submit">

<input type="submit" class="button-primary" value="<?php _e('Save Changes', 'gmp-plugin') ?>" /> </p>

The second option page method is adding your plugin settings to an existing Settings page in WordPress as shown in Figure 7-3. You will also be using the WordPress Settings API functions to hook into these pages and add your plugin settings. Remember that the Settings API was added in version 2.7, so any older installations will not have these functions available for use. First you'll start with creating a new settings section using the add_settings_section function.

Now look over at the code to create your custom settings section. In the following example you are going to add a new settings section at the bottom of the Settings O Reading Settings page. This section will contain options for your plugin.

//execute our settings section function add_action('admin_init', 'gmp_settings_init');

function gmp_settings_init() {

//create the new setting section on the Settings > Reading page add_settings_section('gmp_setting_section', 'GMP Plugin Settings', 'gmp_setting_section', 'reading');

// register the individual setting options add_settings_field('gmp_setting_enable_id' , 'Enable GMP Plugin?',

'gmp_setting_enabled', 'reading', 'gmp_setting_section');

add_settings_field('gmp_saved_setting_name_id' , 'Your Name',

'gmp_setting_name', 'reading', 'gmp_setting_section');

// register our setting to store our array of values register_setting('reading','gmp_setting_values');

5? Kriirfmg Springs frampog» HWI»V> * Tour blrtl pürtj

rtunr Fv «ach jftxfe n j

Li"isikiu la um «d Mi 'J" ' (IMP Plugin Selling*

FIGURE 7-3: Custom settings section

14 nA

First you use the admin_init Action hook to load your custom function gmp_settings_init before any admin page is rendered. Next you call the add_settings_section function to create your new section:

<?php add_settings_field('gmp_setting_enable_id', 'Enable GMP Plugin?', 'gmp_setting_enabled', 'reading', 'gmp_setting_section'); ?>

The first parameter passed is a unique ID for the section. The second parameter is the display name output on the page. Next you pass in the callback function name to display the actual section itself. The final parameter sets what settings page to add your section to. The accepted values are general, writing, reading, discussion, media, privacy, permalink, and misc.

<?php add_settings_field('gmp_setting_ enable_id', 'Enable GMP Plugin?', 'gmp_setting_enabled', 'reading', 'gmp_setting_section'); add_settings_field('gmp_saved_setting_name_id', 'Your Name',

'gmp_setting_name', 'reading', 'gmp_setting_section'); ?>

Now that you've registered your custom settings section you need to register your individual setting options. To do this you'll be using the add_settings_field function. The first parameter you are passing is a unique ID for the field. Next you pass in the title of the field, which is displayed directly to the left of the option field. The third parameter is the callback function name, which you'll use to display your option field. The fourth parameter is the settings page where the field should be displayed. The final parameter is the name of the section you are adding the field to, which in this example is the gmp_setting_section you created with the add_setting_section function call.

<?php register_setting('reading','gmp_setting_values'); ?>

Next you need to register your setting field. In this example you are going to register two different settings: one for an enable/disable checkbox and one for the user's name. Even though you have two setting fields you are going to store both values in an array, so you only need to register one setting called gmp_setting_values. The first parameter you pass is the option group. In this example you are saving your options in the reading group with the rest of the reading options. The second parameter is the option name. The option name should be unique and is used to retrieve the value of the option. A third optional value can be passed that is a custom function name used to sanitize the option values.

Now that you've registered your setting section you need to create your custom functions to display it. The first function you'll create is the gmp_setting_section you called in when you created your setting section:

<?php function gmp_setting_section() {

echo '<p>Configure the GMP Plugin options below</p>';

This is where you can set the subheading for your settings section. This section is great for plugin instructions, configuration information, and more. Next you need to create the function to display your first settings field, Enabled:

<?php function gmp_setting_enabled() { //load our options array

$gmp_options = get_option('gmp_setting_values');

// if the option exists the checkbox needs to be checked If ($gmp_options['enabled']) {

//display the checkbox form field echo '<input '.$checked.' name="gmp_setting_values[enabled]" type="checkbox" />

This is the callback function you defined when you used the add_settings_field function. The first step is to load the options array if it exists. Because this option is a checkbox you know that if it is set, the checkbox should be checked. Next you display the actual setting field that will be used in the setting section. Your field input name needs to be the same setting name you registered previously. Because you are saving your options as an array you need to define the array name value; in this example gmp_setting_values [enabled]. This is how the Settings API knows what option to save and where. Now your Enabled checkbox field will display at the bottom of the Settings O Reading page. Now you need to create the function for your second setting field:

<?php function gmp_setting_name() { //load the option array

$gmp_options = get_option('gmp_setting_values');

//load the proper array option value $name = $gmp_options['name'];

//display the text form field echo '<input type="text" name="gmp_setting_values[name]" value="'.esc_attr($name).'" />';

Just like with your checkbox option, the first thing to do is load the current option value. Next you display your input text field with the same name as defined above in the register_setting function. That's it! You have successfully created your custom settings section and added it to the Settings O Reading SubPanel. Listing 7-2 shows the full code.

nig 7-2: Custom Settings Section

//execute our settings section function add_action('admin_init', 'gmp_settings_init');

function gmp_settings_init() {

//create the new setting section on the Settings > Reading page add_settings_section('gmp_setting_section', 'GMP Plugin Settings', 'gmp_setting_section', 'reading');

// register the individual setting options add_settings_field('gmp_setting_enable_id', 'Enable GMP Plugin?', 'gmp_setting_enabled', 'reading', 'gmp_setting_section'); add_settings_field('gmp_saved_setting_name_id', 'Your Name', 'gmp_setting_name', 'reading', 'gmp_setting_section');

Available for download on Wrox.com

// register our setting to store our array of values register_setting('reading','gmp_setting_values');

// settings section function gmp_setting_section() {

echo '<p>Configure the GMP plugin options below</p>';

// create the enabled checkbox option to save the checkbox value function gmp_s ett ing_enabled() {

// if the option exists the checkbox needs to be checked $gmp_options = get_option('gmp_setting_values'); If ($gmp_options['enabled']) {

//display the checkbox form field echo '<input '.$checked.' name="gmp_setting_values[enabled]" type="checkbox" />

// create the text field setting to save the name function gmp_setting_name() { //load the option value

$gmp_options = get_option('gmp_setting_values'); $name = $gmp_options['name'];

//display the text form field echo '<input type="text" name="gmp_setting_values[name]" value="'.esc_attr($name).'" />' ;

Was this article helpful?

0 0

Post a comment