configuration1Add my vote for this tag plugin1Add my vote for this tag create new tag
, view all tags
ALERT! NOTE: This is a SupplementalDocument topic which is not included with the official TWiki distribution. Please help maintain high quality documentation by fixing any errors or incomplete content. Put questions and suggestions concerning the documentation of this topic in the comments section below! Use the Support web for problems you are having using TWiki.

How to integrate Extension configuration into bin/configure

ALERT! Note: The description given here works from TWiki version 4.1 onward only!


With TWiki 4.1, the new configuration interface supports enhanced configuration for extensions (i.e. beyond simple "Enabled" for plugins). The benefits are:

  • In contrast to settings in the extension topic, complex data structures can be initialized
  • Performance is much better because plugin topics don't need to be parsed for every request
  • Single administration interface bin/configure for both core and extension settings

This topic describes how a plugin/contrib author can make his settings being picked up by bin/configure.


Here is the high-level overview:
  1. Create a Config.spec file in the plugin directory
    • In SVN, this is twikiplugins/XXX/lib/TWiki/Plugins/XXX/Config.spec for a plugin named XXX, twikiplugins/YYY/lib/TWiki/Contrib/YYY/Config.spec for a contrib named YYY.
    • in a live installation, this is the lib/TWiki/Plugins/XXX/ directory for a plugin named XXX
  2. In that spec file, follow the style of lib/TWiki.spec to document your settings and give defaults. You can either create a new sub-section in plugins or put the settings into the plugin section. It is best to follow the style of the examples below.


# ---+ Extensions
# ---++ JSCalendarContrib
# **STRING 10**
# Style setting. This sets your hair style.
$TWiki::cfg{JSCalendarContrib}{style} = 'blue rinse';
# **STRING 5**
# Controls what language is used in calendars.
$TWiki::cfg{JSCalendarContrib}{lang} = 'en';
From Plugins.TWiki::Plugins::Plugins.EditTablerowPlugin
# ---+ Plugins
# ---++ EditTablerowPlugin
# Debug setting
$TWiki::cfg{Plugins}{EditTablerowPlugin}{DEBUG} = 0;
Use the ---+ Plugins section for all plugins, and ---+ Extensions for everything else (Skins, TWikiApplications, AddOns, Contribs etc)

A note on performance: If you are writing a plugin, and all your configuration settings are in your .spec file, then remember to set $NO_PREFS_IN_TOPIC in your plugin (as described in lib/TWiki/Plugins/EmptyPlugin.pm). This will stop TWiki from parsing that file for settings every time it runs.

How to create .spec files

.spec files are executable perl files that are included by TWiki using the perl do function. Their purpose is twofold:
  1. to allow an extension author to include new fields in the $TWiki::cfg configuration hash that can then be referred to by the extension.
  2. to support setting those values from the configure interface.
configure reads .spec files twice; once using do to extract the default values for each field, and then again to extract formatted comments that tell configure how to present the field in the configure UI.

.spec files are only read by configure. When TWiki runs, it reads TWiki.cfg (generated by configure) but not .spec files. So any changes you make to a .spec file will not be seen in TWiki until after you run configure and save.

Structure of a .spec file

A .spec file is structured using TWiki-syntax headings. ---+ defines a top level 'twisty' block, while ---++ will create a running section within that block.

Plugins should use the ---+ Plugins section, and everything else (Skins, TWikiApplications, AddOns, Contribs etc) should use the ---+ Extensions section. All extensions should define their own sub-section. For example,

# ---+ Extensions
# ---++ MyContrib
# This TWiki extension is responsible for firtling, graunching, munging and general dibbling.
After the heading comes a header comment for the section, and then a list of one or more fields. Each field is introduced by a type comment which describes how the field is to be presented in configure. For example,
# Options for the <tt>graunch</tt> command
introduces a field which is expected to take a string value and will be prompted for using a 30-character wide text field. The field type name may be followed by one or more attributes which further refine the type - in the example above, 30 is an attribute that declares the width of the text field, and EXPERT indicates that the setting is only for experts. More detail on types and their attributes can be found below.

The type declaration is followed by a descriptive comment (which must be formatted using HTML, not Plugins.TWiki syntax).

# **SELECT blue rinse,mullet,beehive**
# Style setting. This sets the required hair style.
After this comment comes the default value for the field. This value will be overridden by the value read from TWiki.cfg (if there is one) when configure is run. It exists just to make that all fields have a value.
$TWiki::cfg{MyContrib}{style} = 'blue rinse';

Putting it all together, we get the .spec for MyContrib:

#---+ Extensions
#---++ MyContrib
# This TWiki extension extends TWiki to support graunching, munging and general dibbling.
# Options for the <tt>graunch</tt> command
$TWiki::cfg{MyContrib}{graunch} = "--flibble --nomunge";
# **SELECT blue rinse,mullet,beehive**
# Style setting. This sets the required hair style for topics.
$TWiki::cfg{MyContrib}{style} = 'blue rinse';


