/ 
Daizu-0.2
River stage zero No dependents
/ Daizu::Gen

NAME

Daizu::Gen - default generator class

DESCRIPTION

This class, and subclasses of it, are responsible for deciding which URLs should be created (generated) from each file or directory in a working copy, and generating the output which will be served for those URLs. This class itself is used by default, but you can use a different generator class by setting the daizu:generator property to the name of a Perl module and class. If you set it on a file, it will affect only that file. If you set it on a directory then it will affect that directory and all its descendants, unless they themselves have a daizu:generator property.

This class creates URLs based on the daizu:url property, and the names of files and directories. The results will be similar to the URLs that the filesystem would have if they were served directly from a webserver. Files with names like _index.html (anything starting with _index followed by a dot) are special in that the filename will not appear as part of the URL. Instead the URL will end with a trailing slash (/).

With this generator class only files generate URLs. Directories are ignored, except when a Google sitemap is configured as described below.

TODO - provide a whole section giving guidance on subclassing this. Include an example of a *_urls_info() override which calls its superclass version, like root_dir_urls_info() in Daizu::Gen::Blog.

CONFIGURATION

The only configuration information which this generator currently makes use of is the google-sitemap element shown here:

<config path="example.com">
 <generator class="Daizu::Gen">
  <google-sitemap />
 </generator>
</config>

The sitemap URL will be generated from the directory at the path indicated. It must be a directory, not a plain file. In this case, the sitemap is likely to have a URL like http://example.com/sitemap.xml.gz.

The google-sitemap element may an optional url attribute, which should be a relative or absolute URL at which to publish the sitemap file. Its default value is sitemap.xml.gz

METHODS

Daizu::Gen->new(%options)

Return a new generator object. Requires the following options:

cms

A Daizu object.

root_file

A Daizu::File object for the file on which this generator was specified, or a top-level directory if there was no specification of which generator was in use. So usually this file will have a daizu:generator property naming this class.

config_elem

The XML DOM node (an XML::LibXML::Element object) of a generator element in the Daizu CMS configuration file, or undef if there is no appropriate configuration provided.

$gen->base_url($file)

Return a single URL for $file, as a URI object. This 'base URL' is typically used as the basis for any other URLs the file might generate.

Files with a daizu:url property will take that as their base URL.

Directories can have base URLs even if they don't actually generate any URLs in the publication process, since those URLs are used to build URLs for any content they contain. Directory URLs end in a forward slash.

Files with names starting with _index. have a base URL identical to their parent directory.

Returns undef if there is no URL for this file. This can happen if the file's name is _hide or _template, or if it is contained in a directory with a name like that, or if there is no daizu:url property for the file or any of its ancestors.

Subclasses should typically not override this, but instead override custom_base_url(), as the blog generator does for example.

$gen->custom_base_url($file)

Override this method in a subclass if you want to use a custom URL scheme, for example one based on publication dates instead of file and directory names.

This method is called by base_url(). By the time it has been called, checks have already been done for the daizu:url property, the special names like _hide, and the base URL of the parent directory, if any. If these don't determine the URL, or absence of one, then the custom_base_url() method should supply one, or return undef if the file shouldn't have a base URL.

If this is called then $file is guaranteed to have a parent, but its parent's base URL hasn't been determined, so it may not have one.

The default implementation just uses the base URL of the parent and the name of the file or directory in the obvious way.

$gen->urls_info($file)

Return a list of URLs generated by $file (a Daizu::File object). May return nothing if the file doesn't generate any URLs.

This method calls the base_url() and custom_urls_info() methods to do the actual work. All it does is resolve relative URLs and fill in some missing information, so you're more likely to need to override those two, or one of the *_urls_info methods below, if you want to build a new generator class with a differnet URL scheme. This is what the Daizu::Gen::Blog generator does.

Each URL value returned is actually a reference to a hash containing the following keys, which are all required:

url

The actual URL as a URI object. This will always be an absolute URL.

generator

The name of the class of generator which was used to create these URLs.

method

The name of the method which should be called to generate the output for this file at this URL.

TODO - reference to docs for API of generator methods

argument

Some value which determines exactly which one of a set of URLs of the same basic type this is. For example if there were several URLs for an article, one for each of several pages, then they would probably have the same generator and method, but the page number would be stored as the argument.

The argument is always defined. It will be the empty string if custom_urls_info() didn't supply an argument value.

type

The MIME type which the resource should be served with.

This method returns nothing if the file has no URLs, for example if it has no base URL (which might happen if it is in an _hide directory).

$gen->custom_urls_info($file)

This is called by the urls_info() method above, and does the actual work of supplying the URLs. It should also return a list of hashes for the URLs generated by $file, but is allowed to be a bit more lazy. The following are the differences it may make in return value (although note that it is permissible for this method to return exactly the same values as for urls_info() if it wishes):

  • The url value doesn't have to be an absolute URL, and doesn't have to be a URI object. If the URL desired is the same as the value returned by the base_url() method, then this value can simply be the empty string.

  • The generator value may be omitted or undefined, in which case it will default to the class name of $gen.

  • The argument value may be omitted or undefined, in which case it will default to the empty string.

