Professional WordPress Plugin Development. Brad Williams
add_settings_section( 'pdev_plugin_main', 'PDEV Plugin Settings', 'pdev_plugin_section_text', 'pdev_plugin' ); // Create our settings field for name add_settings_field( 'pdev_plugin_name', 'Your Name', 'pdev_plugin_setting_name', 'pdev_plugin', 'pdev_plugin_main' ); // Create our settings field for favorite holiday add_settings_field( 'pdev_plugin_fav_holiday', 'Favorite Holiday', 'pdev_plugin_setting_fav_holiday', 'pdev_plugin', 'pdev_plugin_main' ); // Create our settings field for beast mode add_settings_field( 'pdev_plugin_beast_mode', 'Enable Beast Mode?', 'pdev_plugin_setting_beast_mode', 'pdev_plugin', 'pdev_plugin_main' ); } // Draw the section header function pdev_plugin_section_text() { echo '<p>Enter your settings here.</p>'; } // Display and fill the Name text form field function pdev_plugin_setting_name() { // Get option 'text_string' value from the database $options = get_option( 'pdev_plugin_options' ); $name = $options['name']; // Echo the field echo "<input id='name' name='pdev_plugin_options[name]' type='text' value='" . esc_attr( $name ) . "'/>"; } // Display and select the favorite holiday select field function pdev_plugin_setting_fav_holiday() { // Get option 'fav_holiday' value from the database // Set to 'Halloween' as a default if the option does not exist $options = get_option( 'pdev_plugin_options', [ 'fav_holiday' => 'Halloween' ] ); $fav_holiday = $options['fav_holiday']; // Define the select option values for favorite holiday $items = array( 'Halloween', 'Christmas', 'New Years' ); echo "<select id='fav_holiday' name='pdev_plugin_options[fav_holiday]'>"; foreach( $items as $item ) { // Loop through the option values // If saved option matches the option value, select it echo "<option value='" . esc_attr( $item ) . "' ".selected( $fav_holiday, $item, false ).">" . esc_html( $item ) . "</option>"; } echo "</select>"; } // Display and set the Beast Mode radio button field function pdev_plugin_setting_beast_mode() { // Get option 'beast_mode' value from the database // Set to 'disabled' as a default if the option does not exist $options = get_option( 'pdev_plugin_options', [ 'beast_mode' => 'disabled' ] ); $beast_mode = $options['beast_mode']; // Define the radio button options $items = array( 'enabled', 'disabled' ); foreach( $items as $item ) { // Loop the two radio button options and select if set in the option value echo "<label><input " . checked( $beast_mode, $item, false ) . " value='" . esc_attr( $item ) . "' name='pdev_plugin_options[beast_mode]' type='radio'/> " . esc_html( $item ) . "</label><br/>"; } } // Validate user input for all three options function pdev_plugin_validate_options( $input ) { // Only allow letters and spaces for the name $valid['name'] = preg_replace( '/[^a-zA-Z\s]/', '', $input['name'] ); if( $valid['name'] !== $input['name'] ) { add_settings_error( 'pdev_plugin_text_string', 'pdev_plugin_texterror', 'Incorrect value entered! Please only input letters and spaces.', 'error' ); } // Sanitize the data we are receiving $valid['fav_holiday'] = sanitize_text_field( $input['fav_holiday'] ); $valid['beast_mode'] = sanitize_text_field( $input['beast_mode'] ); return $valid; } ?>
Adding Fields to an Existing Page
You have seen how to create a new custom settings page for a plugin and its associated entry in the administration menus. Doing so makes sense if your plugin features a lot of settings and its administration page shows a lot of content.
Sometimes, though, it is not worth adding a new menu entry for just one or a few plugin options. Here again the Settings API will prove to be useful, allowing plugin setting fields to easily be added to the existing WordPress setting pages.
How It Works
Two internal functions, do_settings_sections() and do_settings_fields(), are triggered to draw sections and fields that have been previously registered, like you did in the example plugin.
Each core setting page calls these two functions, so you can hook into them if you know their slug name.
Adding a Section to an Existing Page
Your previous plugin was adding a whole new section and its input field on a stand‐alone page. You now modify it to insert this content into WordPress’ Privacy Settings page.
<?php $args = array( 'type' => 'string', 'sanitize_callback' => 'pdev_plugin_validate_options', 'default' => NULL ); register_setting( 'reading', 'pdev_plugin_options', $args ); add_settings_section( 'pdev_plugin_options', 'PDEV Plugin Settings', 'pdev_plugin_section_text', 'reading' ); add_settings_field( 'pdev_plugin_text_string', 'Your Name', 'pdev_plugin_setting_name', 'reading', 'pdev_plugin_options' ); ?>
Notice that the first parameter passed in the register_setting() function call is set to reading. This function now adds your custom section into the reading section, which is located within the Reading Settings page, as shown in Figure 3‐6. Replace all reading instances with media, and your section will be appended at the end of the Media Settings page.
FIGURE 3‐6: Section appended
You still need to whitelist this setting, with register_setting(). Omitting this step would make WordPress ignore the setting when submitting the form.
Adding Only Fields
Of course, it can even make sense to add just one field and no section header to an existing page. Now modify the function in the previous example as shown here:
<?php function pdev_plugin_admin_init(){ $args = array( 'type' => 'string', 'sanitize_callback' => 'pdev_plugin_validate_options', 'default' => NULL ); register_setting( 'reading', 'pdev_plugin_options', $args ); add_settings_field( 'pdev_plugin_text_string', 'Your Name', 'pdev_plugin_setting_name', 'reading', 'default' ); } ?>
Your singular field will be added to the default field set of the reading section, as shown in Figure 3‐7.
FIGURE 3‐7: Singular field
WordPress’ Sections and Setting Fields
To add a section to an existing page or a field to an existing section, all you need to know is the slug name of the page. Table 3‐1 includes every section and field set names found in the WordPress Settings pages.
TABLE 3-1: List of Core Sections and Fields
| WORDPRESS’ SETTINGS PAGES | SECTION NAMES | FIELD SET NAMES |
General Settings (options‐general.php)
|
general
|
default
|
Writing Settings (options‐writing.php)
|
writing
|
default remote_publishing post_via_email
|
Reading Settings (options‐reading.php)
|
reading
|