soo_plugin_pref

This is a plugin for Textpattern.

• Support forum topic
• Author site
• GitHub

Contents

• Overview
• Usage
• Info for plugin authors
  • Configuration
  • Limitations
• History

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):

• Ensure the plugin will load on the admin side (i.e., if type is 0, change it to 1)
• Set the plugin flags (the official plugin template at https://github.com/textpattern/textpattern-plugin-template/blob/master/zem_plugin_example.php already does this for you)

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:

• event is always set to “plugin_prefs”
• prefs_id is always set to 1
• type is always set to 2 (hidden from main Prefs page)

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:

• soo_required_files, a public-side plugin
• soo_editarea, an admin-side plugin

Limitations

• Currently the only allowed values for html are text_input and yesnoradio.
• soo_plugin_pref only handles global preferences. If your plugin has a mix of global and per-user preferences, you will have to code all the handling of the per-user preferences.
• Preferences are only installed on enabling a plugin. Upgrading an enabled plugin does not trigger soo_plugin_pref to install any preferences new to the upgraded version. The user must disable and re-enable it to pick up the new prefs. Plugin authors should include a note about this when releasing a new version with new prefs.

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)

• Pre-installing soo_plugin_pref is no longer required for automatic preference installation
• Each preference is now assigned a position value that determines relative order in the admin interface, and that corresponds to its position in the defaults array

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:

• Automatic installation/removal of preferences on plugin install/deletion
• Simple admin interface for setting preferences