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
Note: The description given here works from TWiki version 4.1 onward only!
Introduction
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
.
Overview
Here is the high-level overview:
- 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
- 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.
Examples:
# ---+ 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';
1;
From Plugins.TWiki::Plugins::Plugins.EditTablerowPlugin
# ---+ Plugins
# ---++ EditTablerowPlugin
# **BOOLEAN**
# Debug setting
$TWiki::cfg{Plugins}{EditTablerowPlugin}{DEBUG} = 0;
1;
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:
- to allow an extension author to include new fields in the
$TWiki::cfg
configuration hash that can then be referred to by the extension.
- 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,
# **STRING 30 EXPERT**
# 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.
# **STRING 30 EXPERT**
# 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';
Namespaces
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.
Types
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** |
LANGUAGE |
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** |
URLPATH |
Relative URL |
- |
**URLPATH** |
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).
Checkers
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
Discussion for this interface takes place in
Codev.SpecifyingConfigurationItemsForExtensions.
Related topics: TWikiPlugins,
TWikiPluginsSupplement
Comments & Questions about this Supplemental Document Topic