I’ve recently come across repeated discussions (especially on the wp-hackers mailing list) debating where plugin authors should place their custom admin pages. I discussed that question directly in my previous post, and basically stated that the plugin’s admin page can go any number of places, depending on what the plugin does. Some people disagree with this argument, saying that all plugin admin screens should go under one menu — usually “Settings” or “Plugins”, depending on whom you ask.

While I disagree, they do raise one good point: many end users will have trouble finding your admin page because they have come to expect such pages to all be dumped under Settings. Many plugin authors solve this by hard coding a link into the plugin Description, but this really isn’t the right place for that, and it can create inappropriate clutter in certain situations1. There is a better way.

WordPress 2.5 makes it fairly easy for plugin authors to add “action” links to the Plugin Management screen, like so:

We can do this in two steps: Add a short function to add the link, and attach that function to the appropriate WordPress filter. I will use my Pull-Quotes plugin for the example.

First, let’s add the attachment. We’re going to create a function called “filter_plugin_actions” and attach it to the existing “plugin_action_hooks” hook. To my mind, it makes sense to do this right after we’ve added the plugin page itself. Thus we might end up with something like this:

Pretty straightforward for the most part. Note that I wrapped it all in a current_user_can() check so that both the page and the link only appear to users who can use them. If you’re wondering why function names are wrapped in the array(&$this ______), it’s because I wrap all of my plugin functions in a PHP class to avoid function name conflicts with other plugins. (It also makes code much more reuseable). If you don’t choose to do that, you can get rid of a little baggage and do something like add_filter( 'plugin_action_links', 'myplugin_filter_plugin_actions', 10, 2 );

First off, this filter is going to be called for every single plugin row on the Plugins page, but we only want it to add a link for our plugin. So we make a variable $this_plugin that holds the name of the plugin file that we’re in right now, and we make the variable static so that plugin_basename() only has to be called once. Then, we start an if() block to contain the actual filter code — that is, we only add the link if we’re on the row for this plugin. Next:

That’s extremely straightforward: we assign the link HTML to a variable. The final step is to add the link to the $links[] array. (For most purposes, I recommend putting the new link before existing links.) Choose ONE of the following, but not both:

Finally we close up our if() and return $links back to the main program flow:

}
return $links;
}

Update: Please, please, please don’t get cute with the text of the link. Name it “Settings”, or “Manage”, or something that is fairly standard to the existing WordPress interface. Oh, and it’s helpful to international users if you wrap it in the __() function, like so:

I totally agree that this “Settings” link can be very, very useful. But also I’m quite afraid of that inconsistency that could happen, if plugin developers would not use the filter as you recommend. Hopefully will this get own filter.

I personally like the idea of adding something to core so that when a person adds an admin menu page, it has a parameter to automatically add a link to the Manage Plugins page as well. Then it would be really consistent.

I’ve already seen another author (*cough*) use this on a plugin of his own, and he put the Settings link _after_ Deactivate. (Alphabetical maybe?) Is he wrong? No, but it is different. So, you’re right. I can show people how to do the link, but personal preferences will range far and wide and it will be inconsistent. Training plugin authors is like herding cats. 😉

Part of why I’m writing these articles is to educate authors on what I consider “elegant” coding practices, as well as various “best practices” such as the upcoming article on using arrays for saving options. A lot of plugin authors put the settings links in the plugin description, so even if link order or name is a bit idiosyncratic, using action links at all is still a step up. So… even if applied inconsistently, these tips will still be an improvement.