The Daizu::Gen implementation of the method simply calls the four *_urls_info methods listed next as appropriate, so usually subclasses should override those instead of this method.

$gen->article_urls_info($file)

Return a list of URLs for an article. $file must be a Daizu::File object for a file which is an article. Uses the article_urls() method in Daizu::File to do the work, so this is just a simple wrapper to allow subclasses to override it.

The return value is as specified for custom_urls_info().

$gen->unprocessed_urls_info($file)

Return a list of URLs for the non-article non-directory file in $file, which must be a Daizu::File object.

This base-class implementation returns a single URL which uses the unprocessed() method in this class.

The return value is as specified for custom_urls_info().

The content type, if not defined by the file, will default to application/octet-stream.

$gen->dir_urls_info($file)

Return a list of URLs for the directory specified by $file, which should be a Daizu::File object. This base-class implementation returns no URLs.

The return value is as specified for custom_urls_info().

$gen->root_dir_urls_info($file)

Return a list of URLs for the directory $file, which should be a Daizu::File object for the root directory of the generator (the directory which has the daizu:generator property or a top-level directory). This base-class implementation returns no URLs unless the configuration specifies that a Google sitemap should be published, in which case it returns a single URL for the sitemap file, using the google_sitemap() method.

If a file, rather than a directory, has a daizu:generator property, then this method isn't called and the file isn't distinguished in any way for being the 'root file'.

The return value is as specified for custom_urls_info().

$gen->generate_web_page($file, $url, $template_overrides, $template_vars)

Use Template Toolkit to do the generation of the content for $file into the URL in $url (which must be a reference to a URL info hash). $template_vars should be a reference to a hash, and is passed to the template, as are the values 'cms' (the Daizu object), 'file' ($file), and 'url' ($url).

If $template_overrides is defined it should be a reference to a hash containing template rewriting instructions. Whenever a template is loaded its name will be looked up in the hash. If an entry is found, the template named by the corresponding value is loaded instead of the original template.

Daizu::TTProvider is used for loading the templates, so they will get loaded directly from the working copy $file is from.

TODO - exactly what format do these URL hashes have to be in? There are several alternatives in use in various places now. Ah, no, these ones need a filehandle at least.

$gen->article_template_overrides($file, $url_info)

Returns a reference to a hash of template rewriting instructions for articles. Each key should be the name of a template which is expected to be loaded (perhaps by a Template Toolkit INCLUDE directive), and the value is the name of a different template which should be loaded instead.

These rewrites will be done for all articles generated by the article() method.

The base-class implementation returns an empty hash reference.

$gen->article_template_variables($file, $url_info)

Returns a reference to a hash of template variable values which should be passed to Template Toolkit when an article page is generated. The keys should be the names of variables which are expected to be present by a template, and the values are passed in as-is.

The base-class implementation returns an empty hash reference.

$gen->article($file, $urls)

A standard generator method for generating an article (a file with its daizu:type attribute set to article). It calls the generate_web_page() method to handle the templating. You can pass all the URLs for the different pages of a multi-page article in at once.

Subclasses can provide template rewriting and extra template variables by overriding the methods article_template_overrides() and article_template_variables().

$gen->unprocessed($file, $urls)

Generate an 'unprocessed' file. This is a standard generator method which simply prints the file's data to each of the URL's file handles

$gen->google_sitemap($file, $urls)

A standard generator method which generates a Google sitemap file, gzip compressed.

The XML namespace URL used in Google sitemaps is available in the variable $Daizu::Gen::SITEMAP_NS.

The format of Google sitemaps is documented here:

http://www.google.com/webmasters/sitemaps/docs/en/protocol.html

$gen->scaled_image($file, $urls)

A standard generator method which generates a scaled version of an image file. $file must represent an image in a format which can be understood by Image::Magick.

The argument should consist of two numbers, the desired width and height of the resulting image, separated by a single space.

$gen->navigation_menu($file, $url)

Return a recursive data structure describing a suitable menu for displaying on a page associated with $file, which must be a Daizu::File object. $url is the URL info for the page being generated.

This is called from the default nav_menu.tt template to generate the menu to put in the right-hand column.

The menu will not include the homepage (because that is presumably already linked from the top of the page or something, and it would be a waste of an extra level in the menu), and will not include any 'retired' articles.

The return value is a reference to an array of zero or more hashes, each of which will contain the following keys:

The URL of the page the menu item refers to, relative to $url. That is, this may not be an absolute URL, but it should get you to the right place from the page this menu was intended for.

This value will not be present for a menu item which refers to the current URL, because that shouldn't be a link (it's bad usability practice to link to the current page, because people might wonder why nothing happened).

title

The full title of the page the item refers to, if any.

short_title

An alternative title which might be more suitable for display in a menu. It will usually be the same as title, but sometimes the user (or a plugin) might provide an abbreviated title which is better in this kind of context.

children

A reference to an array of zero or more hashes, in the same format as the top-level ones, for items which should be presented as 'children' of this menu item, typically as a nested list.

COPYRIGHT

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

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