1Template::Plugin::DirecUtsoerry(C3o)ntributed Perl DocumTeenmtpaltaitoen::Plugin::Directory(3)
2
6 Template::Plugin::Directory - Plugin for generating directory listings
7
9 [% USE dir = Directory(dirpath) %]
10 # files returns list of regular files
12 [% FOREACH file = dir.files %]
13 [% file.name %] [% file.path %] ...
14 [% END %]
15 # dirs returns list of sub-directories
17 [% FOREACH subdir = dir.dirs %]
18 [% subdir.name %] [% subdir.path %] ...
19 [% END %]
20 # 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 # define a VIEW to display dirs/files
31 [% VIEW myview %]
32 [% BLOCK file %]
33 File: [% item.name %]
34 [% END %]
35 [% BLOCK directory %]
37 Directory: [% item.name %]
38 [% item.content(myview) | indent -%]
39 [% END %]
40 [% END %]
41 # display directory content using view
43 [% myview.print(dir) %]
44
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 The constructor expects a directory name as an argument.
53 [% USE dir = Directory('/tmp') %]
55 It then provides access to the files and sub-directories contained
57 within the directory.
58 # regular files (not directories)
60 [% FOREACH file IN dir.files %]
61 [% file.name %]
62 [% END %]
63 # directories only
65 [% FOREACH file IN dir.dirs %]
66 [% file.name %]
67 [% END %]
68 # files and/or directories
70 [% FOREACH file IN dir.list %]
71 [% file.name %] ([% file.isdir ? 'directory' : 'file' %])
72 [% END %]
73 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 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 [% FOREACH file = dir.list %]
93 [% IF file.isdir %]
94 * Directory: [% file.name %]
95 [% ELSE %]
96 * File: [% file.name %]
97 [% END %]
98 [% END %]
99 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 [% USE dir = Directory(dirpath) %]
106 * [% dir.path %]
107 [% INCLUDE showdir %]
108 [% 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 This example is adapted (with some re-formatting for clarity) from a
122 test in t/directry.t which produces the following output:
123 * 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 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 [% USE dir = Directory(dirpath, recurse=1) %]
142 ...
143 [% IF file.isdir -%]
145 * [% file.name %]
146 [% INCLUDE showdir dir=file FILTER indent(4) -%]
147 [% ELSE -%]
148 ...
149 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 [% VIEW myview %]
155 [% BLOCK file %]
156 - [% item.name %]
157 [% END %]
158 [% BLOCK directory %]
160 * [% item.name %]
161 [% item.content(myview) FILTER indent %]
162 [% END %]
163 [% END %]
164 The view "print()" method can then be called, passing the "Directory"
166 object as an argument.
167 [% USE dir = Directory(dirpath, recurse=1) %]
169 [% myview.print(dir) %]
170 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 [% BLOCK directory %]
177 * [% item.name %]
178 [% item.content(myview) FILTER indent %]
179 [% END %]
180 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 With the recurse option disabled, as it is by default, the "directory"
187 block should explicitly call a "scan()" on each directory.
188 [% VIEW myview %]
190 [% BLOCK file %]
191 - [% item.name %]
192 [% END %]
193 [% BLOCK directory %]
195 * [% item.name %]
196 [% item.scan %]
197 [% item.content(myview) FILTER indent %]
198 [% END %]
199 [% END %]
200 [% USE dir = Directory(dirpath) %]
202 [% myview.print(dir) %]
203
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 This module is free software; you can redistribute it and/or modify it
214 under the same terms as Perl itself.
215
217 Template::Plugin, Template::Plugin::File, Template::View
218perl v5.34.0 2022-01-21 Template::Plugin::Directory(3)