How to build WordPress Settings API as Framework

WordPress Settings API is a robust API but it’s not a framework to easily create fields within your WordPress admin area. Let’s build a simple framework utilizing the Settings API.

We’ll create an abstract class that will hold all the basic functionality we need for creating Settings Pages.

Several years ago, I’ve written a similar tutorial on How to create WordPress Menu Pages with OOP. This one is not so focused on the whole OOP approach and it’s heavily dependant on the Settings API. The article from before, has it’s own way of saving data and displaying the fields.

Settings API Framework Abstract Class

You can save this file inside of your plugin or theme to try it out. I like to put my abstract classes inside of an abstract folder. You can name the file as you want, I’ll call it class-settings.php.

Let’s go over the code we have here:

• $id – This is not a DB id. It’s a string ID that will prefix our options and such. It’ll also be used as the menu/submenu slug.
• $page_title – This is the Page Title that will show on the browser tab when viewing the page
• $menu_title – This is the text that will display on the Menu in the admin
• $parent_menu – The menu slug under which we want this menu to be
• $fields – This will hold the configuration of our fields for that specific Settings Page

Then, inside the constructor method, we use action hooks where we’ll register the menus and also the settings.

Registering the Settings Pages

Inside this method, we’re registering the menu or submenu. Our menu & submenu pages will have the slug formed by the $id of the class and the suffix _settings_page: this->id . '_settings_page'.

Displaying the Page

Now, let’s display the page.

We have a simple HTML page with a form that will send the request to options.php. From there, WordPress will know where to save it and how. That’s with the help of the method settings_fields.

Then, with the method do_settings_sections we display sections and fields that are registered to our settings page.

We also have a few custom actions here in case you want to display data other than fields on the settings page.

Registering Fields with the WordPress Settings Framework

Before we register the fields, let’s create some helper methods.

• get_settings_id – This method is not too useful in this class since we can easily get the $id, but if you’re passing the object to other classes or functions, we can retrieve the ID if needed,
• add_field – same as above, not used here. But if you have some classes that might need to add other fields to it, that’s a method that can be used,
• get_fields – This is the method that we’ll use to get fields. Since it also has a filter applied, other plugins or such could hook into it and add fields (or remove some).

This is the important part. We are registering the fields that will be used on our settings page.

We’re registering a single option here and all fields are saved under that one option.

Then, all the fields are registered as setting fields. Sections are registered to the page. Fields are registered to the both page and section.

Sanitizing Options in the WordPress Settings Framework

Since we have also registered a sanitizing method, this will run before saving the data inside of our database.

For the sake of this tutorial, we’ll keep it short. We’ll focus only on text fields.

We get all the fields and go over them. If it’s a section, we’ll skip it since it’s not something that will get saved.

The $input variable holds the data that is posted, that’s trying to be saved.

Then, we go over the field type and define how we’ll sanitize the data.

We also have an action that will trigger once all data is saved. This can be useful for different type of data and such.

Helper Methods for Rendering Fields

Let’s now build a few helper methods that will help us when rendering fields.

• get_option_key – This method will help us when building the field for the name attribute. We can easily provide the field ID/name and this method will return the whole value for the name attribute that we need for saving the data,
• get_option – This method is used for getting the value we need for the field we’re displaying. We get the whole data that was saved before. If our field was saved, it will return the data even if an empty string. If not, it will return the default one we provide,
• render_section – This method is used for rendering all sections,
• render_field – This method is used for rendering all fields. We call a method formed from the field type.

Rendering Text Field in the WordPress Settings Framework

We’ll define the method render_text. This method will be called for a field with the type text.

Rendering Checkbox Field in the WordPress Settings Framework

Page Example with the WordPress Settings Framework

Let’s now see a simple example of a page that will show 1 section and 1 text field.

And let’s say that we want to include both the abstract class and this class. How to include them and show the page?

Just by instantiating the Page class, we’ll be able to see the Page and its settings.

Conclusion

Well, now, with this little class, we can extend it further by adding other different types such as select, radio and such types.

Become a Sponsor