How to integrate extension configuration into bin/configure

Introduction

• Performance is much better because plugin topics don't have to be parsed for every request
• No need for site admins to modify files from the installed package (which should always be read-only)
• Complex Perl data structures can be initialized
• Single administration interface bin/configure for both core and extension settings
• Increased security for sensitive configuration data and account information

Overview

1. Create a Config.spec file in the extension directory
   • In SVN trunk, this is XXX/lib/Foswiki/Plugins/XXX/Config.spec for a plugin named XXX, YYY/lib/Foswiki/Contrib/YYY/Config.spec for a contrib (or Skin, or anything else) named YYY.
   • in a live installation, this is the lib/Foswiki/Plugins/XXX/ directory for a plugin named XXX
2. In that spec file, add your configuration requirements by following the style of the examples below.
3. When configure is run the configuration options will be available through the interface. The default settings read will be saved along with the rest of the configuration.

# ---+ Extensions
# ---++ JSCalendarContrib
# **STRING 30**
# Calendar style. The following styles are shipped by default with the
# Mishoo DHTML calendar: # blue, blue2, brown, green, setup, system, tas, win2k-1, win2k-2,
# win2k-cold-1, win2k-cold-2. Your local site may have other locally-defined styles.
$Foswiki::cfg{JSCalendarContrib}{style} = 'blue';
# **STRING 5**
# Controls what language is used in calendars.
$Foswiki::cfg{JSCalendarContrib}{lang} = 'en';
1;

# ---+ Extensions
# ---++ EditTablerowPlugin
# **BOOLEAN**
# Debug setting
$Foswiki::cfg{Plugins}{EditTablerowPlugin}{DEBUG} = $FALSE;
1;

The details of .spec files

1. to allow an extension author to include new fields in the $Foswiki::cfg configuration hash that can then be referred to by the extension.
2. to support setting those values from the configure interface.

Structure of a .spec file

# ---+ Extensions
# ---++ MyContrib
# This extension supports firtling, graunching, munging and general dibbling.

# **STRING 30 EXPERT**
# Options for the <tt>graunch</tt> command

# **SELECT blue rinse,mullet,beehive**
# Style setting. This sets the required <strong>hair style</strong>.

$Foswiki::cfg{MyContrib}{style} = 'blue rinse';

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

Namespaces

Types

A note on the PERL type

PERL H Switchboard entries

# **PERL H**
# This setting is required to enable executing "myscript" script from the bin directory
$Foswiki::cfg{SwitchBoard}{myscript} = {
    package  => 'Foswiki::Contrib::MyContrib',
    function => 'myFunction',
    context  => { view => 1 },
    };

Checkers

#---+ 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.
$Foswiki::cfg{MyContrib}{style} = 'blue rinse';

package Foswiki::Configure::Checkers::MyContrib::style;
use base 'Foswiki::Configure::Checkers::Checker';

sub check {
    my $this = shift; # This object is used to generate warning and error strings

    if ($Foswiki::cfg{MyContrib}{style} eq 'mullet') {
        return $this->WARNING("Mullets went out of fashion in the 1980's");
    } elsif ($Foswiki::cfg{MyContrib}{style} eq 'blue rinse') {
        return $this->ERROR("Blue rinses are reserved for little old ladies");
    }
    return '';
}

Specialised User Interfaces (UIs)