Template::Plugin::Directory(3pm)

1Template::Plugin::DirecUtsoerry(C3o)ntributed Perl DocumTeenmtpaltaitoen::Plugin::Directory(3)
2
3
4

NAME

6       Template::Plugin::Directory - Plugin for generating directory listings
7

SYNOPSIS

9           [% USE dir = Directory(dirpath) %]
10
11           # files returns list of regular files
12           [% FOREACH file = dir.files %]
13              [% file.name %] [% file.path %] ...
14           [% END %]
15
16           # dirs returns list of sub-directories
17           [% FOREACH subdir = dir.dirs %]
18              [% subdir.name %] [% subdir.path %] ...
19           [% END %]
20
21           # list returns both interleaved in order
22           [% FOREACH item = dir.list %]
23              [% IF item.isdir %]
24                 Directory: [% item.name %]
25              [% ELSE
26                 File: [% item.name %]
27              [% END %]
28           [% END %]
29
30           # define a VIEW to display dirs/files
31           [% VIEW myview %]
32              [% BLOCK file %]
33              File: [% item.name %]
34              [% END %]
35
36              [% BLOCK directory %]
37              Directory: [% item.name %]
38              [% item.content(myview) ⎪ indent -%]
39              [% END %]
40           [% END %]
41
42           # display directory content using view
43           [% myview.print(dir) %]
44

DESCRIPTION

46       This Template Toolkit plugin provides a simple interface to directory
47       listings.  It is derived from the Template::Plugin::File module and
48       uses Template::Plugin::File object instances to represent files within
49       a directory.  Sub-directories within a directory are represented by
50       further Template::Plugin::Directory instances.
51
52       The constructor expects a directory name as an argument.
53
54           [% USE dir = Directory('/tmp') %]
55
56       It then provides access to the files and sub-directories contained
57       within the directory.
58
59           # regular files (not directories)
60           [% FOREACH file = dir.files %]
61              [% file.name %]
62           [% END %]
63
64           # directories only
65           [% FOREACH file = dir.dirs %]
66              [% file.name %]
67           [% END %]
68
69           # files and/or directories
70           [% FOREACH file = dir.list %]
71              [% file.name %] ([% file.isdir ? 'directory' : 'file' %])
72           [% END %]
73
74           [% USE Directory('foo/baz') %]
75
76       The plugin constructor will throw a 'Directory' error if the specified
77       path does not exist, is not a directory or fails to stat() (see Tem‐
78       plate::Plugin::File).  Otherwise, it will scan the directory and create
79       lists named 'files' containing files, 'dirs' containing directories and
80       'list' containing both files and directories combined.  The 'nostat'
81       option can be set to disable all file/directory checks and directory
82       scanning.
83
84       Each file in the directory will be represented by a Template::Plug‐
85       in::File object instance, and each directory by another Template::Plug‐
86       in::Directory.  If the 'recurse' flag is set, then those directories
87       will contain further nested entries, and so on.  With the 'recurse'
88       flag unset, as it is by default, then each is just a place marker for
89       the directory and does not contain any further content unless its
90       scan() method is explicitly called.  The 'isdir' flag can be tested
91       against files and/or directories, returning true if the item is a
92       directory or false if it is a regular file.
93
94           [% FOREACH file = dir.list %]
95              [% IF file.isdir %]
96                 * Directory: [% file.name %]
97              [% ELSE %]
98                 * File: [% file.name %]
99              [% END %]
100           [% END %]
101
102       This example shows how you might walk down a directory tree, displaying
103       content as you go.  With the recurse flag disabled, as is the default,
104       we need to explicitly call the scan() method on each directory, to
105       force it to lookup files and further sub-directories contained within.
106
107           [% USE dir = Directory(dirpath) %]
108           * [% dir.path %]
109           [% INCLUDE showdir %]
110
111           [% BLOCK showdir -%]
112             [% FOREACH file = dir.list -%]
113               [% IF file.isdir -%]
114               * [% file.name %]
115                 [% file.scan -%]
116                 [% INCLUDE showdir dir=file FILTER indent(4) -%]
117               [% ELSE -%]
118               - [% f.name %]
119               [% END -%]
120             [% END -%]
121            [% END %]
122
123       This example is adapted (with some re-formatting for clarity) from a
124       test in t/directry.t which produces the following output:
125
126           * test/dir
127               - file1
128               - file2
129               * sub_one
130                   - bar
131                   - foo
132               * sub_two
133                   - waz.html
134                   - wiz.html
135               - xyzfile
136
137       The 'recurse' flag can be set (disabled by default) to cause the con‐
138       structor to automatically recurse down into all sub-directories, creat‐
139       ing a new Template::Plugin::Directory object for each one and filling
140       it with any further content.  In this case there is no need to explic‐
141       itly call the scan() method.
142
143           [% USE dir = Directory(dirpath, recurse=1) %]
144              ...
145
146               [% IF file.isdir -%]
147               * [% file.name %]
148                 [% INCLUDE showdir dir=file FILTER indent(4) -%]
149               [% ELSE -%]
150                  ...
151
152       From version 2.01, the Template Toolkit provides support for views.  A
153       view can be defined as a VIEW ... END block and should contain BLOCK
154       definitions for files ('file') and directories ('directory').
155
156           [% VIEW myview %]
157           [% BLOCK file %]
158              - [% item.name %]
159           [% END %]
160
161           [% BLOCK directory %]
162              * [% item.name %]
163                [% item.content(myview) FILTER indent %]
164           [% END %]
165           [% END %]
166
167       Then the view print() method can be called, passing the Directory
168       object as an argument.
169
170           [% USE dir = Directory(dirpath, recurse=1) %]
171           [% myview.print(dir) %]
172
173       When a directory is presented to a view, either as [% myview.print(dir)
174       %] or [% dir.present(view) %], then the 'directory' BLOCK within the
175       'myview' VIEW is processed, with the 'item' variable set to alias the
176       Directory object.
177
178           [% BLOCK directory %]
179              * [% item.name %]
180                [% item.content(myview) FILTER indent %]
181           [% END %]
182
183       The directory name is first printed and the content(view) method is
184       then called to present each item within the directory to the view.
185       Further directories will be mapped to the 'directory' block, and files
186       will be mapped to the 'file' block.
187
188       With the recurse option disabled, as it is by default, the 'directory'
189       block should explicitly call a scan() on each directory.
190
191           [% VIEW myview %]
192           [% BLOCK file %]
193              - [% item.name %]
194           [% END %]
195
196           [% BLOCK directory %]
197              * [% item.name %]
198                [% item.scan %]
199                [% item.content(myview) FILTER indent %]
200           [% END %]
201           [% END %]
202
203           [% USE dir = Directory(dirpath) %]
204           [% myview.print(dir) %]
205

TODO

207       Might be nice to be able to specify accept/ignore options to catch a
208       subset of files.
209

AUTHORS

211       Michael Stevens <michael@etla.org> wrote the original Directory plugin
212       on which this is based.  Andy Wardley <abw@wardley.org> split it into
213       separate File and Directory plugins, added some extra code and documen‐
214       tation for VIEW support, and made a few other minor tweaks.
215

VERSION

217       2.7, distributed as part of the Template Toolkit version 2.18, released
218       on 09 February 2007.
219

COPYRIGHT

221       This module is free software; you can redistribute it and/or modify it
222       under the same terms as Perl itself.
223