Adding Action and Meta Links to WordPress Plugins

As we inch closer to launching our first WordPress plugin, it’s time to share some of the things we learned while developing it. Developing WordPress plugins is quite different than developing themes and for me it was a huge step in becoming a better WordPress developer, mainly because of time spent dealing with actions and filters. Those two are part of Plugin API, even though most of it can be used in WordPress theme development as well.

In this post, we’ll take a look at how to add action and meta links to your WordPress plugin, allowing users easier access to your plugin’s settings page, FAQ page on your site, a contact page, well, anything that might be useful. These links will appear in plugins list shown in Plugins page of your WordPress dashboard.

Using {$prefix}plugin_action_links_{$plugin_file} hook to add action links to your plugin

WordPress plugin action links
WordPress plugin action links

By default WordPress displays following plugin action links:

  • Activate / Deactivate
  • Edit (if current user can delete plugins and plugin directory is writable)
  • Delete (if current user can delete plugins and plugin is deactivated)

A lot of WordPress plugins have their own settings page and there’s few WordPress related things more frustrating than activating a plugin and then having to go through all the menus so you can find its settings. Tools? Settings? Separate menu page with subpages, which subpage? You get the point.

Luckily adding a plugin action link is dead simple. All you need to do is hook into {$prefix}plugin_action_links_{$plugin_file} filter hook and mess with its output a little bit. This requires only a few lines of code, so code first, explanation second:

This snippet should be in your main plugin file (e.g. /plugins/your-plugin/your-plugin.php). Since {$prefix}plugin_action_links_{$plugin_file}can be split into pieces and contains variables, let’s break it down:

  • {$prefix} – Two options here, leave it empty if you’re adding links to “standard” Plugins page, or use 'network_admin_' if you want to add Plugin action links in Network Admin page.
  • plugin_action_links_ – Text string.
  • {$plugin_file} – Basename of your plugin. WordPress plugin_basename function is used to dynamically display basename of a file. The only argument, __FILE__ is a PHP “magic contant” which shows full path and filename of the file it’s called from. Then plugin_basename converts it to something that makes sense to WordPress.

Moving on to custom function we created and hooked into {$prefix}plugin_action_links_{$plugin_file}:

function ts_add_plugin_action_links( $links ) {
	return array_merge(
		array(
			'settings' => '<a href="' . get_bloginfo( 'wpurl' ) . '/wp-admin/tools.php?page=our_plugin_page">Settings</a>'
		),
		$links
	);
}

There’s one argument this function has, and it contains an array of plugin action links that are shown by default. In order to add something to this array, we must merge it with another key/value array that contains our custom links. In this example, it’s only one link, to plugin settings page, under Tools menu. If you’d like to show more than one link, just add them to the array. If you’d like to show custom action links after default ones, all you need to do is swap places of $links and custom array.

Using plugin_row_meta hook to add links to your plugin’s meta row

WordPress plugin meta row
WordPress plugin meta row

Information shown in your plugin’s meta row normally contains plugin version, your name and a link to your website, all being pulled from your plugin header. So, they’re not used to interact with your plugin directly, but usually do lead to additional information about your WordPress plugin. For example, you could create a free WordPress plugin and use plugin_row_metahook to show a “Buy Premium Version” link:

This is all very similar to how plugin action links are added, but there’s one key difference. When adding action links using {$prefix}plugin_action_links_{$plugin_file} it is possible able to pass plugin basename directly into the hook name, making it add custom action links only to our plugin. Since there are no variables in plugin_row_meta hook, we must find another way to show custom meta links only for our plugin. That’s where second argument of our custom function comes into play:

function ts_plugin_meta_links( $links, $file )

Note that in order to use second argument in our custom function, fourth argument ($accepted_args) in add_filter function had to be set to 2:

add_filter( 'plugin_row_meta', 'ts_plugin_meta_links', 10, 2 )

Now in ts_plugin_meta_links function it’s possible to use basename of plugin currently displayed, while looping through plugins list. We can then compare it to plugin_basename(__FILE__) (basename of file this code is in), and if it is the same file, add links to plugin row meta. Otherwise, WordPress will only display standard information.

And there it is. Dead simple, but quite often overlooked by WordPress plugin developers. Other than Settings and “Buy premium version” link, what other links do you think would help users? Our comment form doesn’t bite :)

Note: Prior to WordPress 3.1, plugin_action_links and plugin_action_links_{$plugin_file} were hooks you’d use to add plugin action links. Since 3.1 they’re both deprecated and shouldn’t be used. For more information about WordPress hooks, sprint to Adam Brown’s WordPress hook database.

3 thoughts on “Adding Action and Meta Links to WordPress Plugins”

  1. Awesome post. Just what I needed for a plugin I am writing. Thanks for the simple straight forward instructions. Basically cut and paste into my plugin object. I was looking for the action link hook but I ended up using the meta hook as well.

    Thanks again for the time to write this.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>