In response to a previous article which covers custom WordPress plugin structure, How to Write a WordPress Plugin, a reader asked me the following question.
What are the advantages of using this approach then using add_settings_field() and add_settings_section()?
My previous article covers one method of adding a settings page to a plugin. In this article, I’m going to elaborate on WordPress’s settings framework.
Create a settings.php File and Define Your Settings Class
Class based plugins are easier to understand and maintain. In my previous tutorial I separated the custom post types into their own classes and files. In this example, I’m going to do the same for the plugin’s settings. Create a settings.php file in your main plugin directory and add the following.
In your main plugin’s php file, add the following lines to the constructor.
is an identifier for grouping options. To keep things organized and simple I generally use the theme/plugin slug that the settings are used to manage. In the case of a plugin named “WP Plugin Template” I used an $option_group of “wp_plugin_template-group”. The “-group” part of the identifier comes in handy when your plugin/theme/etc is more complicated and requires different groups of settings. As a general rule of thumb, if I want the settings fields to be separated into seperate form fieldsets I use seperate “-group” ids. ie: “wp_plugin_template-group_a” and “wp_plugin_template-group_b”
$option_name (string, required)
is the name of the option I want to save. I don’t get too fancy with these, use general variable naming convention. The option name should indicate what kind of value is stored in it.
$sanitize_callback (string, optional)
a callback function for validation and sanitation. You can put any validation you want in this callback function, BUT the function must return a value of some kind. So if for the supplied value doesn’t pass your validation rules, return an empty string return '';.
Where do you want the user to manage these settings?
Your first real choice is the page that you want your admins to manage these settings. You can use an existing page such as “media” or “general” OR create a new page. In my plugin tutorial, I choose the latter and create a new settings type page.
At this point if you are using a custom page to display your settings you could conceivably just echo html from your plugin_settings_page function and everything would be awesome. Except, you would have mixed template/HTML logic in with your application/plugin logic. Instead, lets include a template from our templates directory w/i the callback. That way the template logic is separate.
Now you need a templates/settings.php file in order to render the content from plugin_settings_page. If you are NOT using add_settings_section and add_settings_field then you can simply add your desired HTML in this file like so.
With this you have a working settings page from the menu sup page you created. But what if you wanted to not write any form field HTML? What if you wanted to add your settings to an existing menu page? The next couple sections go over using add_settings_section and add_settings_field and the benefits/disadvantages of doing so.
If you decided to not create a sub menu page for your settings and use and existing page such as general or media, then you do not need a templates/settings.php template. Instead the page will automatically render your settings section at the bottom of the page after all of the existing sections.