Keep your configuration values in the appropriate namespace. Plugins each have their own configuration namespace, viz. $Plugins.TWiki::Cfg{Plugins}{XXX} where XXX is the name of the plugin. All Enabled flags are already in this namespace e.g. $Plugins.TWiki::cfg{Plugins}{ActionTrackerPlugin}{Enabled} = 1;

Contribs, Skins, AddOns and TWikiApplications should all occupy the Extensions namespace e.g. $Plugins.TWiki::cfg{Extensions}{MailInContrib}{DEBUG} = 0;.

The namespaces for Plugins and Extensions are deliberately kept separate because Plugins are automatically loaded by TWiki by discovery of the .pm's from the Plugins directory. This means they can be selectively enabled and disabled, whereas other types of extension are always enabled if they are installed.


The following field types are supported in .spec files:
Type name Description Attributes Example
BOOLEAN Boolean value - **BOOLEAN**
COMMAND String representing an operating system command - **COMMAND**
NUMBER Numerical value - **NUMBER**
OCTAL Octal (permissions) value - **OCTAL**
PASSWORD Password (hidden) - **PASSWORD**
PATH File path - **PATH**
PERL Arbitrary perl value - **PERL**
REGEX Regular expression - **COMMAND**
SELECT Choices Comma-separated list of legal values **SELECT crypt,sha1,md5,plain**
SELECTCLASS Choice of classes/packages, where package names may be matched from disc. List of package names. Package specifications may include wildcards; in the example, all package with names ending in Login will be selected from the TWiki::Client package. none is a special name used to indicate no choice. **SELECTCLASS none,Plugins.TWiki::Client::*Login**
STRING Arbitrary text string width **STRING 30**
URL Absolute URL - **URL**

All fields support some common attributes:

EXPERT Indicates that this is an expert setting. This just generates a slightly different UI.
M Indicates this setting is mandatory (must have a value for TWiki to run)
H If this is present, the field will not be shown in configure

Note that these types are supported because there is a .pm for the type in the lib/TWiki/Configure/Types directory. Extensions may add other types by installing an appropriate .pm to this directory. The .pm may define the following functions:

prompt Generates the HTML to prompt for a value
=string2value Used to convert from the string returned by $query->param() to the actual stored value
equals Used to compare two values of this type
onUpdate Invoked if a value of this type is changed
See the code for examples and function specs.

A note on PERL

The PERL type allows you to enter arbitrary perl data structures for values. The value entered by a user must be valid perl, but that is the limit of the checking. If you use the PERL type, you are strongly recommended to implement a Checker for the field (see Checkers, below).


configure also supports optional checkers for values. These are packages in lib/TWiki/Configure/Checkers that are named for the field and define a single function, check. This function is used to perform value validation. For example,
#---+ Extensions
#---++ MyContrib
# The contrib is responsible for firtling, graunching, munging and general dibbling.
# **SELECT blue rinse,mullet,beehive**
# Style setting. This sets the <i>required</i> hair style.
$TWiki::cfg{MyContrib}{style} = 'blue rinse';
The MyContrib extension might install lib/TWiki/Configure/Checkers/MyContrib/style.pm as follows:
package TWiki::Configure::Checkers::MyContrib::style;
use base 'TWiki::Configure::Checkers::Checker';

sub check {
    my $this = shift;

    if ($TWiki::cfg{MyContrib}{style} eq 'mullet') {
        return $this->WARNING("Mullets went out of fashion in the 1980's");
    } elsif ($TWiki::cfg{MyContrib}{style} eq 'blue rinse') {
        return $this->ERROR("Blue rinses are reserved for little old ladies");
    return '';
The string returned by check will be used to generate a warning/error message in configure when the relevant value is found in TWiki.cfg. Checkers can also be used to 'guess' values based on platform inspection. See lib/TWiki/Configure/Checkers/DataDir.pm for an example of this approach.

Specialised User Interfaces (UIs)

configure supports the inclusion of specialised UIs for very complex applications. For example, the extensions installer is a specialised UI, as is the Plugin enabler. Specialised UIs are packages stored in the lib/TWiki/Configure/UIs directory. You have to be very expert to use them, and there is almost no documentation.

Contributors: ThomasWeigert, HaraldJoerg, CrawfordCurrie


Discussion for this interface takes place in Codev.SpecifyingConfigurationItemsForExtensions.

Related topics: TWikiPlugins, TWikiPluginsSupplement

Comments & Questions about this Supplemental Document Topic

Please use the Support forum if you have questions about TWiki features. This comment section is about the documentation of this topic.
Edit | Attach | Watch | Print version | History: r3 < r2 < r1 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r3 - 2006-12-02 - CrawfordCurrie
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2018 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.