Extension:PreferencesExtension

From MediaWiki.org

Jump to: navigation, search
Manual on MediaWiki Extensions
List of MediaWiki Extensions
Preferences Extension

Release status: stable
Implementation MyWiki, Special page
Description Allows other extensions to add new user preferences to MediaWiki
Author(s) Austin Che
Last Version 2006/11/16
MediaWiki  ?
License No license specified
Download below or here
Example [1] (login required)

Contents

[edit] Description

This extension hooks into the default Special:Preferences page and allows other extensions to easily add new preferences.

[edit] Installation

Copy code to extensions/PreferencesExtension/PreferencesExtension.php and add this to LocalSettings.php:

 require_once("$IP/extensions/PreferencesExtension/PreferencesExtension.php");

[edit] Usage

A typical usage is in your extension function to call wfAddPreferences with an array of new preferences to be added. Each preference is specified as another associative array. The valid keys for this associative array are (everything is optional):

[edit] Parameters

  • name: the name of the preference (the name for the form element)
  • section: the name of the section in the preferences dialog. This should be the internal name used not the displayed name (e.g. 'prefs-misc'). To create a new section, simply use a different name. The actual display text will be whatever is returned using wfMsg(section) so you can set the text by adding the appropriate value to the message cache.
  • type: The type of form element being added. The valid types are the constants PREF_USER_T, PREF_TOGGLE_T, PREF_TEXT_T, PREF_PASSWORD_T, and PREF_INT_T. The default is PREF_USER_T.
  • size: For type=PREF_TEXT_T, PREF_PASSWORD_T, and PREF_INT_T, defines the size of the textbox
  • html: For PREF_USER_T, allows specification of the complete html to be inserted into the preferences form. The string @VALUE@ inside this html will be expanded to the current value of this element
  • min: Defines the minimum allowed integer value for PREF_INT_T types
  • max: Defines the maximum allowed integer value for PREF_INT_T types
  • validate: The name of a function. If defined, for PREF_TEXT_T, PREF_PASSWORD_T, and PREF_USER_T, this function will be called to validate the form value on submission. The function should take one argument (the form value) and return the value that should be used as the submitted value.
  • save: The name of a function. If defined, this function will be called to set the element's value instead of using the default of setting the value via $wgUser->setOption. The function takes two arguments ($name, $value).
  • load: The name of a function. If defined, this function will be called to load an element's value instead of the default using $wgUser->getOption. This function takes one argument $name and should return the value.
  • default: The default value to use for this element in displaying the form.

[edit] Code

<?php
 
/**
 * This allows other extensions to add their own preferences to the default preferences display
 *
 * Author: Austin Che <http://openwetware.org/wiki/User:Austin_J._Che>
 */
 
$wgExtensionCredits['specialpage'][] = array(
    'name' => 'PreferencesExtension',
    'version' => '2006/11/16',
    'author' => 'Austin Che',
    'url' => 'http://openwetware.org/wiki/User:Austin_J._Che/Extensions/PreferencesExtension',
    'description' => 'Enables extending user preferences',
);
$wgHooks['SpecialPage_initList'][] = 'wfOverridePreferences';
 
// constants for pref types
define('PREF_USER_T', 1);
define('PREF_TOGGLE_T', 2);
define('PREF_TEXT_T', 3);
define('PREF_PASSWORD_T', 4);
define('PREF_INT_T', 5);
 
// each element of the following should be an array that can have keys:
// name, section, type, size, validate, load, save, html, min, max, default
if (!isset($wgExtensionPreferences))
     $wgExtensionPreferences = array();
 
/**
 * Adds an array of prefs to be displayed in the user preferences
 *
 * @param array $prefs
 */
function wfAddPreferences($prefs)
{
    global $wgExtensionPreferences;
 
    foreach ($prefs as $pref)
    {
        $wgExtensionPreferences[] = $pref;
    }
}
 
function wfOverridePreferences(&$list)
{
    // we 'override' the default preferences special page with our own
    $list["Preferences"] = array("SpecialPage", "Preferences", "", true, "wfSpecialPreferencesExtension");
    return true;
}
 
