WP-Fun.co.uk

Fire and Forget

How many plugins do you use that have a small number of config settings that you almost never need to go back to? These plugins might help prevent spam, add a widget, or shortcode; they have settings but, crucially, don't need tweaking or changing very often, if at all. What a waste it is for these plugins to create new admin pages just for that. Well here’s an alternative.

Take a look at this entry from my plugin page:

This entry has an extra action: configure. Selecting configure opens panel beneath the entry containing the basic configuration options letting you change the settings from the plugin page itself, and without requiring the addition of another admin page.

How it is done

You can download this sample plugin at the end of this post, but here is an explanation of how you achieve this in your own plugin.

There are four parts to this technique:

  1. Insert the form
  2. Insert the configure link and open the form
  3. Handle the form feedack.

I'll explain these in turn.

Insert the form

When the table loads that lists all the plugins an action (after_plugin_row) is triggered imediately after each row. This action passes three values: the filepath of the plugin, the basic details of the plugin, and the state of the plugin, so whether it is active, inactive, or recently active.

Adding the form means checking against these to ensure that the form is inserted at the right point and outputing the form itself:

[php]
add_action("after_plugin_row", array(&$this,"add_config_form"), 10, 3);

function add_config_form($pluginfile, $plugindata, $context){
if ( $plugindata['Name'] == 'Plugin Config Sample' && $context == 'active' ) {
?>

Plugin Config Sample Configuration



}
}

It is important to note that the plugin page is effectively one big form. This means that you can't use an actual form to make the update, which is why there are no form tags in the function above. You will need to Ajax to get the data and submit it.

The plugin also adds some CSS so that the form is hidden by default which means we need javascript to make it visible.

Using jQuery it is very easy to work back and insert the configure link, the javascript is included in the sample plugin below so I won't spit it out right here.

The final part is using Ajax to actually update the plugin.

Jquery includes some really easy functions for using ajax so the following is all I have used:

[js]
$('#pcsc_config_submit').click(function(){ pcsc_config_update()});

function pcsc_config_update(){

//get the important value
API_Val = $('#pcsc_config-API').val();

//set the url
url = '/wp-admin/admin-ajax.php';

//add the action and the actual value
$.post(url , { "action" : "pcsc_config-update" , "pcsc_config-API" : API_Val }, function(d){
if ( d == 'updated' ) {
//show the updated message
$('#pcsc_message').show();
}
});
}

The important point to note here is the URL and the action value. By sending the request to admin-ajax.php and including an action name (pcsc_config-update) you can use a hook to handle request.

The following code in the plugin handles the request:

[php]
add_action("wp_ajax_pcsc_config-update", array(&$this,"save_config"));

function save_config(){
if ( !update_option('pcsc_config-API' , $_POST['pcsc_config-API'])){
add_option('pcsc_config-API' , $_POST['pcsc_config-API']);
};

die('updated');

}

Note the hook that calls the save_config function is 'wp_ajax_' + the action specified in the ajax call. The function updates the option and then dies and echos 'updated'. Looking back at the javascript, it tests for the value updated in the return data and makes the success message visible if it is there.

Obviously a real world scenario would include validation, error handling, and nonces.

You can download the example plugin here, it is very basic, just enough to demonstrate the technique, but hopefully you will consider this method next time you make a plugin that doesn't require much configuration. This will help to make WordPress a little less cluttered for everyone.

The 2.7 version of my Fun with Plugins, plugin generator, will include this has an option.

Update:I've just been pointed toward a filter that I overlooked (odd as I looked for something that did this specifically) which means extra actions can be added to the action list without the use of Javascript which is excellent news. Details of the filter: plugin_action_links can be found at Nerdaphernalia.

Because of this I have updated the plugin to include an alternative options as well. Option 1 is the javascript link, the second option will link to the settings page, but doesn't add an admin menu, so there is still only one link to it.