template::plugin::directory(3)
NAME
Template::Plugin::Directory - Plugin for generating direc
tory listings
SYNOPSIS
[% USE dir = Directory(dirpath) %]
# files returns list of regular files
[% FOREACH file = dir.files %]
[% file.name %] [% file.path %] ...
[% END %]
# dirs returns list of sub-directories
[% FOREACH subdir = dir.dirs %]
[% subdir.name %] [% subdir.path %] ...
[% END %]
# list returns both interleaved in order
[% FOREACH item = dir.list %]
[% IF item.isdir %]
Directory: [% item.name %]
[% ELSE
File: [% item.name %]
[% END %]
[% END %]
# define a VIEW to display dirs/files
[% VIEW myview %]
[% BLOCK file %]
File: [% item.name %]
[% END %]
[% BLOCK directory %]
Directory: [% item.name %]
[% item.content(myview) | indent -%]
[% END %]
[% END %]
# display directory content using view
[% myview.print(dir) %]
DESCRIPTION
This Template Toolkit plugin provides a simple interface
to directory listings. It is derived from the Tem
plate::Plugin::File module and uses Template::Plugin::File
object instances to represent files within a directory.
Sub-directories within a directory are represented by fur
ther Template::Plugin::Directory instances.
- The constructor expects a directory name as an argument.
- [% USE dir = Directory('/tmp') %]
- It then provides access to the files and sub-directories
contained within the directory.
# regular files (not directories)
[% FOREACH file = dir.files %][% file.name %]- [% END %]
- # directories only
[% FOREACH file = dir.dirs %][% file.name %] - [% END %]
- # files and/or directories
[% FOREACH file = dir.list %][% file.name %] ([% file.isdir ? 'directory' :'file' %]) - [% END %]
- [% USE Directory('foo/baz') %]
- The plugin constructor will throw a 'Directory' error if
the specified path does not exist, is not a directory or
fails to stat() (see Template::Plugin::File). Otherwise,
it will scan the directory and create lists named 'files'
containing files, 'dirs' containing directories and 'list'
containing both files and directories combined. The 'nos
tat' option can be set to disable all file/directory
checks and directory scanning. - Each file in the directory will be represented by a Tem
plate::Plugin::File object instance, and each directory by
another Template::Plugin::Directory. If the 'recurse'
flag is set, then those directories will contain further
nested entries, and so on. With the 'recurse' flag unset,
as it is by default, then each is just a place marker for
the directory and does not contain any further content
unless its scan() method is explicitly called. The
'isdir' flag can be tested against files and/or directo
ries, returning true if the item is a directory or false
if it is a regular file.
[% FOREACH file = dir.list %][% IF file.isdir %]* Directory: [% file.name %][% ELSE %]* File: [% file.name %][% END %]- [% END %]
- This example shows how you might walk down a directory
tree, displaying content as you go. With the recurse flag
disabled, as is the default, we need to explicitly call
the scan() method on each directory, to force it to lookup files and further sub-directories contained within.
[% USE dir = Directory(dirpath) %]
* [% dir.path %]
[% INCLUDE showdir %]- [% BLOCK showdir -%]
[% FOREACH file = dir.list -%][% IF file.isdir -%]
* [% file.name %][% file.scan -%]
[% INCLUDE showdir dir=file FILTER indent(4) -%][% ELSE -%]
- [% f.name %]
[% END -%][% END -%] - [% END %]
- This example is adapted (with some re-formatting for clar
ity) from a test in t/directry.t which produces the fol lowing output:
* test/dir- file1
- file2
* sub_one- bar
- foo* sub_two- waz.html
- wiz.html- xyzfile- The 'recurse' flag can be set (disabled by default) to
cause the constructor to automatically recurse down into
all sub-directories, creating a new Template::Plu
gin::Directory object for each one and filling it with any
further content. In this case there is no need to explic
itly call the scan() method.
[% USE dir = Directory(dirpath, recurse=1) %]...
[% IF file.isdir -%]
* [% file.name %][% INCLUDE showdir dir=file FILTER indent(4) -%][% ELSE -%]...- From version 2.01, the Template Toolkit provides support
for views. A view can be defined as a VIEW ... END block
and should contain BLOCK definitions for files ('file')
and directories ('directory').
[% VIEW myview %]
[% BLOCK file %]- [% item.name %]- [% END %]
- [% BLOCK directory %]
* [% item.name %][% item.content(myview) FILTER indent %][% END %]
[% END %] - Then the view print() method can be called, passing the
Directory object as an argument.
[% USE dir = Directory(dirpath, recurse=1) %]
[% myview.print(dir) %] - When a directory is presented to a view, either as [%
myview.print(dir) %] or [% dir.present(view) %], then the
'directory' BLOCK within the 'myview' VIEW is processed,
with the 'item' variable set to alias the Directory
object.
[% BLOCK directory %]* [% item.name %][% item.content(myview) FILTER indent %][% END %]The directory name is first printed and the content(view)
method is then called to present each item within the
directory to the view. Further directories will be mapped
to the 'directory' block, and files will be mapped to the
'file' block.With the recurse option disabled, as it is by default, the
'directory' block should explicitly call a scan() on each
directory.
[% VIEW myview %]
[% BLOCK file %]- [% item.name %][% END %][% BLOCK directory %]* [% item.name %][% item.scan %]
[% item.content(myview) FILTER indent %][% END %]
[% END %][% USE dir = Directory(dirpath) %]
[% myview.print(dir) %]
TODO
Might be nice to be able to specify accept/ignore options
to catch a subset of files.
AUTHORS
Michael Stevens <michael@etla.org> wrote the original
Directory plugin on which this is based. Andy Wardley
<abw@kfs.org> split it into separate File and Directory
plugins, added some extra code and documentation for VIEW
support, and made a few other minor tweaks.
VERSION
2.51, distributed as part of the Template Toolkit version
2.08, released on 30 July 2002.
COPYRIGHT
This module is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.
SEE ALSO
- Template::Plugin, Template::Plugin::File, Template::View