Professional WordPress Plugin Development. Brad Williams
preceding code adds a submenu labeled PDEV Settings under the Settings menu, as shown in Figure 3‐3. Set the page title to PDEV Plugin Settings, set the capability to
manage_options so that only administrators can view it, and set the function pdev_plugin_option_page() to be called when the submenu is clicked.
FIGURE 3‐3: Submenu labeled PDEV Settings
The following is a list of all available submenu functions in WordPress:
add_dashboard_page: Adds a submenu to the Dashboard menu
add_posts_page: Adds a submenu to the Posts menu
add_media_page: Adds a submenu to the Media menu
add_links_page: Adds a submenu to the Links menu
add_pages_page: Adds a submenu to the Pages menu
add_comments_page: Adds a submenu to the Comments menu
add_theme_page: Adds a submenu to the Appearance menu
add_plugins_page: Adds a submenu to the Plugins menu
add_users_page: Adds a submenu to the Users menu
add_management_page: Adds a submenu to the Tools menu
add_options_page: Adds a submenu to the Settings menu
To use any of these functions, simply swap out the function name in the code shown earlier.
NOTE If your plugin requires only a single options page, it's best practice to add it as a submenu to an existing menu. If you require more than one, create a custom top‐level menu.
PLUGIN SETTINGS
Now that you've learned how to create menus and submenus in the WordPress Dashboard, it's time to create a settings page for your plugin. WordPress enables easy access to the database to store and retrieve data, such as options end users can modify and save in settings pages or internal information plugins you need to know. You'll learn how to save and fetch this data using the Options API and internal WordPress functions.
THE OPTIONS API
The Options API is a set of functions that enable easy access to the database where WordPress, plugins, and themes save and fetch needed information.
Options are stored in a database table named, by default, wp_options and can be text, integers, arrays, or objects. For example, WordPress keeps in this table the title of your blog, the list of active plugins, the news articles displayed on the Dashboard, or the time to check if a new version is available.
You'll now learn how to use the functions to access, update, and save options: add_option(), update_option(), get_option(), and delete_option().
Saving Options
You start by saving your first plugin option, which will be named pdev_plugin_color and have a value of red. The function call to do so is the following:
<?php add_option( 'pdev_plugin_color', 'red' ); ?>
The add_option()function accepts the following parameters:
option: Name of the option to add
value: Value of the option you are adding
deprecated: Description, which is no longer used
autoload: Whether to load the option when WordPress starts
The first parameter is your option name. It is crucial that you make it unique and self‐explanatory.
Unique: It will never conflict with internal existing or future WordPress options or with settings that might be created by another plugin.
Self‐explanatory: Name it so that it's obvious it's a plugin setting and not something created by WordPress.
NOTE Using the same prefix, for example, pdev_plugin, for function names, options, and variables is highly recommended for code consistency and for preventing conflict with other plugins. The golden rule of “Prefix everything,” first introduced in Chapter 2, applies here.
The second parameter is the option value that can be practically anything a variable can hold: string, integer, float number, Boolean, object, or array.
Saving an Array of Options
Every option saved adds a new record in WordPress’ option table. You can simply store several options at once, in one array. This avoids cluttering the database and updates the values in a single MySQL query for greater efficiency and speed.
$options = array( 'color' => 'red', 'fontsize' => '120%', 'border' => '2px solid red' ); update_option( 'pdev_plugin_options', $options );
Saving your plugin options in one array rather than individual records can have a huge impact on WordPress’ loading time, especially if you save or update many options. Most of the time, PHP code executes fast, but SQL queries usually hinder performance, so save them whenever possible.
Updating Options
Now that you know how to create a new option for your plugin, let's look at updating that option value. To handle this, you'll use the update_option()function. As an example, let's update the color of your new plugin setting from red to blue.
<?php update_option( 'pdev_plugin_color', 'blue' ); ?>
The update_option()function accepts the following parameters:
option: Name of the option to update
value: Value of the option you are updating
autoload: Whether to load the option when WordPress starts
The difference between add_option() and update_option() is that the first function does nothing if the option name already exists, whereas update_option() checks if the option already exists before updating its value and creates it if needed.
Retrieving Options
To fetch an option value from the database, use the function get_option().
<?php $pdev_plugin_color = get_option( 'pdev_plugin_color' ); ?>
The first thing to know about get_option() is that if the option does not exist, it will return false. The second thing is that if you store Booleans, you might get integers in return.
The get_option()function accepts the following parameters:
option: Name of the option to retrieve
default: Value to return if the option does not exist. The default return value is false.
As an illustration of this behavior, consider the following code block that creates a couple of new options with various variable types:
<?php update_option( 'pdev_bool_true', true ); update_option( 'pdev_bool_false',