soo_plugin_pref

Summary:

Plugin preference management

Example plugin using soo_plugin_pref (this and the help text below courtesy soo_plugin_display)

 1 : require_plugin('soo_plugin_pref');
 2 : add_privs('plugin_prefs.soo_useless','1,2');
 3 : add_privs('plugin_lifecycle.soo_useless','1,2');
 4 : register_callback('soo_useless_prefs', 'plugin_prefs.soo_useless');
 5 : register_callback('soo_useless_prefs', 'plugin_lifecycle.soo_useless');
 6 : 
 7 : function soo_useless_prefs( $event, $step ) {
 8 :     soo_plugin_pref($event, $step, soo_useless_defaults());
 9 :     if ( substr($event, 0, 12) == 'plugin_prefs' ) {
10 :         $soo_useless_prefs = soo_plugin_pref_vals('soo_useless');
11 :         echo
12 :         n. startTable('useless') .
13 :         tr(n. td('This plugin is quite use' .
14 :             ( $soo_useless_prefs['status']['val'] ? 'ful.' : 'less.')
15 :         )) .
16 :         endTable();
17 :     }
18 : }
19 : 
20 : function soo_useless_defaults( ) {
21 :     return array(
22 :         'status'    =>  array(
23 :             'val'   =>  0,
24 :             'html'  =>  'yesnoradio',
25 :             'text'  =>  'Is this useful?',
26 :         ),
27 :     );
28 : }

soo_plugin_pref version 0.2.3, 3.7 KB
(If it won’t install try the compressed version)

Full plugin help text

soo_plugin_pref

This is a plugin for Textpattern.

Contents

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. (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.) 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.

NB: A limitation is that if you upgrade an already-enabled plugin, and the new version of the plugin includes new pref settings, you must disable and re-enable it to pick up the changes.

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:

In the plugin manifest (i.e., the $plugin array at the top of the file):

Add this to 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');    // optional
if ( @txpinterface == 'admin' )
{
    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');
}

Define your plugin’s preference defaults. I like to do this with a function, with the option to output the multi-level array required by soo_plugin_pref() or a simple key:value array:

function abc_my_plugin_defaults( $vals_only = false ) {
    $defaults = array(
        'foo' => array(
            'val'   => 'foo',
            'html'  => 'text_input',
            'text'  => 'Helpful description',
        ),
        'bar' => array(
            'val'   => 1,
            'html'  => 'yesnoradio',
            'text'  => 'Equally helpful description',
        ),
    );
    if ( $vals_only )
        foreach ( $defaults as $name => $arr )
            $defaults[$name] = $arr['val'];
    return $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:

Add the prefs callback:

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);
    }
}

Finally, fetch the plugin preferences for use by the rest of the plugin code. I usually put preferences into a global array:

global $abc_my_plugin;
$abc_my_plugin = function_exists('soo_plugin_pref_vals') ?
    array_merge(abc_my_plugin_defaults(true), soo_plugin_pref_vals('abc_my_plugin'))
    : abc_my_plugin_defaults(true);

Note the use of soo_plugin_pref_vals(), which returns your plugin’s preferences as an associative array.

There are various ways you can code the above requirements, depending on your plugin’s exact needs. Some working examples:

Limitations

Version History

0.2.3 (2017-02-23)

Documentation update

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:

Posted 2009-09-06 (last modified 2017-03-13)