Doug's Blog

Hacking WordPress Screen Options

**Warning, Nerd Alert. Code Samples Will Follow**

As a developer I notice things about the WordPress interface that a lot of people overlook. One feature that’s pretty awesome to have is the ability to show/hide different columns and meta boxes on various screens. Here’s some of those options on the “Add Post” screen:



A plugin that I was writing recently required a custom admin screen, and I found that there were a couple of rarely used things that I wanted to be able to control that it would be handy to add to this section of the admin interface. Unfortunately there is very little documentation on how to do anything with this part of WordPress. Pippin’s Plugins has a post on how you can add a simple numeric increment counter to the screen options for use in various places and I found this to be useful. Selection_001The counter can be found on pages within WordPress that list posts or custom post types etc.

I’ll leave his tutorial for you to follow if you wanted to add something like that to your plugin/screen. I found it useful as I was displaying several hundred items and I used this counter to control how many were displayed at one time. But I didn’t want to stop there. I wanted to add more options to that tab.

After reading a ton of code and sorting my way through it, I found that there are currently no hooks or filters that will allow you to add a custom element to the screen options tab. The only elements that can be displayed are metaboxes, columns, and a per_page counter. I just wanted a simple way to turn my option on/off so this works out great for me, as you’ll see below, I hacked these checkboxes to do my bidding. In the future I hope that this part of WordPress is extended to better allow customization of this area. Below are the technical details of how I added a per user on/off setting, and used it in my plugin.

Here’s the relevant code:

In the first bit of code, we grab the current screen and attach a filter to it. This filter then returns the option and a label for it. You could return an array of any number here and WordPress would render each one as a checkbox for that screen. In my production code, this is only fired off as my admin screen is loading.

The html part is what took me the longest to figure out. With regular usage of the metaboxes and columns checkboxes, the hiding/displaying is done in real time and the option is saved to the database for the user over AJAX. After many fruitless attempts to figure out where WordPress was saving the checkboxes I finally found that common.js processes them for us the moment that they’re checked/unchecked. Adding a hidden element won’t work because the code in common.js that looks like this: return $('.manage-column').filter(':hidden').map(function() { return; }).get().join(',');. The id of the hidden elements is what is actually saved to the database. So by adding a “fake” table column with the same id as the column that we’re using to fake this data, we can then use css to position our fake element off-screen and then WordPress will do all the AJAX saving for us automatically.

Finally, you will probably want to utilize the value of this variable at some point, the last bit of code is a function that handles this. If you want to also update your screen dynamically (for now my code is expecting the user to hit the apply button before I show the difference on screen) you will need to hook into the jQuery action, $('.hide-column-tog', '#adv-settings').click( function() { is what that looks like for how WordPress does it.

If you’re curious to see the code in action, I use it to show/hide the WordPress admin scripts in this plugin: