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

AUTHORS

205       Michael Stevens wrote the original Directory plugin on which this is
206       based.  Andy Wardley split it into separate File and Directory plugins,
207       added some extra code and documentation for "VIEW" support, and made a
208       few other minor tweaks.
209
211       Copyright (C) 2000-2007 Michael Stevens, Andy Wardley.
212
213       This module is free software; you can redistribute it and/or modify it
214       under the same terms as Perl itself.
215

SEE ALSO

217       Template::Plugin, Template::Plugin::File, Template::View
218
219
220
221perl v5.34.0                      2022-01-21    Template::Plugin::Directory(3)
Impressum