Learn about the Settings API, make a plan, and add your plugin settings. The steps outlined in this tutorial can be applied to any plugin and the code serves as a template that you can use when building your own plugins.
- [Instructor] Now that our plugin has its own menu item and settings page let's continue with plugin development and add the plugin settings. We will do this using the Settings API. The Settings API is great, because it provides built-in security and visual consistency, plus it handles all of the form processing, so less time is spent testing everything. Now for the plugin that we are building in this chapter the first step is planning. Exactly which settings do we need? Some plugins, like Hello Dolly, have zero settings.
The plugin just does its thing. Most plugins however do have settings, like Akismet. Akismet has its own sub-level menu item under the Settings menu. And it also has its own settings page where the plugin can be customized. Likewise for our plugin, the settings page is located under the Settings menu. So any options that we add will be displayed on this page. But before adding any code, let's do some basic planning.
Our plugin will display its settings in two sections. The first will include options to customize the login page and the second will provide options to customize the admin area. We also want to plan out the types of fields to use. Here are the HTML fields that we'll use for our plugin's settings. So we'll use at least one of each type of HTML field. In general, here are the types of fields that can be used in any plugin. Text inputs, radio inputs, checkboxes, textareas, and select menus.
There are some great resources online if you are unfamiliar with any of these fields. So that's the plan. Now let's add these settings to our plugin. To add a setting we first need to register it using the register setting function. To add this function we can grab the complete code from the Exercise Files, and then we can add it to the main plugin file, like so. With this function we register our plugin's options using the register_settings function.
The first parameter of this function specifies the name of the option group. This should match the parameter that we specified in the settings_fields function. We added this function in the previous video. So this must match this. Then the second parameter specifies the name of the option itself. We will use this name when retrieving the option from the database.
Lastly, the third parameter specifies the callback function that will be used to validate the settings. We'll create this callback function in a moment. Once the parameters are defined we register our function with the admin_init hook. This hook fires only in the admin area, so it's perfect for registering our plugin settings. Before continuing, let's define the callback function specified in the third parameter. This function will be used to validate our plugin settings. We can grab the code from the Exercise Files and then add it to the main plugin file, like so.
For now, this function simply returns the input variable. We'll add more to it in the upcoming video on validating plugin settings. So now, with these two functions, the register_settings function and the validation function, we've successfully registered our plugin settings. Next, we want to add two sections for our settings. To add our two settings sections we use the add_settings_section function.
To save time let's get the code from the Exercise Files. And then we can add the code to the existing function, myplugin_register_settings, just like so. This new code registers both of our settings sections. The first adds a section for our login page options and the second adds a section for our admin area options.
For each of these functions, the first parameter is the section ID. This value will be used later on when we add the individual settings. The second parameter is the title of the section, which will be displayed as the section heading wrapped in h2 tags. The third parameter is the callback function. The callback function will display a description of the section. We'll add the callback functions in a minute.
Lastly, the fourth parameter is the page on which the section should be displayed. This should match the menu slug specified in the add_submenu_page function. We defined this function in the previous video. So this must match this, and this. Basically this parameter tells WordPress where to display the section. So now with both sections in place we need to add the two callback functions.
We can grab the code from the Exercise Files and add it to the main plugin file. Each of these two functions echos the markup that we want to display for each section. Let's take a look. In the previous video this page was empty. Now that we have added the two sections and their callback functions the plugin page has something to display. Here we have the two sections. One of the Login Page options and one for the Admin Area options.
Here is the message displayed by the first callback function and here is the message displayed by the second callback function. The section titles are defined in the second parameter of each add_settings_section function, here and here. So at this point we have registered the plugin setting and added the two settings sections. The final step is to add the settings fields, which define the actual settings that our plugin will be using.
With everything in place we can begin adding our settings fields. To save time let's grab the complete code from the Exercise Files. This looks like a lot, but it's actually quite repetitive and easy to follow. Let's go ahead and add this code inside of our existing register_settings function. In this new code we are using the function add_settings_field to add each of our seven plugin settings.
We want to add four settings in the first section and three in the second section. So if we scroll through this code we can see seven functions, one for each of our seven settings. Two, three, four, five, six, and seven. Let's look at the parameters used for each of these functions. First, is the setting ID. We'll use this value when retrieving the setting from the database.
The second parameter is the title of the setting. It will be displayed next to the setting on the plugin page. The third parameter is the callback function, this function will output the markup required to display the setting. We'll add the callback functions in the next video. The fourth parameter specifies the page on which the setting should be displayed. This value should be the same as the menu slug specified in the add_submenu_page function right here.
So this should match this. Moving onto the fifth parameter, this specifies the section that should display the setting. It should match the section ID. We define the section ID in either of the add_settings_sections functions. We have myplugin_section_login and myplugin_section_admin.
So our first setting goes to the login section, likewise with our second, third, and fourth. And then three settings for the admin section. So once you have that we have the sixth parameter. This is an array that contains any data that we would like to pass to that callback function.
Anything is possible here. To make things easier, I like to include the field id and the label. This information will make things easier when writing the callback functions for each of our settings. And speaking of which, let's add the callback functions next. To save time we can grab the callback functions from the Exercise Files and then add the code at the end of our main plugin file. For now, these callback functions are just placeholders.
They output a simple message that tells us that they're working. We'll flesh out these callback functions in the next video. For now, let's recap what we've done so far. First, we create a function that will contain all of our settings functionality. This function is registered with the admin_init hook. Inside of this function we register our options, and then we add both of our settings sections, here and here.
And then we add each of our seven settings. Two, three, four, five, six, and seven. These first four settings are displayed in the first section of the plugin page. And these last three settings are displayed in the second section.
So again, four settings for the first section and three for the second section. So with everything in place let's view the results on the plugin page. Here we can see the seven settings, each with their callback functions. Remember, these are just placeholders. We'll complete these functions in the next video. For this video everything is complete. Before closing, let's organize our settings code.
To do so, we want to create two new files. One for the register settings function and one for the callback functions. Now in the register settings file we want to put all of our register settings code.
And remember to save changes. And likewise, in the settings-callbacks file we want to put all of our callback functions. And to both new files we add the no direct access snippet, which we can get from the main plugin file.
So we add the code to the top of each of these files here. Remember to save changes. Again, this code prevents the file from being accessed directly, as explained in the previous video on creating the plugin directory. And last, but not least, we need to include our two new files in the main plugin file. So we duplicate this line twice, like so, and then change the file names to settings-register.php and settings-callbacks.php.
So now our two new files are included in the plugin. Settings-register and settings-callbacks. Then one more quick visit to the plugin Settings page and everything is working great. In this video we learned about the Settings API, made a plan, and added our plugin settings. The steps outlined in this tutorial can be applied to any plugin and the code serves as a template that you can use when building your own plugins.
In the next video we complete the settings by defining their respective callback functions.
- WordPress APIs
- Action and filter hooks
- Activating and deactivating plugins
- Plugin security
- Creating the directory and files
- Adding menus and the settings page
- Inserting custom functionality
- Testing and debugging WordPress plugins
- Creating widgets
- Managing users and roles
- Adding custom post types and taxonomies
- Working with custom fields and database queries
- Using APIs: Transients, HTTP, and REST