Part of that process included replacing hard-coded data with options that future plugin users could configure. I haven’t built a new WordPress plugin from the ground up in a long time, but I recently decided to turn some code that was only useful to me into a fully functional plugin that I could distribute.
I needed to make a settings page for the plugin, and I was curious about the most up-to-date approach in the ever-changing WordPress world. Let’s look at a few different approaches to adding a settings page to your WordPress plugin.
- API for WordPress Settings
- A Framework for Custom Fields
- Making Use of a Code Generator
- Making use of the REST API
- VueJS (VueJS for short) is a
- React to the situation
API for WordPress Settings
WordPress 2.7 introduced the WordPress Settings API, which allows developers to register settings fields on existing settings forms in the dashboard, as well as create new settings forms that WordPress will display and save data for:
It allows you to create settings pages, sections within those pages, and sections within those sections, as well as fields within those sections.
This is the most manual of the methods discussed in this post, but it’s worth learning how it works because it’s a simple enough approach that it may be all that’s required in some cases.
To begin, we must create a new menu item and page to house our settings form. In the WordPress dashboard, add the page to the ‘Settings’ top-level menu item:
To communicate with the Settings API, that function must have a form element and some function calls: The fifth argument to add_options_page is the name of the function that will be used to display the page’s contents, in this case the settings form.
The name of the settings group that will be registered later is passed as an argument to the function. The settings_fields function generates code to instruct the form on what to do, as well as a hidden input to secure it with a nonce.
When registering fields, we’ll use that. The function do_settings_sections is the most important part of the form because it outputs all of the sections and fields (textboxes, selects, checkboxes, and so on) for the user to fill out. That function argument is again arbitrary, but it must be unique.
Let’s get started:
There are three things going on in this scene. To begin, we’ll use register_setting to create a new record in the wp_options table for our settings, with the option_name dbi_example_plugin_options.
This is useful for centralizing all of our plugin settings, but serialization of data can cause problems when migrating the WordPress database if not done correctly. The name of the function that validates data entered when saving the option is the third argument. Each of our preferences will be saved as a serialized array of data.
Ensure that the API key is a 32-character string that only contains numbers and letters, for example:
Second, we’re adding a group section to the settings, which is linked to the option. Finally, we use add_settings_field to register three fields for the group. All of these are text fields that will be used to store the settings for our plugin.
Next, we’ll need to write functions to render the fields on the form and display helpful text for the section:
Oh, my goodness! That’s all there is to it; we now have a settings page:
Using the settings in our code is as simple as calling get_option(‘dbi_example_plugin_options’) and selecting the appropriate setting from the array.
It’s not the most straightforward of the WordPress APIs to use or explain. It’s no surprise, then, that there are a number of wrapper libraries available that aim to make the process of adding a settings page to your WordPress plugin as simple as possible. There are a lot of moving parts here, such as registering this and that, duplicating code, and making sure everything is in order.
When I first created my Instagram WordPress plugin in 2012, I used Gilbert Pellegrom’s WordPress Settings Framework to create the settings page; this was before we worked together or even knew each other. James Kemp, a Delicious Brains friend, now maintains the framework; the WordPress community can truly be a small world. 😄😄😄
A Framework for Custom Fields
In the spirit of PHP frameworks, I’d like to demonstrate an alternative method for creating a settings page that does not rely on the WordPress Settings API. If I need a settings page when building a site for a client, I will use Advanced Custom Fields to create an options page and then define the fields using ACF.
It’s one of the many reasons I enjoy using ACF: it simplifies a complicated WordPress feature. (Have you heard of ACF Blocks, a PHP wrapper for registering blocks for the new Block Editor without having to touch React?)
This is where the Carbon Fields framework comes in. Carbon Fields, unlike ACF, isn’t a plugin; instead, it’s installed as a library within a plugin, and they recommend using Composer. When creating a plugin or theme for distribution, however, you can’t assume that the user has ACF installed.
After installing the Carbon Fields library, make sure you require the Composer autoload.php file if you haven’t already:
It’s as simple as using the following code to replicate what we did above with the WordPress Settings API:
As you can see, the framework makes it very simple to make the fields more user-friendly, such as adding a default, minimum, and maximum to the ‘Results Limit’ field and turning the ‘Start Date’ field into a date picker, which would have required a lot of coding with the Settings API.
You must use the carbon_get_theme_option() function to access a setting’s saved data:
Frameworks may be overkill for small projects, but they are a great way to accomplish a lot with less code, allowing you to focus on writing plugin code rather than reinventing the wheel by creating another settings page.
Making Use of a Code Generator
Another approach that makes use of the WordPress Settings API and the convenience of a framework is to use one of the many WordPress generators available:
- http://wpsettingsapi.jeroensormani.com/ WP Settings API – http://wpsettingsapi.jeroensormani.com/
- Option Page Generator for WordPress www.jeremyhixon.com/tool/wordpress-option-page-generator
- https://generatewp.com/settings-page/ GenerateWP (premium)
There are only a few field types supported: text, textarea, select, radio, checkbox, and no date picker. Let’s use the WordPress Option Page Generator to recreate our settings page.
Here’s the generated code, which I can paste into my plugin and use the data similarly to the WordPress Settings API.
However, for a plugin that requires a lot of changes to the settings code, they might not be the best option in the long run. They’re also useful for learning how things work, dissecting existing code, and figuring out how everything fits together. Generators are a great way to get started with your plugin by providing a ready-made settings page that can be tweaked without requiring a lot of coding.
Making use of the REST API
Improving your plugin or theme settings screens is one of the many great uses for the WordPress REST API.
I won’t use this technique to recreate my settings page because the article is a very thorough tutorial. Josh Pollock delves into how to create a settings page with the REST API and jQuery in this excellent article.
The REST API can outperform traditional admin-ajax.php requests in terms of performance, and when combined with the improved user experience of clicking ‘Save’ and the form settings being saved in the background without a page refresh, this approach feels far more modern than the WordPress Settings API.
As your form grows in complexity, Josh points out that “you’ll be doing more and more with jQuery that is a pain to manage and would be simpler, and provide a better user experience if you used VueJS or React,” which leads me to the next approach, a VueJS-powered settings page.
VueJS (VueJS) is a programming language that allows you to
wp-optionskit: wp-optionskit: wp-optionskit: wp-optionskit: wp-optionskit: wp-optionskit: wp-optionskit: wp-optionskit: wp-optionskit: wp-optionskit: wp-optionskit: wp-optionskit: wp-optionskit: wp-optionskit:
The settings page can be instantiated and configured using the code found here, and the package can be installed with Composer. The following is an example of a settings page:
This method appeals to me because it allows you to create complex settings pages with multiple tabs and subsections simply by configuring PHP arrays of data. The settings data is stored in one record in the options table, similar to some of the other approaches, so retrieving and using the saved data is simple.
VueJS, hold on a second. Isn’t WordPress fully committed to React?
A Few Words About React
Despite the fact that the WordPress community is rapidly adopting React for editing content in the WordPress admin (WooCommerce is even rebuilding their admin in React), I have yet to come across any React-based frameworks for creating plugin settings pages, aside from a few tutorials. However, as we saw with wp-optionskit, using the REST API allows for extensive use of VueJS or React in the WordPress admin.
Did you know that WP Migrate DB Pro’s entire UI is being rewritten in React? (If you enable beta updates in the plugin, the 2.0 beta is available.) We improve performance and user experience while also making the code more manageable for future development.
There are many ways to accomplish the same thing in development, and the approach you choose for one project may differ from the approach you choose for another. Wp-optionskit is my current favorite because it allows for multiple settings tabs and subsections, as well as a better user experience when saving.
Please let us know in the comments section. What method do you employ when it comes to creating WordPress settings pages for your plugins? Have I overlooked any popular choices?
This entry was posted in WP Migrate DB Pro, Plugin Development, React, Vue.js, REST API, WP Migrate DB Pro, WP Migrate DB Pro, WP Migrate DB Pro, WP Migrate DB Pro, WP Migrate DB Pro, WP Migrate DB Pro
Iain works in the south of England as a product manager. He helps people buy and sell WordPress businesses and publishes a monthly WordPress newsletter. He also manages a number of WordPress products.
I’ve been using a setings api class, which has proven to be very useful. WP-OOP-Settings-API (https://github.com/ahmadawais/WP-OOP-Settings-API) (https://github.com/ahmadawais/WP
Thank you very much! Do you know how to sanctify a field (say, text)? That is the class in which I am enrolled.
This is another one that I use.
Millions of users rely on it, and it includes some of the most popular themes ever created. Redux Framework (https://redux.io) is another option.
Thank you for letting me know about this. That’s incredible! Dovy is a character in the film Dovy
The framework appears to be attractive, but it appears to display very annoying administrative notices.
Otherwise, there are no notices. Only if you’re in dev-mode or on a local network.
Great job on the article! Not only do I like the visual consistency with WordPress, but I’m also reusing the same text fields, radio buttons, accordions, and other elements that Core uses in Gutenberg. The settings data is then passed back to the server via the REST API. I decided to go all-in on the new Gutenberg styles, using the open-source React components available at https://developer.wordpress.org/block-editor/components/. So far, it’s been great. I’m refactoring the settings page for my plugin WP Shopify http://wpshop.io at the moment. As a result, the functionality has been completely reused, which makes me happy as a developer.
I’d like to learn more about that process. Thank you so much, Andrew!
https://wpshop.io/blog/wp-shopify-3-0-progress-update-2-admin-settings/ http://wpshop.io/blog/wp-shopify-3-0-progress-update-2-admin-settings/ You’ve got it!
Admin Options Pages is another option.
Thanks, but not so good if you want to distribute your own plugin – not great if you rely on another plugin to work.
It’s useful in situations where you want to intentionally expose these controls to the user, such as when using TGMPA to make the plugin a requirement. But it is, without a doubt, a very specific use case.
Another option is the MB Settings Page, which includes network settings and customizer panels/sections.
Do you know about https://www.wp-hasty.com/ for code generators? Although it is a relatively new code generation website, I prefer it to generatewp.
I’m trying to make a checkbox options page with WordPress Option Page Generator, but the variables under "Retrieve this value with:" don’t seem to be returning anything…
I’ve tried numerous guides and still can’t figure it out. I’m trying to make a checkbox options page with WordPress Option Page Generator, but when I try to connect the variables under "Retrieve this value with:" to functions in the plugin, they’re null.
The vue.js option, like the documentation at https://github.com/WPUserManager/wp-optionskit, is poorly written. One of the five options has a great post.
Thank you for recommending Carbon Fields!
The error is caused by the line echo “”; Option 1’s code appears to be a little wonky. Fatal blunder: It’s a pity, because I’m sure it’d be fantastic otherwise. Syntax error, unexpected ” (T_ENCAPSED_AND_WHITESPACE), expected ‘-‘ or identifier (T_STRING), variable (T_VARIABLE), or number (T_NUM_STRING).
Thank you for the heads up; everything is now fixed. ,,,,,,,,,,
VERY HELPFUL FOR ME Thank you so much! This is an excellent article!
Please test before posting because there are several cut-and-paste errors in the code.
Thanks for letting us know; we’ve fixed the two code snippets that were causing issues.