Daizu::Plugin::RelatedLinks - add information to 'img' elements

This plugin adds a box in the 'extras-col' (the right-hand column of each page) for articles with a daizu:links property.

Warning: this plugin is experimental and is almost certain to change the way it works later. At a minimum the two text files it loads are likely to become database tables. The property name used might also change.

There is a blog article discussing the design of this feature, and also providing an example of what the related links look like:

http://www.daizucms.org/blog/2006/11/related-links/

To use this you add a property called daizu:links to an article file. This should contain one or more URLs separated by whitespace (probably best to put them on separate lines). The URLs must be listed in a file called _hide/links.txt, which contains the following tab-separated fields:

• The name identifying the source (website) which the link refers to. This should be a short name which doesn't contain whitespace, and which must exist in the sources file described below.
• The URL, which must exactly match (as a simple string) the URL used in the property.
• The title to use for the link, which should be text encoded as UTF-8.
• Optionally, a short description of the format of the information at the URL. This can act as a warning to users of what they should expect. Suitable values would be 'PDF' or 'Flash'. It will be displayed in parentheses after the link's title.
  
  If you don't want to include a format for a link you don't need the last tab separator either.

The name of the link source is looked up in a separate text file called _hide/link-sources.txt which is in a similar format, with the following fields:

• The name of the source, used to identify it in the links.txt file.
• The source's URL, which should probably be the homepage of the website.
• The title of the source, which is used as the cover text of its link.

If the URLs of the link itself and the source are the same then only one link is shown, using the title of the link.

To turn on this plugin, include the following in your Daizu CMS configuration file:

    <plugin class="Daizu::Plugin::RelatedLinks" />

Daizu::Plugin::RelatedLinks->register($cms, $whole_config, $plugin_config, $path)

Registers the plugin as a filter for all articles at or in $path.

$self->filter_article($cms, $file, $doc)

Does the actual filtering in-place on $doc and returns it.

This doesn't actually modify the content, just adds an 'extra template' if there is a daizu:links property on the file.

Daizu::Plugin::RelatedLinks->links_for_file($file)

This is called by the template plugin/relatedlinks_extras.tt to get the links which should be provided. If that template is used then this is expected to return at least one related link. $file should be the article file whose page is being generated.

This is a class method so that it can be called using the Template::Plugin::Class module from the template.

This gets the URLs from the daizu:links property and finds the extra metadata for them in the files _hide/links.txt and _hide/link-sources.txt. Those files must exist and must contain information about any URLs referenced in the property, and any link 'sources' referenced for those URLs.

Returns a reference to an array of hashes containing the URLs and titles.

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

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