Create Custom Option Panels with WordPress 2.9
WordPress is a powerful engine in itself, but sometimes themes need options that fall outside the core dashboard. The good news is that putting these changes into motion is not as complex as it once was. This is where custom option panels come in.
In this tutorial we’ll use a custom options panel to insert analytic tracking codes. This will be done using the recent WordPress 2.9 updates to options. The same fundamentals can be carried over to a number of other custom field applications in you own themes.
Option Panel Fundamentals
Custom option panels are a way of expanding options for a specific theme. The big idea allows non-developers to maintain a high level of control over a theme. The average blogger shouldn’t have to spend time learning WordPress tags and PHP fundamentals in order to make simple changes like design elements or content sources. One panel might be responsible for social media accounts like Twitter or Flickr, while another might be for background images.
We’ve covered WordPress option panels before in our “How to Add an Announcement Box to Your WordPress Theme” tutorial. Since then, advances in the template tags and documentation have made basic options much easier to make. Less headache is a great thing.
The Goal
Our custom options panel will allow a blog administrator to paste in tracking codes (e.g. Google Analytics) which will be added into the theme’s code automatically. This will make updating (or appending) the tracking code easy to do without leaving the administrative dashboard.
This tutorial combines and simplifies several of the articles found in the WordPress Codex. If you get stuck or would like to see about additional options that do not appear here, I’ve linked to the source articles at the end of this post.
Creating the Files
Create a new folder called “functions” inside the root of your theme folder. This folder is where the code will live, and keeps it neatly separated from the standard functions. Within that folder, create a new PHP file called “admin-menu.php”. This file will contain all functions related to option panel creation and management.
In order to have WordPress recognize this new folder, we’ll need to reference it from within the functions.php file. Open it up and paste in the following block to add our new file to the mix:
<?php // Load main options panel file require_once (TEMPLATEPATH . '/functions/admin-menu.php'); ?>
Need to check a MySQL database value directly at any point? WordPress saves all custom fields and options into the wp_options table by default. If the values are written correctly, you should see the results there.
Build the Options Panel
The options panel will be built and called using four functions. Three of this functions will be within the admin-menu.php file created in the last step. I’ve broken them down in order of appearance (copy in accordingly). Please keep in mind that you can change the function names used as long as all other references are updated too.
Function omr_create_menu
This function is responsible for creating a new dashboard menu item in the sidebar via the add_menu_page hook. The hook specifies the title for the page (Build Internet) as well as which function should construct the option panel (omr_settings_page). After the first hook is initiated, the register_settings function will be called.
<?php
// create custom plugin settings menu
add_action('admin_menu', 'omr_create_menu');
function omr_create_menu() {
//create new top-level menu
add_menu_page('Build Internet Settings', 'Build Internet', 'administrator', __FILE__, 'omr_settings_page', 'favicon.ico');
//call register settings function
add_action( 'admin_init', 'register_mysettings' );
}
Function register_mysettings
The register_setting function is responsible for declaring a new setting, and arranging it into groups as needed. We’ll be using it here in minimal capacity. For larger control panels, grouping would become a more important way of keeping organized.
function register_mysettings() {
//register our settings
register_setting( 'omr-settings-group', 'omr_tracking_code' );
}
Function omr_settings_page
This function is where the form and structure of the options panel is declared. The WordPress dashboard has a series of default CSS styles assigned to elements, and this form will be automatically formatted upon creation.
Notice that the “omr-settings-group” is declared before any inputs appear. This makes sure that the field(s) we specified in the last step are loaded. Once loaded, the get_option function loads in the current value from the database. This will keep the theme from overwriting the database values with blank fields every time an edit is made.
function omr_settings_page() {
?>
<div class="wrap">
<h2>Build Internet Options</h2>
<form method="post" action="options.php">
<?php settings_fields('omr-settings-group'); ?>
<table class="form-table">
<tr valign="top">
<th scope="row">Tracking Code</th>
<td><textarea name="omr_tracking_code"><?php echo get_option('omr_tracking_code'); ?></textarea></td>
</tr>
</table>
<p class="submit">
<input type="submit" class="button-primary" value="<?php _e('Save Changes') ?>" />
</p>
</form>
</div>
<?php } ?>
The submit button’s value is set to <?php _e('Save Changes') ?>, which will commit changes to the database. No extra work required!
Accessing the Stored Value
Once you’ve saved a custom option to the database, you’ll still need to access it for output in the theme. This is done using the get_option function available in WordPress. Open up your theme’s footer.php file and we’ll demonstrate by placing the analytics code. Copy the following in immediately above the closing <body> tag:
<?php
//Display Google Analytics, etc.
echo get_option('omr_tracking_code');
?>
If everything is working properly, you should see the value of the option output in the live version.
Exploring Possibilities
Inserting analytic codes is obviously one of the less exciting uses of option panels. Similar methods can be used for announcements, “Image of the Day”, or a number of other innovative ways. Have any good ideas or suggestions for further uses? Share them (and any troubles) in the comments below. If anyone needs a downloadable version, please let me know and I’ll put one together. A modified set of files is available for download below. It was built off of the principles found in this tutorial.
