Configuration file format

Each Daizu CMS installation must have a configuration file containing information about how to connect to the database and the Subversion repository, where output should be written to when published, and how plugins and generators should be configured. This is done with a small XML file.

XML format

You can call the file anything you want, providing you tell Daizu CMS where it is. With the daizu utility program you can do this with the -c option. In the Perl API, simply pass a filename to the Daizu constructor. These are both optional. If a configuration filename isn't specified, Daizu will use the name in the DAIZU_CONFIG environment variable if it is set, or failing that the name /etc/daizu/config.xml if such a file exists.

A complete example configuration file is shown at the bottom of this page, and the same file is provided in the Daizu source package as config.xml.

The root element should be called config. All the elements described in this file should be in the Daizu ‘config’ namespace:

http://www.daizucms.org/ns/config/

Elements in other namespaces will be ignored by the config file parser, as will unrecognized elements, so you can use the same file for configuration for other parts of your publishing setup if necessary.

Currently XInclude (xi:include) elements won't be expanded in these files.

Elements

The following elements will be understood if they appear as children of the root element, providing they are in the config namespace. They are listed in alphabetical order. Anything that isn't described as being ‘required’ below is optional.

config

As well as being the name of the root element, you can also have other config elements nested inside it. In this case they must have a path attribute. Any configuration inside them will only apply to the file or directory at that path, any anything inside it (if it's a directory) unless overridden by another config element with a more specific path.

Only some configuration elements are allowed in a nested, or ‘inner’ config element. The plugin element allows plugins to be enabled for only part of your content, or to have different configuration for different parts. This will not apply to all types of plugin. The guid-entity and generator can also be used to override the default configuration.

database

Required. Describes how to connect to the PostgreSQL database. Can have the following attributes:

dsn: Required. DBI datasource name of the database. Will usually be something like ‘dbi:Pg:dbname=foo’.
user: Database username. Default is not to specify one.
password: Database password. Default is not to specify one.

generator

Generators define how files are published, by providing Perl code to generate the URLs and output data. The default generator is Daizu::Gen, with no additional configuration. A generator element can provide configuration to whatever generator is used for a particular path. The path is taken from the config element it is used in. Note that the choice of which generator to use for each part of the content is made in the content repository, by putting daizu:generator properties on files and directories.

The content of the generator element can provide additional configuration for the generator. Exactly how the content is interpretted depends on which generator class is used.

These attributes can be used:

class: Required. The name of the Perl class (and module) we are configuring.

guid-entity

Required. There can be more than one of these, but there must be exactly one in the global configuration (a child of the root element and not in any inner config elements). Ones in inner config elements provide different configuration for particular parts of the content, and override the global one.

Each guid-entity element defines the ‘entity’ which will be used to create a GUID URI for each file. The global guid-entity is used for the default entity for all files, unless another one overrides it. You might want to use the overrides for example so that several different websites get GUIDs using their own domain name.

Warning: the GUID URIs are created when a file's first revision is loaded into the database, before it is checked out into any working copies. Therefore, you must set up the guid-entity elements before loading any data from the repository if you want to get the right type of GUIDs. The only way to adjust this later is to fiddle with the database or manually set daizu:guid properties on all your files.

The following attributes are allowed:

entity: Required. This should be a valid taggingEntity as defined by RFC 4151. See that specification for full details of what is allowable, but basically you should use a domain name or email address, followed by a comma, followed by a date on which you had sole authority of it. For example, if you registered the domain ‘example.com’ in 2005 and still own it in 2006, you could use this:
example.com,2006

live-working-copy

Required. The ID number of the working copy which should be regarded as the ‘live’ one, reflecting the content visible on the live websites. The number should be provided in the id attribute, and will usually have the value ‘1’.

output

Required, at least if you want to generate any output.

There can be multiple output elements which send output for different elements to different document root directories. For example, if you publish several websites on different domains you probably want to send their output to different places.

The following attributes can be present:

url: Required. Content for this URL, or any which start with it, will be published using this output element's configuration.
path: Required. The path on the filesystem where output will be written to.
index-filename: The filename to use for ‘index’ files, which have a URL ending with /. This defaults to index.html, but depending on your web server configuration you might want to change it, for example to index.shtml if you need to do that to turn on server-side includes.
redirect-map: The filesystem path to write a map file to for redirects from old, currently inactive URLs, to new ones which are likely to be equivalent. If this isn't present then the map won't be output at all. The paths (the keys you're mapping from) will be the full path of the old URL within the domain specified in the url attribute. The corresponding value will be an absolute URL.
gone-map: Same as redirect-map except that it contains the paths of URLs which are no longer active, and which don't have anywhere to redirect to. The corresponding values are simply ‘1’.

plugin

There can be any number of plugin elements. Each should have a class attribute, whose value names the class (and module) to be used to register the plugin.

If the plugin element has any content, it will be passed to the plugin's register method, so some plugins might use that to allow extra configuration. Daizu itself doesn't pay any attention to this content.

Note that some types of plugin can be applied to parts of the content repository by configuring them inside an inner config element with a path. They can also have different configuration for different paths.

repository

Required. Describes how to connect to the Subversion repository containing the site content. It doesn't matter how you create the repository providing it conforms to the required structure.

The following attributes can be present:

url: Required. Should contain a full URL to the repository. Daizu has only been tested with file and svn URLs, but in principle other types should work.
username: Required for svn URLs, but not file ones. The username to use when connecting to svnserve.
password: The password to use for svn URLs.

template-test

If present, must have an attribute called path which points to a directory on the filesystem containing copies of all the template files (the _template directories). These will be used when generating pages instead of reading the templates from the working copy. This makes it easier to test changes to templates, since you don't have to commit them for the changes to take effect.

Code in the _lib directory is also looked for at this path, rather than in the live working copy.

Example

<?xml version="1.0" encoding="US-ASCII"?>
<config xmlns="http://www.daizucms.org/ns/config/">

 <!-- How to connect to the database.  -->
 <database dsn="dbi:Pg:dbname=web_geoff" />

 <!-- How to connect to the Subversion repository.  -->
 <repository url="file:///home/geoff/svn/repos/web_geoff" />

 <!-- Which working copy should the live sites be generated from?
      This will usually be '1' because that will be the ID number
      assigned to the first working copy you check out.
   -->
 <live-working-copy id="1" />

 <!-- Domains/email addresses to use, with associated dates of
      ownership, for minting tag URIs as GUIDs for each file.
      There must be exactly one global one to act as a default.
   -->
 <guid-entity entity="foobar.com,2006" />

 <!-- Write all output for example.com into the directory where
      Apache will look for it (assuming Apache has been told to).
   -->
 <output url="http://www.example.com/"
         path        ="/var/www/example.com"
         redirect-map="/var/www/example.com-redirect.map"
         gone-map    ="/var/www/example.com-gone.map" />

 <!-- The stuff in this <config> element will only apply to
      content at or below the specified path.
   -->
 <config path="example.com">

  <!-- Use a different domain and date for creating GUID URIs
       for content on the 'example.com' website.
    -->
  <guid-entity entity="example.com,2006-03" />

  <!-- Provide extra configuration for the Daizu::Gen generator,
       when it is used on a particular website, to enable the
       creation of a XML sitemap file (for Google and other
       search engines).
    -->
  <generator class="Daizu::Gen">
   <xml-sitemap />
  </generator>

 <!-- End of configuration specific to 'example.com'. -->
 </config>

 <!-- You'll need at least one plugin to load articles from
      files.  This one is for files which have XHTML fragments
      as their content.  -->
 <plugin class="Daizu::Plugin::XHTMLArticle" />

 <!-- Enable the syntax-highlighting plugin, which is supplied
      with Daizu CMS.  -->
 <plugin class="Daizu::Plugin::SyntaxHighlight" />

 <!-- This plugin adds convenient 'anchors' to headings, so
      that you can link to specific sections of pages.  -->
 <plugin class="Daizu::Plugin::HeaderAnchor" />

 <!-- Add missing width, height, alt, and title attributes to
      images.  -->
 <plugin class="Daizu::Plugin::ImageMetadata" />

 <!-- Provide a box of 'related links' on some articles.  -->
 <plugin class="Daizu::Plugin::RelatedLinks" />

 <!-- Use templates from the filesystem instead of the
      database.
   -->
 <template-test path="/home/geoff/svn/web_geoff" />

</config>

Daizu CMS