function wfSpecialPreferencesExtension()
{
    require_once('SpecialPreferences.php');
 
    // override the default preferences form
    class SpecialPreferencesExtension extends PreferencesForm
    {
        // unlike parent, we don't load in posted form values in constructor
        // until savePreferences when we need it
        // we also don't need resetPrefs, instead loading the newest values when displaying the form
        // finally parent's execute function doesn't need overriding
        // this leaves only two functions to override
        // one for displaying the form and one for saving the values
 
        function savePreferences() 
        {    
            // handle extension prefs first
            global $wgUser, $wgRequest;
            global $wgExtensionPreferences;
 
            foreach ($wgExtensionPreferences as $p)
            {
                $name = isset($p['name']) ? $p['name'] : "";
                if (! $name)
                    continue;
 
                $value = $wgRequest->getVal($name);
                $type = isset($p['type']) ? $p['type'] : PREF_USER_T;
                switch ($type)
                {
                    case PREF_TOGGLE_T:
                        if (isset($p['save']))
                            $p['save']($name, $value);
                        else
                            $wgUser->setOption($name, $wgRequest->getCheck("wpOp{$name}"));
                        break;
 
                    case PREF_INT_T:
                        $min = isset($p['min']) ? $p['min'] : 0;
                        $max = isset($p['max']) ? $p['max'] : 0x7fffffff;
                        if (isset($p['save']))
                            $p['save']($name, $value);
                        else
                            $wgUser->setOption($name, $this->validateIntOrNull($value, $min, $max));
                        break;
 
                    case PREF_PASSWORD_T:
                    case PREF_TEXT_T:
                    case PREF_USER_T:
                    default:
                        if (isset($p['validate']))
                            $value = $p['validate']($value);
                        if (isset($p['save']))
                            $p['save']($name, $value);
                        else
                            $wgUser->setOption($name, $value);
                        break;
                }
            }
 
            // call parent's function which saves the normal prefs and writes to the db
            parent::savePreferences();
        }
 
        function mainPrefsForm( $status , $message = '' )
        {
            global $wgOut, $wgRequest, $wgUser;
            global $wgExtensionPreferences;
 
            // first get original form, then hack into it new options
            parent::mainPrefsForm($status, $message);
            $html = $wgOut->getHTML();
            $wgOut->clearHTML();
 
            $sections = array();
            foreach ($wgExtensionPreferences as $p)
            {
                if (! isset($p['section']) || ! $p['section'])
                    continue;
                 $section = $p['section'];
 
                $name = isset($p['name']) ? $p['name'] : "";
                $value = "";
                if ($name)
                {
                    if (isset($p['load']))
                        $value = $p['load']($name);
                    else
                        $value = $wgUser->getOption($name);
                }
                if ($value === '' && isset($p['default']))
                    $value = $p['default'];
 
                $sectext = htmlspecialchars(wfMsg($section));
                $regex = "/(<fieldset>\s*<legend>\s*" . preg_quote($sectext) . 
                    "\s*<\/legend>.*?)(<\/fieldset>)/s";
 
                // check if $section exists in prefs yet
                // cache the existence of sections
                if (!isset($sections[$section]))
                {
                    $sections[$section] = true;
 
                    if (! preg_match($regex, $html, $m))
                    {
                        // doesn't exist so add an empty section to end
                        $addhtml = "<fieldset><legend>$sectext</legend></fieldset>";
                        $html = preg_replace("/(<div id='prefsubmit'.*)/s", "$addhtml $1", $html);
                    }
 
                }
 
                $type = isset($p['type']) ? $p['type'] : PREF_USER_T;
                switch ($type)
                {
                    case PREF_TOGGLE_T:
                        $addhtml = $this->getToggle($name);
                        break;
 
                    case PREF_INT_T:
                    case PREF_TEXT_T:
                    case PREF_PASSWORD_T:
                        $size = isset($p['size']) && $p['size'] ? "size=\"{$p['size']}\"" : "";
                        $caption = isset($p['caption']) && $p['caption'] ? $p['caption'] : wfMsg($name);
                        if ($type == PREF_PASSWORD_T)
                            $type = "password";
                        else
                            $type = "text";
                        $addhtml = "<table>" . 
                            $this->addRow("<label for=\"{$name}\">$caption</label>",
                                          "<input type=\"$type\" name=\"{$name}\" value=\"{$value}\" $size />") . "</table>" ;
                        break;
 
                    case PREF_USER_T:
                    default:
                        $addhtml = preg_replace("/@VALUE@/", $value, isset($p['html']) ? $p['html'] : "");
                        break;
                }
 
                // the section exists
                $html = preg_replace($regex, "$1 $addhtml $2", $html);
            }
 
            $wgOut->addHTML($html);
 
            // debugging
            //$wgOut->addHTML($wgUser->encodeOptions());
        }
    }
 
    global $wgRequest;
    $prefs = new SpecialPreferencesExtension($wgRequest);
    $prefs->execute();
}


Retrieved from "http://www.mediawiki.org/wiki/Extension:PreferencesExtension"
Personal tools