If you’re the type of person who learns best by seeing code in action, you should look at my sample plugin on GitHub.
Call me strange, but I’ve never been a huge fan of the WordPress Settings API. The sheer fact that a diagram like this might be necessary to explain it is indicative to me that it’s too complicated!
After fighting with conventional approaches, I decided to write my own framework as a Settings API alternative.
Here are the requirements I started with for my settings API:
- Similar syntax to the WordPress Options API (add_option, get_option, update_option, etc)
- Single settings object for direct access (when required)
- Automatic handling of arrays, using delimited strings for user facing fields
- Automatic HTML field naming and saving
Basically, the API should be as easy to use as the options API and automate the annoying, inefficient tasks developers face when they are building options pages.
Additionally, the data should be stored in a single WordPress option for three main reasons:
- Allows for programmatic direct access to a single, local settings object. (if you even need it)
- Doesn’t pollute the options table with lots of new options.
- Gives you the freedom to name your options however you like, without worrying about collisions with other plugins.
I developed my initial approach while rewriting Simple LDAP Login. After showing my approach to a few other devs, I decided to spend some time refining it to be a formal, reusable framework for future plugins.
I’ve named the framework WordPress Simple Settings and released it under the GPL on GitHub (fork away!).
I designed it to be as minimalist as possible. You should be able to implement it in minutes, and I’ve included a sample plugin to demonstrate exactly how it works! Woo hoo!
[repo name=”wordpress-simple-settings” author=”clifgriffin”]
What Is It Exactly?
WordPress Simple Settings is an abstract class which you use as your base class in your own plugins, themes, etc.
You set a unique prefix in your implementation, and the framework builds a settings object which is stored in a single option in the database. (Using the WordPress Options API)
The framework gives you getters, setters, and handles HTML field naming and data saving…all automatically, and with as little involvement from you as possible!
To demonstrate the brevity, this is the entire class:
Here are the basic functions available to you.
This is essentially a wrapper for
update_setting that respectfully does not make any changes if the option in question is already set.
You’ll most frequently use this in your activation hook.
Retrieves a specific option. Returns string by default. If you specify
$type, it will treat the value as a semi-colon delimited string and return an array.
Updates a specific option.
Gets an HTML field name. If you set
$type to array, the field value will be treated as a semi-colon delimited string and stored as an array.
$YourPluginInstance->the_nonce() somewhere in your admin form to generate the nonce used to validate / save settings.
There is no need to call this unless you want to override the default functionality. This function will be called on
admin_init and automagically saves settings, if the right nonce and
$_REQUEST is set.
One of my goals in building this framework was to have an easily accessible settings object that can be used directly when the getters / setters are inconvenient. This is done by simply using
Obviously this should be used in read-only applications. Setting values here will not update them in the database.
Please let me know if you successfully use it in your project, and if you have any ideas for improvements!
I’m with you in that the WordPress Settings API is complicated – there’s no real way around it. In my opinion, it’s probably one of the most (if not *the* most) unintuitive APIs in WordPress right now.
Your framework definitely provides a cleaner interface for it. I dig that and this is something that I could see being used in client projects where you have full control over the development, upgrade, and maintenance process.
The one thing about writing a framework or library that sits between developers and one of the WordPress APIs is the cost of maintenance.
That is, you’re inserting a dependency in between plugins, themes, or applications and WordPress that will need to be maintained and grown as WordPress continues to grow and change. This isn’t necessarily a negative – as with anything that is created has to be maintained in someway – but when you’re dealing with settings, you don’t want it to bork whenever a user upgrades WordPress after the API has changed.
Other than that, I think open sourcing this thing, sharing it, and making the interface as clean as possible is good stuff. Happy to share this with others :).
Thanks vote of confidence, Tom. 🙂
I get what you’re saying about the potential dangers of maintaining an interface that puts you in between plugin authors and WordPress, but since the Options API is the real underlying interface, and it’s been around since WP 1.5, it feels pretty safe.
Maintainability is a great argument for breaking out future expansions into other classes which implement this one. That way, the core functionality is protected from feature creep and devs don’t have to use more than they need.
This a nice idea. I liked using Pippin’s solution which he has used in EDD. https://github.com/easydigitaldownloads/Easy-Digital-Downloads/blob/master/includes/admin/settings/register-settings.php
There you can add additional theme options very easily.
There are definitely some nice option frameworks out there. This is the one I’m most familiar with: http://wptheming.com/options-framework-theme/
I’ve really only used them in the context of a theme, and now that I use Genesis for most projects, that is taken care of.
I see this as a good fit for smaller projects with only a handful of options. It eases form processing and option storage, but leaves everything else in your control.
I found that Devin’s framework is just a bit too big for just a smaller projects. Pippin’s solution is quite simple. I used it for this plugin here. https://github.com/flowplayer/wordpress-flowplayer/blob/master/includes/register-settings.php
Your project gives indeed a lot more styling possibilities. I think when starting a project you need to think of the pros and cons for each solution. I think your solution could be useful like you say for smaller projects.
Thank you for bringing a new solution to the community.