June 10, 2006
Configuration System

ProWiki uses a system of ConfigurationFiles to configure wikis as a whole and a system of ConfigurationPages to configure or reconfigure parts of wikis (in the extreme down to single pages). The atomic parts of the configuration process are variable assigments like "SiteName=ProWikiCenter" which are called Options.

The reading of configuration information happens on any single request (e. g. a page request like "FrontPage" or a Command request like "ThisWiki:action=index"), most obviously to (1) control whether the user has the right to have this specific request executed and (2) to look for specific rendering options.

The Options are processed sequentially, file by file, page by page, and sequentially within the text of files and pages. If a variable name recurs in this overall sequence of options, it's value (the variable content) is overwritten (see the notes about reconfiguration down the page).

It's easy to understand with an example. Lets assume that a user requests a page "Admin/Template/Example" then the total sequence to build the configuration information is:

  1. server.cfg -- the ServerConfigFile contains server specific data (e. g. the diretory for external software subsystems, the path to access sendmail, ...)
  2. global.cfg -- the GlobalConfigFile contains general data for all wikis (in general on the server, but this might even span multiple servers, for example to block certain IP ranges of spammers)
  3. cluster.cfg -- the ClusterConfigFile may contain data shared by a group of wikis (e. g. the WikiCluster containing the list of member wikis)
  4. wiki.cfg -- the WikiConfigFile contains the central wiki data, especially that which never changes (for example the CookieName used to identify users)
  5. Context -- the TopContextPage contains the everyday wiki configuration (for example the SiteName shown in the BrowserTitle)
  6. Admin/Context -- this configures the Admin page Branch, it restricts the edit access to it and all its subpages to Admins.
  7. Admin/Template/Context -- this ContextPage configures the Template branch to show pure text on all subpages and archive any single change
  8. Admin/Template/Example/Context -- this page either does not exist or contains no Options, because no special configuration is needed
Note that all ConfigurationFiles must exist (with the exception of the configurable cluster.cfg), while all ContextPages are optional.


It very common that options are defined at some point in the configuration sequence and redefined later in the sequence. This is sometimes called Reconfiguration. For example you will define a TemplateFile for the whole wiki, while changing the look of specific parts of your wiki later on, redefining TemplateFile.

Note: This silent overwriting can also lead to confusions, when you want to change an Option and you actually change it and nothing happens! Probably the option is redefined later in the configuration sequence, so the value is overwritten before its use (maybe even 10 lines down on the same page). In doubt use CdmlDisplay to show the effective variable value or TextSearch to look at what places the options exists.


The distribution of configuration information among ContextPages makes ProWiki more efficient, because configuration information is often only read for requests to pages that actually use them.


This actually creates a system of inheritance:

  1. each page inherits the options from its parent
  2. each page may define or redefine options by having a ContextSubPage
  3. each page again passes his options to its SubPages recursively

FolderAdministration FolderConfiguration FolderProgramming