Epic Alex | WordPress Tutorials

Underused Plugin Function

There is often a lot of talk about where WordPress plugin settings pages should be placed in the admin panels, and once the plugin author has decided where to put it, the user then has to work out where to find it. Well in WordPress 2.7, a new filters was added to solve the problem.

What is a shame though, is that out of the 20 plugins that are currently activated on my blog, only 1 of them uses this new functionality. So lets look at what that new filter is.

Add Action to the Action Column

plugin_action_links_{$plugin}. This allows the plugin author to add another action for their plugin, along with the standard activate/deactivate and edit. The codex lists the following example for adding a link to your settings page, which solves our problem above.

$plugin = plugin_basename(__FILE__); 
 
function my_plugin_actlinks( $links ) { 
 // Add a link to this plugin's settings page
 $settings_link = '<a href="whatevertheurlis">Settings</a>'; 
 array_unshift( $links, $settings_link ); 
 return $links; 
}
 
add_filter("plugin_action_links_$plugin", 'my_plugin_actlinks' );

This will look like this:

A screenshot of a plugin using the code above

1. What this does is assign the plugin file name to a $plugin variable for later use.
2. We then start our function, remembering to add $links as a parameter since we are using a filter; this is also why that variable is returned at the end.
3. We then assign the link(s) we want to add to the variable $settings_link.
4. We could also make $settings_link an array to add more than one link, since it will be passed to array_unshift(), which prepends passed elements to the front of the array $links, which is defined by WordPress in plugins.php

This is obviously intended for a link to the plugin’s settings page, and therefore solves the age old problem of finding it. The user installs the plugin, goes to the plugins page, activates it, and straight away knows that he can click the link to find out where to go.

While this is know doubt the intended action, there are many other uses for this. How about adding a donate link, or if you have full uninstall functionality in your plugin (ie. removal of database records), maybe you could place a link here for that as well.

So, let’s hope that plugin authors everywhere take up the baton and make it easier for users to find their settings page.

WordPress 2.8

June 10th – I installed WordPress 2.8 today, and found that the link structure has changed. Yet another new filter is now used for this, but the principle is the same. I also saw via a tweet that WPEngineer had covered the topic today, and the code proposed there for this function is as follows:

Your code should now look like this:

function set_plugin_meta($links, $file) {
$plugin = plugin_basename(__FILE__);
// create link
if ($file == $plugin) {
return array_merge( $links, array( sprintf( '<a href="options-general.php?page=%s">%s</a>', $plugin, __('Settings') ) ));
}
return $links;
}
add_filter( 'plugin_row_meta', 'set_plugin_meta', 10, 2 );

Essentially all that has changed is the function, but the result is the same. So, if we have two different methods depending on WordPress version, how do we know which one to use? Simple; plugin_row_meta was only introduced in 2.8, so we can check for its existence, if it is there, run the 2.8 version. If the function does not exist, then run the old version.

If we want to be really careful, we can check for the existence of a function that was only introduced in 2.7, and if that isn’t there, then do nothing. We end up with the following:

function my_plugin_actlinks( $links ) {
global $file;
if(function_exists('plugin_row_meta')) {
$plugin = plugin_basename(__FILE__);
// create link for 2.8
if ($file == $plugin) {
return array_merge( $links, array( sprintf( '<a href="options-general.php?page=%s">%s</a>', $plugin, __('Settings') ) ));
}
return $links;
} elseif(function_exists('post_class')) {
// Add a link to this plugin's settings page for 2.7
$nue_settings_link = '<a href="whatevertheurlis">Settings</a>'; 
array_unshift( $links, $nue_settings_link ); 
return $links;
} else {}
}
if(function_exists('plugin_row_meta')) {
add_filter( 'plugin_row_meta', 'my_plugin_actlinks', 10, 2 );
}
if(function_exists('post_class')) {
add_filter('plugin_action_links_$plugin', 'my_plugin_actlinks' );	
} else {}

When this is used in WordPress 2.8, the link to the settings page is only there after the plugin is activated. You should now have something looking like this:

Are you a plugin author? Does your plugin have this functionality? Or are you a user tired of searching for that hidden page, what do you think of the idea? I’d love to hear your feedback in the comments below.