NAME

Daizu - class for accessing Daizu CMS from Perl

DESCRIPTION

Most access to Daizu functionality requires a Daizu object. It provides a database handle for access to the 'live' content data, and a SVN::Ra object for access to the Subversion repository.

Some other classes are documented as requiring a $cms value as the first argument to their constructors or methods. This should always be a Daizu object.

CONSTANTS

$Daizu::VERSION

The version number of Daizu CMS (as a whole, not just this module).

$Daizu::DEFAULT_CONFIG_FILENAME

The full path and filename of the config file which will be read by default, if none is specified in the constructor call or the environment.

Value: /etc/daizu/config.xml

$Daizu::CONFIG_NS

The URI used as an XML namespace for the elements in the config file.

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

$Daizu::HTML_EXTENSION_NS

The URI used as an XML namespace for special elements in XHTML content.

Value: http://www.daizucms.org/ns/html-extension/

$Daizu::HIDING_FILENAMES

A list of file and directory names which prevent any publication of files with one of the names, or anything inside a directory so named. Separated by '|' so that the whole string can be included in Perl and PostgreSQL regular expressions.

Value: _template|_hide

%Daizu::DEFAULT_ARTICLE_PARSERS

A mapping of mime types to code references (for methods in this class) which can read articles in these formats and turn them into an XHTML DOM which can then be used for further processing to publish the article.

Handlers are only defined for XHTML articles (which are actually fragments of XHTML, the bit inside the body element).

These are only the default article parsers. You can add more using plugins, which should register themselves by calling the add_article_parser() method below. See for example Daizu::Plugin::PodArticle.

METHODS

Daizu->new($config_filename)

Return a Daizu object based on the information in the given configuration file. If $config_filename is not supplied, it will fall back on any file specified by the DAIZU_CONFIG environment variable, and then by the default config file (see $DEFAULT_CONFIG_FILENAME above).

The value returned will be called $cms in the documentation.

For information about the format of the configuration file, see the documentation on the website: http://www.daizucms.org/doc/config-file/

$cms->ra

Return the Subversion remote access (SVN::Ra) object for accessing the repository.

$cms->db

Return the DBI database handle for accessing the Daizu database.

$cms->config_filename

Returns a string containing the filename from which the configuration was loaded. The filename may be a full (absolute) path, or may be relative to the current directory at the time the Daizu object was created.

$cms->live_wc

Return a Daizu::Wc object representing the live working copy.

$cms->load_revision($update_to_rev)

Load information about revisions and file paths for any new revisions, upto $update_to_rev, from the repository into the database. If no revision number is supplied, updates to the latest revision.

This is called automatically before any working copy updates, to ensure that the database knows about revisions before any working copies are updated to them. It is idempotent.

This is a simple wrapper round the code in Daizu::Revision.

$cms->add_property_loader($pattern, $object, $method)

Plugins can use this to register themselves as a 'property loader', which will be called when a property whose name matches $pattern is updated in a working copy.

Currently it isn't possible to localize property loader plugins to have different configuration for different paths in the repository using the normal path configuration system.

The pattern can be either the exact property name, a wildcard match on some prefix of the name ending in a colon, such as svn:*, or just a * which will match all property names. There isn't any generic wildcard or regular expression matching capability.

$object should be an object (probably of the plugin's class) on which $method can be called. Since it is called as a method, the first value passed in will be $object, followed by these:

$cms

A Daizu object.

$id

The ID number of the file in the wc_file database table for which the new property values apply.

$props

A reference to a hash of the new property values. Only properties which have been changed during a working copy update will have entries, so the file may have other properties which haven't been changed.

Properties which have been deleted during the update will have an entry in this hash with a value of undef.

An example of a property loader method is _std_property_loader in this module. It is always registered automatically.

$cms->add_article_parser($mime_type, $path, $object, $method)

Plugins can use this to register a method which will be called whenever an article of type $mime_type needs to be parsed. The MIME type can be fully specified, or be something like image/* (to match any image format), or just be * to match any type. These aren't generic glob or regex patterns, so only those three levels of specificity are allowed. The most specific plugin available will be tried first. Plugins of the same specificity will be tried in the order they are registered. The plugin methods can return false if they can't handle a particular file for some reason, in which case Daizu will continue to look for another suitable plugin.

The plugin registered will only be called on for files with paths which are the same as, or are under the directory specified by, $path. Plugins should usually just pass the $path value from their register method through to this method as-is.

$method (a method name) will be called on $object, and will be passed $cms and a Daizu::File object representing the input file. The method should initialize the file object with the content (XHTML DOM) and metadata for the article and return true to indicate that it was able to load the file as an article. Alternatively it can return false to indicate that it can't handle the file, in which case it shouldn't alter the file object at all.

See Daizu::Plugin::PodArticle or Daizu::Plugin::PictureArticle for examples of registering and writing article parser plugins, and also the parse_xhtml_article() method in this class.

$cms->add_html_dom_filter($path, $object, $method)

Plugins can use this to register a method which will be called whenever an XHTML file is being published. $method (a method name) will be called on $object, and will be passed $cms and an XML DOM object of the source, as a XML::LibXML::Document object. The plugin method should return a similar object, either a completely new copy of the DOM or the same value it was passed (which it might have modified in place).

The plugin registered will only be called on for files with paths which are the same as, or are under the directory specified by, $path. Plugins should usually just pass the $path value from their register method through to this method as-is.

See Daizu::Plugin::SyntaxHighlight for an example of registering and implementing a DOM filter method.

$cms->parse_xhtml_article($cms, $file)

An article parser which parses fragments of XHTML content and turns them into an XHTML DOM. This can also be used for parsing any file whose content is in a suitable format. It is a thin wrapper around the parse_xhtml_content() function.

The redundant $cms argument is there because this function needs to match the calling convention for article parsers, as described in the documentation for the add_article_parser() method.

$cms->call_property_loaders($id, $props)

Calls the plugin methods which wish to be informed of property changes on a file, where $id is a file ID for a record in the wc_file table, and $props is a reference to a hash of the format described for the add_property_loader() method.

$cms->guid_entity

Return the entity to be used for minting GUID URLs for the file at $path. This finds the best match from the guid-entity elements in the configuration file and returns the corresponding entity value.

$cms->output_config($url)

Return information about where the published output for $url (a string or URI object) should be written to. If there is a suitable output element in the configuration file then this will return a hash containing information from that element, followed by a list of three strings, which will all be defined. If you join these strings together (by passing them to the file function from Path::Class for example) to form a complete path then it will be the path to the file (never directory) which the output should be written to.

The first value returned will be a reference to a hash containing the following keys:

url

The value from the url attribute in the configuration file, as a URI object.

path

The value from the path attribute.

index_filename

The value from the index-filename attribute, or the default value index.html if one isn't set.

redirect_map

The value from the redirect-map attribute, or undef if there isn't one.

gone_map

The value from the gone-map attribute, or undef if there isn't one.

The other three values are:

• The absolute path to the document root directory, which will be the value of the path attribute in the appropriate output element in the configuration file. This is the same as the path value in the hash.

• The relative path from there to the directory in which the output file should be written. This is given separately so that you can create that directory if it doesn't exist. This will be the empty string if the output file is to be stored directly in the document root directory, but the file function mentioned above will correctly elide it for you in that case.

• The filename of the output file. This is a single name, not a path.

If the configuration doesn't say where $url should be published to then this will return nothing.

TODO - this doesn't use file itself, so the results aren't portable across different platforms.

COPYRIGHT

This software is copyright 2006 Geoff Richards <geoff@laxan.com>. For licensing information see this page:

http://www.daizucms.org/license/