Adding Admin Options Page in WordPress

Posted in Tutorials

Let’s learn how to add a simple admin option in an new admim options page in WordPress.  This option is often used for users to save plugin or theme settings.

In this tutorial, we will be working on a theme called TwentyCustom which is a duplicate of the default TwentyThirteen theme (see tutorial here for details).  We will add an admin option for placing an copyright notice at the bottom  of the footer as shown…

2. First we need to add an administration menu in the WordPress dashboard.   For the sake of simplicity in a tutorial, we are going to add this code in the functions.php file of the TwentyCustom theme.  For those building plugins and themes, you may want to put in better place.

At the bottom of functions.php, we write the following to register the our custom_copyright_menu function under the admin_menu hook.

The parameter “admin_menu” must be “admin_menu”.  But the function name custom_copyright_menu is an arbitrary name that you give your function.  This means that whenever WordPress calls up the admin menu, it will run your function custom_copyright_menu.

3. We define the custom_copyright_menu function as follows (at the bottom of the functions.php file), which just calls the wordpress function add_options_page which does all the heavy lifting for us so we don’t have to.

4.  The add_options_page takes several parameters.  The first parameter is the title of your new admin page.  The second parameter is the text of the menu item for that page.  The third parameter is the capabilities.  Here, only the user with “manage_options” capabilities can see the menu item.  List of possible capabilities are here.

The 4th parameter is the unique identifier for this page so wordpress can use this identifier to bring up the page.  You can see how WordPress uses that in the query string above.

The 5th parameter is an arbitrary name for another function.  In this example, we give the name custom_copyright_options.  This function is called by add_options_page to display the actual options page.

5.  We define custom_copyright_options() as follows at the bottom of functions.php file…

function custom_copyright_options() {
    if ( !current_user_can( 'manage_options' ) )  {
        wp_die( 'You do not have sufficient permissions to access this page.' );
    }

    echo '<p>Enter your copyright notice here.</p>';
}

If the current user can not “manage_options”, call wp_die with the error message of “You do not have sufficient permissions to access this page”.  Otherwise render the options page.  For now, we just put “Enter your copyright notice here”.    For simplicity, we omitted the __() translation function.  But you can add if needed.

6. At this point you should have a “Copyright” menu under the “Settings” menu which shows the rendered page (as shown above).  The call to add_options_page adds the menu under “Settings”.  If you want your menu under “Tools” for example, call add_management_page instead.

7.  Now we add code to render our copyright admin options page more fully.   Change the code to …

Note how we we follow WordPress admin style by making call to screen_icon() and enclosing page in div of class=”wrap”.

8.  Now we create the form with text input of name “copyright_option_text” to save our copyright.  Re-arrange the code within the div class=”wrap” to be as follows…

Just follow this structure.  This is how WordPress wants it.  The only two things that are unique to our example is copyright_option_text and copyright_option-group.

Always have the form “post” to “options.php”.  Right after the form tag, call settings_fields() and do_settings_fields().  Feed both of them our value “copyright_options-group”.  The do_settings_fields has two arguments that are required as described in WordPress codex.  The second argument is described as …

“Slug title of the settings section whose fields you want to show. This should match the section ID used in add_settings_section().”

Since the second argument is not that applicable to us, let’s just put in an empty string.

Within our form is an input field with name value copyright_option_text and that is the name value that we feed the function get_option() for wordpress to retrieve that value from the database.

Finally, call submit_button().  WordPress will know what to do.

9. But we are not done.  For security reasons (known as whitelisting the options), we have to register our setting.   Remember how we called the admin_menu hook in the previous steps.  Right below that line is a good place (but does not have to be) to trigger the register_setting function (a wordpress function) via the admin_init hook.  But we wrap this call in our arbitrary-named function register_copyright_settings as shown …

Feed the register_setting function our two value of copyright_option-group and copyright_option_text as shown above.

10.  Try saving a value to our copyright options now. It should work like this…

11.  At this point, we can save new value to our option.  You can see all the “options values” (including our copyright_option_text) that WordPress is saving by going to /wp-admin/options.php …

12.  Putting it all together.  Here is the full code from the functions.php file…

/* Add Custom Admin Menu */
add_action( 'admin_menu', 'custom_copyright_menu' );
add_action( 'admin_init', 'register_copyright_settings');

function register_copyright_settings() {
    register_setting( 'copyright_option-group', 'copyright_option_text' );
};

function custom_copyright_menu() {
    add_options_page( 'Custom Copyright Options', 'Copyright', 'manage_options', 'custom-copyright-identifier', 'custom_copyright_options' );
}

function custom_copyright_options() {
    if ( !current_user_can( 'manage_options' ) )  {
        wp_die( 'You do not have sufficient permissions to access this page.' );
    }
?>

    <div>
        <?php screen_icon(); ?>
        <h2>Custom Copyright Option</h2>

        <form method="post" action="options.php">
            <?php 
            settings_fields( 'copyright_option-group' ); 
            do_settings_fields( 'copyright_option-group', '' );
            ?>

            <p>Enter your copyright notice here.</p>
            <input type="text" name="copyright_option_text" value="<?php echo get_option('copyright_option_text'); ?>" />

            <?php
            submit_button();
            ?>
        </form>
    </div>
<?php
}
?>

13. The only thing left to do is to be able to retrieve this saved option value from the footer template.  In the footer.php theme file. …

For more reference on creating admin options, see Codex and Otto’s tutorial.

 

---