Dakar TWiki.cfg File Format

As of Dakar, the TWiki.cfg has a special format that allows to "type strongly" each of the settings, and to group them in sections and subsections for better organization.

The values available to configuration are determined by parsing =TWiki.cfg. Special full-line comments guide the parse.

Any comment of the form:

#---+ Some text

is treated as a new section (configure treats them as a foldable block), and following comments are dragged in too. ---++, ---+++ and so on are treated as subsections (and rendered as H3, H4, etc)

Comments of the form

# **TYPE opts**

Types of settings

For all setting types, the option M denotes that the field is mandatory. The type can be used by the configuration interface to decide how to render, store and validate the setting.

URL [M]

Denotes that the setting will express an URL (example: http://localhost/)

PATH [M]

Denotes that the setting will express a physical path on the server (example: /home/twiki/data)

URLPATH [M]

Denotes that the setting will express a url path (example: /twiki)

BOOLEAN [M]

Denotes that the setting will receive the values true or false only.

STRING [ <COLS> [ 'X' <<ROWS> [M]

Denotes that the setting is a string. For an 80 character single line prompt box, use STRING 80. For a 10-line textarea, STRING 80 X 10

PASSWORD [M]

Denotes that the setting is a password, and as such is not sent out in the html. (some code works out if the user has typed into this field) otherwise similar to string.

REGEX [M]

Denotes that the setting is a regular expression

SELECT opt1,opt2,...,optN [m][M]

Denotes that the setting can receive only one of the specified options (e.g. radio). [m] indicates the multiple values can be selected (e.g. checkbox)

OCTAL [M]

Denotes that the setting is an octal number

COMMAND [M]

Denotes that the setting is an external command to be invoked by TWiki (example, rcs)

NUMBER [M]

Denotes that the setting is a decimal number

Example:

# **BOOLEAN**
# You can use persistent CGI session tracking even if you are not using login.
# This allows you to have persistent session variables - for example, skins.
# Client sessions are not required for logins to work, but TWiki will not
# be able to remember users unless there is some other mechanism - such as
# browser cacheing of authentication - available.
#
# See TWiki.TWikiUserAuthentication for a full discussion of the pros and
# cons of using persistent sessions.
$cfg{UseClientSessions} = 1;

Going Forward

There is a need to be able to specify arbitrary structures that can be compiled to config panels. The two main structuring elements are arrays and records.

For example, a simple mandatory record can be defined like this:

{ field1,field2,...fieldN }

An array of numbers like this:

[ NUMBER ]

An array of records like this:

[ { f1,f2..fN } ]

Example:

# **[ { defaultWeb,folder,onError,onNoTopic,onSuccess,spambox,topicPath,user } ] M**
# Configuration for the MailInContrib
# The configuration is in the form of an array of mailbox specifications. Each
# specification defines a number of fields:
$TWiki::cfg{MailInContrib} = [
{
   folder => 'pop://junk+junk:junk@mail.junk.net/Inbox',
   onError => 'log',
   onNoTopic => 'error',
   onSuccess => 'log delete',
   topicPath => 'to subject',
  },
{
   folder => 'pop://junk+junk:junk@mail.junk.net/Inbox',
   onError => 'log',
   onNoTopic => 'error',
   onSuccess => 'log delete',
   topicPath => 'to subject',
  },
];

DISCOVER package [M]

Works like SELECT, but having as options the modules under package. The caveat is that the module must be installed under the lib directory.

Example:

# **DISCOVER TWiki::Client**

This will look for all the module files in lib/TWiki/Client With the current default setup, it will show a combobox with the values TWiki::Client::ApacheLogin and TWiki::Client::TemplateLogin

Discussion

There is also a need for SELECT options to be somehow extended - for eg the JoomlaUserMapper needs to be added to the list of selectable UserMappers if that module is installed

-- SvenDowideit - 13 May 2006

Added a "new" type for that.

-- RafaelAlvarez - 13 May 2006

Sounds like a case for YAML or JSON

-- AntonAylward - 13 May 2006

The two main ideas behind ConfigPanelAddOn are to have pluggable configuration modules, so extensions can be configured from a single interface without modifying the code, and abstracting the "representation" of the configuration file.

The later means that to change the file format the only thing that needs to be changed is the parser, the rest of the instrastructure will still work. Pluggable parsers for different file formats is part of the design.

-- RafaelAlvarez - 13 May 2006