Wordpress Plugin Tutorial Part IX - Setting the Options

In part eight of the tutorial series we looked at how to add an admin page. On this tutorial we will see how to save the settings to the database and how to retrieve those options. We will also have to change the contents of the options page to utilize the Settings API.

First of all we must specify that we are planning to modify a setting. In order to do this we will use the register_setting function. We will hook into the 'admin_init' action and call the register _setting function.

To do this add the following line to the constructor of the CustomCommentMessage class.

add_action('admin_init', 
           array(&$this, 'ccm_admin_init') );

We define the 'ccm_admin_init' function as follows.

function ccm_admin_init(){
    //register the setting so that we can modify it
    //the first parameter is the options group
    //the second parameter is the option name
    register_setting( 'ccm_options',
                      'ccm_title_reply' );

    //We add a settings section to the page
    add_settings_section('ccm_main',
                         'Custom Comment Message',
                         array(&$this,'ccm_section_text'),
                         plugin_basename(__FILE__));

    //We add a settings field to the section
    //we added above. The fifth parameter is the id
    //of the settings section created above
    add_settings_field('plugin_text_string',
                       'Default Comment Message',
                       array(&$this,'ccm_setting_string'),
                       plugin_basename(__FILE__),
                       'ccm_main');

}

In both the above functions the fourth parameter is the 'page'  on which they are to be shown.
Below is a screenshot that shows what a settings section and a settings field are.

Note that a callback function is specified in the 'add_settings_section' and 'add_settings_field' functions. It is these callback functions that print the contents out. The code for the callback functions are given below.

//This function prints out the contents of the section
function ccm_section_text() {
?>
    <p>Set the default comment 
         message that you would like to use.</p>
<?php
}

//This function prints out the contents of the field
function ccm_setting_string() {
    $option = get_option('ccm_title_reply');
?>
    <input id='plugin_text_string' 
           name='ccm_title_reply' 
           size='40'
           type='text' 
           value="<?php echo wp_kses_data($option); ?>" />
<?php
}

Note that we call the get_option function to retrieve the value of the option 'ccm_title_reply'. All functions above should go in the "CustomCommentMessage" class. We send the $option value through the function 'wp_kses_data' to validate the value so that we are secure against Cross Site Scripting attacks. You can read more about this at the data validation page.

Finally we have to edit the function 'print_ccm_admin_page' to look like shown below.

function print_ccm_admin_page(){
?>
<div>
  <form method="post" 
        action="options.php">

    <?php settings_fields('ccm_options'); ?>
    <?php do_settings_sections(plugin_basename(__FILE__)); ?>

    <input type="submit" 
           value="Save Changes"
           name="Submit"/>
  </form>
</div>
<?php

}

The function 'settings_fields' prints a nonce field and some other fields to the page. By using the 'Settings API' we avoid the need to manually set nonce fields, which makes the task easier. Remember to pass into the 'settings_field' function, the options group that we used in the 'register_settings' function.
Next we call the 'do_settings_sections' function that will output the sections. We must pass into this function the 'page' that we passed to the 'add_settings_field' and 'add_settings_section' functions.

After doing the above modifications you will see that the values that after you save the settings they are saved to database and shown to you when you visit the settings page.