soo_plugin_pref Page 1 of 4

soo_plugin_pref

Summary:

Plugin preference management

Download

soo_plugin_pref version 0.2.2 (3.2 KB)

Preview soo_plugin_pref code

You can also download a sample plugin to see how the preference management works.

Overview

This is an admin-side plugin for managing plugin preferences.

For users, it provides a consistent admin interface to set preferences for soo_plugin_pref-compatible plugins, and automatically installs or removes those preferences from the database as appropriate. Of course, when you upgrade a plugin your existing preference values are retained.

For plugin authors, it allows you to add preference settings to your plugins without having to create the user interface or the preference-handling functions.

It uses the plugin prefs/lifecycle features introduced in Txp 4.2.0, so Txp 4.2.0 or greater is required.

Usage

soo_plugin_pref only works with plugins that are designed to use it. (See support forum thread for a list of compatible plugins.) As of version 0.2.1, you can install plugins in any order. A compatible plugin’s preferences will be installed the first time you activate it or click its Options link in the plugin list while soo_plugin_pref is active. Its preferences will be removed from the database when you delete it while soo_plugin_pref is active.

To set a plugin’s preferences, click its Options link in the plugin list.

Info for plugin authors

If you are not a plugin author, you can safely ignore the rest of this help text.

Configuration

To configure a plugin to work with soo_plugin_pref:

If this is a public-side plugin, set the type so that it will also load on the admin side:

$plugin['type'] = 1;

Set the plugin flags at the top of the plugin template (using the http://textpattern.googlecode.com/svn/development/4.x-plugin-template/ template all you need to do is uncomment the $plugin['flags'] line):

if (!defined('PLUGIN_HAS_PREFS')) define('PLUGIN_HAS_PREFS', 0x0001);
if (!defined('PLUGIN_LIFECYCLE_NOTIFY')) define('PLUGIN_LIFECYCLE_NOTIFY', 0x0002);
$plugin['flags'] = PLUGIN_HAS_PREFS | PLUGIN_LIFECYCLE_NOTIFY;

Then somewhere in the plugin code section (substituting your plugin’s name for abc_my_plugin, and whatever name you choose for the callback function):

require_plugin('soo_plugin_pref');
add_privs('plugin_prefs.abc_my_plugin','1,2');
add_privs('plugin_lifecycle.abc_my_plugin','1,2');
register_callback('abc_my_plugin_prefs', 'plugin_prefs.abc_my_plugin');
register_callback('abc_my_plugin_prefs', 'plugin_lifecycle.abc_my_plugin');

and finally, define your plugin’s preferences and route the plugin_prefs and plugin_lifecycle events to soo_plugin_pref() in your callback function. Here’s an example:

function abc_my_plugin_prefs( $event, $step ) {
	$defaults = array(
		'foo' => array(
			'val'	=> 'foo',
			'html'	=> 'text_input',
			'text'	=> 'Helpful description',
		),
		'bar' => array(
			'val'	=> 1,
			'html'	=> 'yesnoradio',
			'text'	=> 'Equally helpful description',
		),
	);
	soo_plugin_pref($event, $step, $defaults);
}

For each preference, val is the default value, and html is the type of HTML input element used to display the preference in the admin interface; these go to the corresponding columns in txp_prefs. text is the label that will appear in the admin interface; it is not stored in the database.

Preference names in the database are in the format “plugin_name.key”, where “plugin_name” is your plugin’s name, and “key” is the array key from the $defaults array.

Each preference will be assigned a position value corresponding to its position in the defaults array, starting at 0. This determines its relative order in the admin interface.

Other txp_prefs columns are set as follows:

Alternative configuration if prefs are optional

If you wish to offer soo_plugin_pref preference management as an option rather than a requirement:

Set the plugin flags as above.

Prefix the error suppression operator (’@’) to the require_plugin() line, but otherwise set add_privs() and register_callback() as above.

Define your preference defaults in a separate function:

function abc_my_plugin_defaults( ) {
	return array(
		'foo' => array(
			'val'	=> 'foo',
			'html'	=> 'text_input',
			'text'	=> 'Helpful description',
		),
		'bar' => array(
			'val'	=> 1,
			'html'	=> 'yesnoradio',
			'text'	=> 'Equally helpful description',
		),
	);
}

Then add a conditional check to your callback function:

function abc_my_plugin_prefs( $event, $step ) {
	if ( function_exists('soo_plugin_pref') )
		soo_plugin_pref($event, $step, abc_my_plugin_defaults());
	else {
		// any custom preference handling goes here
	}
}

If nothing else, you should display a message for a plugin_prefs.abc_my_plugin event if soo_plugin_pref is not installed. The version below checks the event type, then attempts to cobble together a meaningful message using gTxt() fragments:

function abc_my_plugin_prefs( $event, $step ) {
	if ( function_exists('soo_plugin_pref') )
		return soo_plugin_pref($event, $step, abc_my_plugin_defaults());
	if ( substr($event, 0, 12) == 'plugin_prefs' ) {
		$plugin = substr($event, 13);
		$message = '<p><br /><strong>' . gTxt('edit') . " $plugin " .
			gTxt('edit_preferences') . ':</strong><br />' .
			gTxt('install_plugin') . ' <a
			href="http://ipsedixit.net/txp/92/soo_plugin_pref">soo_plugin_pref</a></p>';
		pagetop(gTxt('edit_preferences') . " &#8250; $plugin", $message);
	}
}

Functions

There’s also soo_plugin_pref_vals( $plugin ), a handy little function that returns your plugin’s preferences as an associative array. It strips the plugin name and ‘.’ from the name in the database, so that the array keys match those in your defaults array. My typical use of this, with the alternative (i.e., soo_plugin_pref optional) configuration shown above:

if ( function_exists('soo_plugin_pref_vals') )
	$abc_my_plugin = soo_plugin_pref_vals('abc_my_plugin');
else
	foreach ( abc_my_plugin_defaults() as $name => $val )
		$abc_my_plugin[$name] = $val;

where $abc_my_plugin is global.

Limitations

Version History

0.2.2 (9/28/2009)

Fixed bug in pref position re-indexing

0.2.1 (9/26/2009)

0.2 (9/17/2009)

This version uses a different identifying scheme for preferences and hence is not compatible with the previous version. The plugin name is no longer stored in the event column, so there is no longer any restriction on plugin name length.

0.1 (9/5/2009)

Basic plugin preference management: