WP Options Pages & Options
Well, it’s that time again to talk about a hard lesson learned. When it comes to wordpress Options pages, there is a lot to learn. It provides a bit of getting used to, in order to understand all the hooks, actions, enqueues, NONCE configuration, scripts, CSS, and permissions. Not to mention the options themselves – naming convention, sections, ID’s, values, and options meta storage. There are tons of “options pages libraries” out there that help with this process, some good, some great, and some – well that leave a bit to be desired.
So why talk about Options Pages then? is it really that simple? I mean – just go get a library and away you go right? wrong…. While using a library can accelerate your development, they don’t always provide the best documentation. Then, just when you think you’ve got something working – the library provider updates – and sometimes BREAKS your options page, or adds new functions and features that are incompatible with the backwards version you are using…. requiring (drum roll please) refactoring of all your options code. Now who has time for that??? not me.
Anyhow I’m rambling. I use ChatGPT to generate my options page code. It too has it’s quirks and issues. At the end of the day, if you “touch something” like (lets say the name / string used as an ID for a single option), it can cause hours of heartache. I know!! I experienced it!!! So, here’s today’s short but hopefully meaningful lesson:
IF YOU EXPECT YOUR OPTION SETTINGS TO WORK
(i mean just work out of the box), then…
1. set all your PAGE references to EXACTLY the same slug as the options page slug in the menu bar!!!
2. match the menu slug / page slug to your settings_fields call exactly.
3. match the menu slug / page slug to your do_settings_sections call exactly
4. match your menu slug / page slug to register_setting(<page slug>,<page slug>… ) exactly!
this is CRITICAL to do, or reset_option and the SAVE/SUBMIT process will simply refuse to write the options to the options meta table in the database!! If you do not match your page-slug / menu slug you will spend hours running debug and wondering why you don’t see the options SAVING to the database.
This cost me more than 6 hours today in heavy frustration, turning on PHP debug on a staging site, and not seeing any errors. Finally, aligning all the names (after reading lots of support articles and posts), I got it working. Now, there is something to be said – your “options” in the database can be called something slightly different than the page-slug. That part is not a rigid requirement, but beware… it *could* cause you heartburn. My suggestion is: KISS it, keep it all the same and be good to go.
One more tidbit: When naming your options in the database, PLEASE add a namespace for your plugin (a prefix string). This will avoid overwriting and conflicting with other plugins around the world. DON’T simply use a short identifier like “my_options”, this is simply bad practice. All of our options will be prefixed with a part of our company name: “aplus_<options>” for example.