Theme Options API

WP Framework comes packaged with a set of functions for creating a customized theme options page tailored specific to your WordPress theme. By the end of this guide, you’ll learn how to create a theme options page, add and remove settings, and interface with your theme options database directly using WP Framework’s Theme Options API.

The 411

When you download and activate WP Framework, it adds an option to the database containing WP Framework’s version number. The name of the option is the actual name of the your WordPress theme’s folder name with a suffix of “_theme_options”. So if the folder name is titled wpframework, the options name is wpframework_theme_options. This allows you to use WP Framework in several WordPress themes instead of having them all share the same theme settings.

For your convenience, WP Framework has a constant named THEMEOPTIONS so you don’t have to keep track of the options name. Just call get_option( THEMEOPTIONS ); and your all set.

By default WP Framework also checks to see if the settings in the database exists, so if the version number was ever erased or the settings in the database was ever completely wiped out, it would preform an install and set everything back to their defaults.

Theme Options Page

When you download and activate WP Framework for the first time, you won’t see your theme options page. That’s because you haven’t added anything yet! This configuration is provided as a convenience so you can choose to enable or disable the theme options page entirely. Alright, so now that we understand what’s going on behind the scenes, let’s get started!

The first thing we have to do is add a meta box (section) to the theme options page.

Adding Sections

function custom_theme_options() {
	framework_add_metabox( 'example-1', 'Example Metabox #1', 1 );
	framework_add_metabox( 'example-2', 'Example Metabox #2', 2 );
	framework_add_metabox( 'example-3', 'Example Metabox #3', 3 );
}
add_action( 'framework_hook_theme_options', 'custom_theme_options' );

What this code does is wrap framework_add_metabox() into a function called custom_theme_options(), which is then hooked into framework_hook_theme_options.

This step is necessary in order to get the metabox registered and displayed onto the theme options page. If the theme options page didn’t exists before, it will now.

Here’s a list of all available parameters to framework_add_metabox():

  1. $id - String for use in the ‘id’ attribute of tags.
  2. $title - Title of the meta box.
  3. $column - Registers the metabox to a specific column (1, 2, or 3).
  4. $priority - The priority within the column the metabox should be shown ( ‘high’, ‘core’, ‘default’, ‘low’ ).

You can also add multiple metaboxes at once using framework_add_metaboxes(); Just create an multidimensional array containing all the metaboxes:

function custom_theme_options() {
	$metaboxes = array(
		array(
			'id' => 'example-1',
			'title' => 'Example Metabox #1',
			'column' => 1,
		),
		array(
			'id' => 'example-2',
			'title' => 'Example Metabox #2',
			'column' => 2,
		),
		array(
			'id' => 'example-3',
			'title' => 'Example Metabox #3',
			'column' => 3,
		),
	);
	framework_add_metaboxes( $metaboxes );
}
add_action( 'framework_hook_theme_options', 'custom_theme_options' );

Adding Settings to a Metabox

First, we have to register the option into database.

framework_add_option( 'my_option', 'Stuff' );

Now, let’s add a setting to one of the metaboxes. We’re going to add it to our custom_theme_options function.

function custom_theme_options() {
	framework_add_metabox( 'example-1', 'Example Metabox #1', 1 );
	framework_add_metabox( 'example-2', 'Example Metabox #2', 2 );
	framework_add_metabox( 'example-3', 'Example Metabox #3', 3 );
	framework_add_setting( 'example-1', 'textfield', 'my_option', 'Label for my option' );
}
add_action( 'framework_hook_theme_options', 'custom_theme_options' );

framework_add_metabox() accepts 4 parameters:

  1. $section - The id of the section the setting should be located under.
  2. $type - textfield|textarea|checkbox|radio|function
  3. $name - String for use in the ‘id’ and ‘name’ attribute, Or the function callback.
  4. $label - Text used for the label tag.

And now you have a text field under “Example Metabox #1.”

framework_add_metabox() handles all the underlying work involved in displaying your text field by adding all the correct attributes to the form element. But sometimes, you might need control over that for advanced settings. framework_add_metabox() also allows you to use your own function for displaying the form element:

framework_add_setting( 'example-1', 'function', 'custom_settings_field' );

Then, just define custom_settings_field:

function custom_settings_field( $options ) {
	$value = $options['my_option'];
	if ( $value ) {
		$value = ' value ="'. $value .'"';
	} else {
		$value = '';
	}
	echo '<input type="text" id="my_option" name="'. THEMEOPTIONS .'[my_option]" '. $value .' />';
}

Note that the $options variable is past to your function which contains all the settings for your theme (for convenience).

When using a function to display your form fields, remember to add the correct attributes. The name attribute should be the name="THEMEOPTIONS[option_name]" If you don’t prefix the name with THEMEOPTIONS[], then the option won’t get saved to the database.

Removing Settings from a Metabox

To remove a setting, just add framework_remove_setting() at the bottom of our custom_theme_options:

add_action( 'framework_hook_theme_options', 'remove_my_settings' );
function remove_my_settings() {
	framework_remove_setting( 'custom_settings_field' );
}

framework_remove_setting() takes only one parameter:

  1. $name - Name of the setting to be removed.

In order for framework_remove_setting() to work, it must be called after the setting was added.

Interfacing with the Theme Options database

All of your options are stored into one single database entry within the framework. WP Framework provides a few functions for adding, updating, and retrieving values from the database. You can also use these functions in template files, and other areas within your theme.

Adding Options

framework_add_option( 'my_option', true );

Updating Options

framework_update_option( 'my_option', false );

Retrieving Options

To retrieve an option stored in your theme’s db:

framework_get_option( 'my_option' );

To retrieve all the options stored in your theme:

get_option( THEMEOPTIONS );

Download WP Framework

Discuss WP Framework

Stop by the forums and get help with your customizations!

    It Seem There Is Something Wrong With BBLD Configuration, Please Check It.

WP Framework on Twitter!

Follow WP Framework and stay in the loop on WP Framework happenings!