| ASB::Out::Template-A.04.01.06 |
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.
ASB::Out::Template
This is the option to use if you want at all to use the class described in this man page.
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?).
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 http://cpan.org,
download and install the Template-Toolkit module (see INSTALL under
http://search.cpan.org/~abw/Template-Toolkit-2.14/), 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):
~/.asb/template/TEMPLATE_SET
/etc/asb/template/TEMPLATE_SET
TEMPLATE_DIR/TEMPLATE_SET
~/.asb/template
/etc/asb/template
TEMPLATE_DIR
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:
the file ASB__Item__Dir.index.html would be applied to items of the
class ASB::Item::Dir, and the result would be a file called
DIRNAME/index.html.
the file ASB__Item__File.html would be applied to items of the class
ASB::Item::File (and any children), and the result would be a file called
FILENAME.html.
as a special case, the file ASB__Item__File__Film.dev_null would be applied
to items of the class ASB::Item::File::Film but no file would be created.
It's of course only of interest if there are side effects due to application of
the template, or if items of a certain sub-class should be occulted, whereas
some parent class has a template with output.
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, [% opts.author %] 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.
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).
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).
Function very similar to targetfile but to be used for directories. The returned directory is also created if it doesn't exist yet.
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).
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.
Given a text, returns a text that can be used as an HTML parameter value.
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.
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.
Similar in principle to the extra_always function, it returns the list of keys that should be shown only on demand.
| ASB::Out::Template- |