Sections and Settings
Now define what the settings will be more precisely by using the function add_settings_field() and how they will be visually grouped with the function add_settings_section().
<?php add_settings_section( id, title, callback, page ); add_settings_field( id, title, callback, page, section, args ); ?>
The first function call, add_settings_section(), defines how the section on the page will show. The four required parameters it uses follow:
id: HTML ID tag for the section
title: Section title text that will show within an <H2> tag
callback: Name of the callback function that will echo some explanations about that section
page: Settings page on which to show the section (that is, the ?page=pdev_plugin part of the page URL)
The second function call, add_settings_field(), describes how to add the form input. Its required parameters follow:
id: HTML ID tag for the section
title: Formatted title of the field, which is displayed as the label for the field on output
callback: Name of the callback function that will echo the form field
page: Settings page on which to show the section
section: Section of the settings page in which to show the field, as defined previously by the add_settings_section() function call
args: Additional arguments used when outputting the field
Now let's implement these new functions for your plugin settings as follows:
<?php add_settings_section( 'pdev_plugin_main', 'PDEV Plugin Settings', 'pdev_plugin_section_text', 'pdev_plugin' ); add_settings_field( 'pdev_plugin_name', 'Your Name', 'pdev_plugin_setting_name', 'pdev_plugin', 'pdev_plugin_main' );
You now need to define two simple callback functions: one to display a few explanations about the section and one to output and fill the form field.
<?php // Draw the section header function pdev_plugin_section_text() { echo '<p>Enter your settings here.</p>'; } // Display and fill the Name 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 ) . "'/>"; }?>
This second function call fetches the option value name that is stored in an array.
When outputting the HTML input field, note its name. This is how you tell the browser to pass this value back into an array with the same name as the option you'll save, as defined earlier in the register_setting() function call. Any field that has not been previously registered and whitelisted will be ignored by WordPress.
You'll also notice you are using the esc_attr() function. This is used to escape the HTML attribute value for display. You'll learn more about this in Chapter 4.
Validating User Input
There is still one callback function to define, pdev_plugin_validate_options(), as mentioned earlier when registering the settings.
In this example, users are asked to enter text, so your validation function simply makes sure that the input contains only letters.
<?php // Validate user input (we want text and spaces only) function pdev_plugin_validate_options( $input ) { $valid = array(); $valid['name'] = preg_replace( '/[^a-zA-Z\s]/', '', $input['name'] ); return $valid; } ?>
To validate the user input as letters only, a simple pattern matching (also known as regular expression) that strips all other characters is used here. This regex pattern also supports spaces between names.
This function is passed the $_POST data as a parameter. For enhanced security, start creating a new empty array named $valid and collect in this array only the values you are expecting. This way, if for some reason an unanticipated field is submitted in the form, your function not only validates the information you want but also blocks everything else. Refer to Chapter 4 for more tips and functions about data validation.
Rendering the Form
Now that you have defined these function calls, it's time to use them. At the beginning of this step‐by‐step example, you created an empty page. Go back to that and add the form fields and a Submit button.
// Create the option page function pdev_plugin_option_page() { ?> <div class="wrap"> <h2>My plugin</h2> <form action="options.php" method="post"> <?php settings_fields( 'pdev_plugin_options' ); do_settings_sections( 'pdev_plugin' ); submit_button( 'Save Changes', 'primary' ); ?> </form> </div> <?php }
The settings_fields() function call references the whitelisted option you have declared with register_setting(). The only required parameter is the settings group name. This should match the group name used in register_setting(). It takes care of the hidden fields, security checks, and form redirection after it has been submitted.
The second function call, do_settings_sections(), outputs all the sections and form fields you have previously defined. The only required parameter for this function is the slug name of the page whose settings sections you want to output.
The final function is submit_button(), which will display the form submission button. This function is extremely handy when building any form in WordPress and accepts the following parameters:
text: Text displayed on the button.
type: Type and CSS class or classes of the button.
name: HTML name of the button.
wrap: Boolean that defines whether the output button should be wrapped in a paragraph tag. Defaults to true.
other_attributes: Additional attributes that should be output with the button, such as a tabindex.
An alternative method is using the get_submit_button() function. This function supports the same parameters, but instead of displaying the button, it will return the submit button. This is useful if you are compiling a form but not ready to fully display it yet.
All Done!
Notice how little HTML you have laid down, and yet the plugin page is now complete and functional. This is a major reason this Settings API is rock solid: you focus on features and let WordPress create all the HTML with relevant tags and classes, handle
