ASB::Out::Template - output class of ASB using the Template::Toolkit module



asb [...] --output ASB::Out::Template [--out-template-dir template-dir] [--out-template template-set] [...]

Other options, possibly also relevant to the template output methods, are described in the asb(1) man page.



The ASB::Out::Template class can be used to output the tree of items created by ASB to almost any kind of text format, the mostly expected format being nevertheless HTML.

It absolutely requires the Template Toolkit CPAN module. Understanding of this toolkit is recommended in order to be able to write own template sets.




This is the option to use if you want at all to use the class described in this man page.

--out-template=TEMPLATE_SET set of templates to be used

You can use this option to select which template set should be used. The default template set is called default (what else?).

--out-template-dir=TEMPLATE_DIR where to find the template set

You can use this option to select where ASB should search for the template set and other related files (e.g. icons and stylesheets). The default is to search in the sub-directory called template in the current directory.



Under Debian, the Template Toolkit can be installed through the libtemplate-perl package, e.g. by the command apt-get install libtemplate-perl.

Under Windows and ActivePerl, use the ppm shell to install the Template-Toolkit package.

For most other Perl flavours, you can either go to, download and install the Template-Toolkit module (see INSTALL under, or you can use, most probably as root or administrator, the command perl -MCPAN -e shell to install the same module. Be aware that I didn't test those variants (feedback is very welcome).



As a general rule, the ASB::Out::Template class uses the Template Toolkit with its default options, with two exceptions: the INCLUDE_PATH is set to encompass user, system and package directories ; and four variables can be used to populate the templates.


One of the important options of the Template::Toolkit is the INCLUDE_PATH, i.e. the list of directories where the toolkit searches for templates and other related files in a relative manner.

ASB::Out::Template defines the INCLUDE_PATH in the following manner (and search order):

  1. ~/.asb/template/TEMPLATE_SET

  2. /etc/asb/template/TEMPLATE_SET


  4. ~/.asb/template

  5. /etc/asb/template


Files with names containing two underscores (__) are searched for in those directories and listed to be used for output of items of the corresponding class, the double underscores being replaced by double columns. Also the extension of the filename will define how the resulting file will be named, based on the presence or not of a dot in this extension.

Three examples will make this clearer:

There are two rules to be considered here: only one file can be applied to each item, and it will be the first one found with the most specific class (i.e. considering the 3 above examples, ASB__Item__File__Film.dev_null would be applied to an item of class ASB::Item::File::Film::Mjpg and not ASB__Item__File.html).


It is also important to know which variables can be used within a template. The class ASB::Out::Template defines four of them:


It is the output object instantiated from ASB::Out::Template, for which methods are described below.


This is the object representing the current item being processed. Methods and variables are class specific (and not yet properly described), but a fair amount of them is used as an example in the default template set.


This hash variable allows use of the options which can be set e.g. per command line. For example, [% %] would output the name of the author (which can be set through the --author option).


It's a simple string variable containing the name of the file to be created out of the template. It would be empty in the case of the null device.



This chapter describes the methods defined for objects of the class ASB::Out::Template, and which can be used within templates through the out variable. We will first list the class' own methods, and then the ones inherited from the ASB::Out class.

All the methods listed below are meant to be used in Templates in a form similar to [% out.function_name(parameters) %], the return value of the function replacing the placeholder.


copy_to_target(source,relative_file) returns relative_path

This method searches for the source file either absolutely, relatively to the current directory, and finally relatively to the directories in the INCLUDE_PATH (see INCLUDE_PATH). Once found, the source file is copied as up as possible in the hierarchy: either to the target directory as given by the --target option, or, if not defined, to one of the top directories given on the command line. Finally, the method returns relative_path, the path of the copied file, relative to the relative_file file.

This method is explicitly meant to insert style sheets and icons/images within an HTML page, as in the following example:

 <link rel="stylesheet" type="text/css"
        href="[% out.copy_to_target("defstyle.css",target_file) %]"

where defstyle.css could be anywhere along the INCLUDE_PATH (BTW, this method is currently the only reason for having introduced the target_file template variable).


targetfile(@dirs, file) returns target_file

Taken a list of path parts (directories and a file), returns the concatenated path of the file, removing parent directories (i.e. '..' parts) and adding in front the target directory defined through the --target option (if applicable).

targetdir(@dirs) returns target_dir

Function very similar to targetfile but to be used for directories. The returned directory is also created if it doesn't exist yet.

format_time(time_date) returns human_time_date

Given a time_date in seconds or in EXIF format (YYYY:MM:DD HH:MM:SS), returns a time and date string in human readable format (not localized).

get_html_id(any_text) returns html_id

Given a text (generally the name of a file), returns a text that can be used as an HTML id parameter. Be aware that texts which differ only by exotic signs will lead to the same id.

get_html_value(any_text) returns html_value

Given a text, returns a text that can be used as an HTML parameter value.

href(any_path) returns html_path

Given a (generally relative) path, returns an HTML path that can be used as an href value. This method currently only escapes spaces and replaces blackslashes with slashes, it probably only work for UN*X and DOS like OSs.

extra_always(extras_ref) returns @extras

Given a hash reference for extra parameters (e.g. EXIF values), it returns a list of the keys that should be always shown. Caveat: it's currently only possible to influence this list by modifying the source code.

extra_not_always(extras_ref) returns @extras

Similar in principle to the extra_always function, it returns the list of keys that should be shown only on demand.