3
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Strict//EN">
6
<title>Template::Plugin::Directory</title>
7
<link rel="stylesheet" type="text/css" href="../../../css/blue.css" title="Clear Blue">
8
<link rel="alternate stylesheet" type="text/css" href="../../../css/orange.css" title="Clear Orange">
9
<link rel="alternate stylesheet" type="text/css" href="../../../css/green.css" title="Clear Green">
10
<link rel="alternate stylesheet" type="text/css" href="../../../css/purple.css" title="Clear Purple">
11
<link rel="alternate stylesheet" type="text/css" href="../../../css/grey.css" title="Clear Grey">
13
<link rel="stylesheet" type="text/css" href="../../../css/ie6.css" />
15
<link rel="stylesheet" type="text/css" href="/css/print.css" media="print">
16
<script type="text/javascript" src="../../../js/tt2.js"></script>
17
<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
18
<meta name="author" content="Andy Wardley">
23
<a href="../../../index.html" id="logo" alt="" title="Click for the Home Page"><span class="alt">TT2 Home Page</span></a>
25
<li><a href="../../../modules/index.html">Modules</a></li>
26
<li><a href="../../../modules/Template/index.html">Template::*</a></li>
27
<li><a href="../../../modules/Template/Plugin/index.html">Plugin::*</a></li>
28
<li class="last"><a href="../../../modules/Template/Plugin/Directory.html">Directory.pm</a></li>
30
<div class="controls">
31
<a href="#" class="menu show" onclick="widescreen_off(); return false" title="Show Menu">
32
<span class="about">Click to view the menu. It's very nice.</span>
34
<a href="#" class="menu hide" onclick="widescreen_on(); return false" title="Hide Menu">
35
<span class="about">Click to hide the menu and go all widescreen!</span>
39
<a href="../../../modules/Template/Plugin/Date.html" title="Template::Plugin::Date" class="go back">Back<span class="about"><h4>Template::Plugin::Date</h4>Plugin to generate formatted date strings</span></a>
40
<a href="../../../modules/Template/Plugin/index.html" title="Template::Plugin::* Modules" class="go up">Up<span class="about"><h4>Template::Plugin::* Modules</h4></span></a>
41
<a href="../../../modules/Template/Plugin/Dumper.html" title="Template::Plugin::Dumper" class="go next">Next<span class="about"><h4>Template::Plugin::Dumper</h4>Plugin interface to Data::Dumper</span></a>
44
<h1 class="headline">Template::Plugin::Directory</h1>
45
<h2 class="subhead">Plugin for generating directory listings</h1>
50
<a href="../../../index.html" id="logo"></a>
53
<li class="l0 first"><a href="../../../manual/index.html">Manual</a></li>
54
<li class="l0"><a href="../../../modules/index.html" class="warm">Modules</a></li>
55
<li class="l1"><a href="../../../modules/Template.html">Template.pm</a></li>
56
<li class="l1"><a href="../../../modules/Template/index.html" class="warm">Template::*</a></li>
57
<li class="l2"><a href="../../../modules/Template/Base.html">Base.pm</a></li>
58
<li class="l2"><a href="../../../modules/Template/Config.html">Config.pm</a></li>
59
<li class="l2"><a href="../../../modules/Template/Constants.html">Constants.pm</a></li>
60
<li class="l2"><a href="../../../modules/Template/Context.html">Context.pm</a></li>
61
<li class="l2"><a href="../../../modules/Template/Directive.html">Directive.pm</a></li>
62
<li class="l2"><a href="../../../modules/Template/Document.html">Document.pm</a></li>
63
<li class="l2"><a href="../../../modules/Template/Exception.html">Exception.pm</a></li>
64
<li class="l2"><a href="../../../modules/Template/Filters.html">Filters.pm</a></li>
65
<li class="l2"><a href="../../../modules/Template/Grammar.html">Grammar.pm</a></li>
66
<li class="l2"><a href="../../../modules/Template/Iterator.html">Iterator.pm</a></li>
67
<li class="l2"><a href="../../../modules/Template/Namespace/index.html">Namespace::*</a></li>
68
<li class="l2"><a href="../../../modules/Template/Parser.html">Parser.pm</a></li>
69
<li class="l2"><a href="../../../modules/Template/Plugin.html">Plugin.pm</a></li>
70
<li class="l2"><a href="../../../modules/Template/Plugin/index.html" class="warm">Plugin::*</a></li>
71
<li class="l3"><a href="../../../modules/Template/Plugin/Autoformat.html">Autoformat.pm</a></li>
72
<li class="l3"><a href="../../../modules/Template/Plugin/CGI.html">CGI.pm</a></li>
73
<li class="l3"><a href="../../../modules/Template/Plugin/Datafile.html">Datafile.pm</a></li>
74
<li class="l3"><a href="../../../modules/Template/Plugin/Date.html">Date.pm</a></li>
75
<li class="l3"><a href="../../../modules/Template/Plugin/Directory.html" class="warm">Directory.pm</a></li>
76
<li class="l3"><a href="../../../modules/Template/Plugin/Dumper.html">Dumper.pm</a></li>
77
<li class="l3"><a href="../../../modules/Template/Plugin/File.html">File.pm</a></li>
78
<li class="l3"><a href="../../../modules/Template/Plugin/Filter.html">Filter.pm</a></li>
79
<li class="l3"><a href="../../../modules/Template/Plugin/Format.html">Format.pm</a></li>
80
<li class="l3"><a href="../../../modules/Template/Plugin/HTML.html">HTML.pm</a></li>
81
<li class="l3"><a href="../../../modules/Template/Plugin/Image.html">Image.pm</a></li>
82
<li class="l3"><a href="../../../modules/Template/Plugin/Iterator.html">Iterator.pm</a></li>
83
<li class="l3"><a href="../../../modules/Template/Plugin/Math.html">Math.pm</a></li>
84
<li class="l3"><a href="../../../modules/Template/Plugin/Pod.html">Pod.pm</a></li>
85
<li class="l3"><a href="../../../modules/Template/Plugin/Procedural.html">Procedural.pm</a></li>
86
<li class="l3"><a href="../../../modules/Template/Plugin/String.html">String.pm</a></li>
87
<li class="l3"><a href="../../../modules/Template/Plugin/Table.html">Table.pm</a></li>
88
<li class="l3"><a href="../../../modules/Template/Plugin/URL.html">URL.pm</a></li>
89
<li class="l3"><a href="../../../modules/Template/Plugin/View.html">View.pm</a></li>
90
<li class="l3"><a href="../../../modules/Template/Plugin/Wrap.html">Wrap.pm</a></li>
91
<li class="l2"><a href="../../../modules/Template/Plugins.html">Plugins.pm</a></li>
92
<li class="l2"><a href="../../../modules/Template/Provider.html">Provider.pm</a></li>
93
<li class="l2"><a href="../../../modules/Template/Service.html">Service.pm</a></li>
94
<li class="l2"><a href="../../../modules/Template/Stash.html">Stash.pm</a></li>
95
<li class="l2"><a href="../../../modules/Template/Stash/index.html">Stash::*</a></li>
96
<li class="l2"><a href="../../../modules/Template/Test.html">Test.pm</a></li>
97
<li class="l2"><a href="../../../modules/Template/VMethods.html">VMethods.pm</a></li>
98
<li class="l2"><a href="../../../modules/Template/View.html">View.pm</a></li>
99
<li class="l0"><a href="../../../tools/index.html">Tools</a></li>
100
<li class="l0 last"><a href="../../../tutorial/index.html">Tutorial</a></li>
102
<div class="foot"></div>
106
<div class="section">
108
<h1 id="contents" onclick="switch_section(this)" title="Click title to show/hide section content.">Contents</h1>
109
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
113
<li class=""><a href="#SYNOPSIS">SYNOPSIS</a></li>
114
<li class=""><a href="#DESCRIPTION">DESCRIPTION</a></li>
115
<li class=""><a href="#AUTHORS">AUTHORS</a></li>
116
<li class=""><a href="#COPYRIGHT">COPYRIGHT</a></li>
117
<li class=""><a href="#SEE_ALSO">SEE ALSO</a></li>
124
<div class="section">
126
<h1 id="SYNOPSIS" onclick="switch_section(this)" title="Click title to show/hide section content.">SYNOPSIS</h1>
127
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
130
<pre>[% USE dir = Directory(dirpath) %]
132
# files returns list of regular files
133
[% FOREACH file = dir.files %]
134
[% file.name %] [% file.path %] ...
137
# dirs returns list of sub-directories
138
[% FOREACH subdir = dir.dirs %]
139
[% subdir.name %] [% subdir.path %] ...
142
# list returns both interleaved in order
143
[% FOREACH item = dir.list %]
145
Directory: [% item.name %]
147
File: [% item.name %]
151
# define a VIEW to display dirs/files
154
File: [% item.name %]
157
[% BLOCK directory %]
158
Directory: [% item.name %]
159
[% item.content(myview) | indent -%]
163
# display directory content using view
164
[% myview.print(dir) %]</pre>
167
<div class="section">
169
<h1 id="DESCRIPTION" onclick="switch_section(this)" title="Click title to show/hide section content.">DESCRIPTION</h1>
170
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
174
This Template Toolkit plugin provides a simple interface to directory
175
listings. It is derived from the <a href="../../../modules/Template/Plugin/File.html">Template::Plugin::File</a>
176
module and uses <a href="../../../modules/Template/Plugin/File.html">Template::Plugin::File</a> object instances to represent files
177
within a directory. Sub-directories within a directory are represented by
178
further <code>Template::Plugin::Directory</code> instances.
181
The constructor expects a directory name as an argument.
183
<pre>[% USE dir = Directory('/tmp') %]</pre>
185
It then provides access to the files and sub-directories contained within
188
<pre># regular files (not directories)
189
[% FOREACH file IN dir.files %]
192
<pre># directories only
193
[% FOREACH file IN dir.dirs %]
196
<pre># files and/or directories
197
[% FOREACH file IN dir.list %]
198
[% file.name %] ([% file.isdir ? 'directory' : 'file' %])
201
The plugin constructor will throw a <code>Directory</code> error if the
202
specified path does not exist, is not a directory or fails to
203
<code>stat()</code> (see <a href="../../../modules/Template/Plugin/File.html">Template::Plugin::File</a>). Otherwise, it will scan the directory
204
and create lists named '<code>files</code>' containing files,
205
'<code>dirs</code>' containing directories and '<code>list</code>'
206
containing both files and directories combined. The <code>nostat</code>
207
option can be set to disable all file/directory checks and directory
211
Each file in the directory will be represented by a <a href="../../../modules/Template/Plugin/File.html">Template::Plugin::File</a>
212
object instance, and each directory by another
213
<code>Template::Plugin::Directory</code>. If the <code>recurse</code>
214
flag is set, then those directories will contain further nested entries,
215
and so on. With the <code>recurse</code> flag unset, as it is by default,
216
then each is just a place marker for the directory and does not contain
217
any further content unless its <code>scan()</code> method is explicitly
218
called. The <code>isdir</code> flag can be tested against files and/or
219
directories, returning true if the item is a directory or false if it is
222
<pre>[% FOREACH file = dir.list %]
224
* Directory: [% file.name %]
226
* File: [% file.name %]
230
This example shows how you might walk down a directory tree, displaying
231
content as you go. With the recurse flag disabled, as is the default, we
232
need to explicitly call the <code>scan()</code> method on each directory,
233
to force it to lookup files and further sub-directories contained within.
235
<pre>[% USE dir = Directory(dirpath) %]
237
[% INCLUDE showdir %]
240
[% FOREACH file = dir.list -%]
244
[% INCLUDE showdir dir=file FILTER indent(4) -%]
251
This example is adapted (with some re-formatting for clarity) from a test
252
in <i>t/directry.t</i> which produces the following output:
265
The <code>recurse</code> flag can be set (disabled by default) to cause
266
the constructor to automatically recurse down into all sub-directories,
267
creating a new <code>Template::Plugin::Directory</code> object for each
268
one and filling it with any further content. In this case there is no
269
need to explicitly call the <code>scan()</code> method.
271
<pre>[% USE dir = Directory(dirpath, recurse=1) %]
276
[% INCLUDE showdir dir=file FILTER indent(4) -%]
280
The directory plugin also provides support for views. A view can be
281
defined as a <code>VIEW ... END</code> block and should contain
282
<code>BLOCK</code> definitions for files ('<code>file</code>') and
283
directories ('<code>directory</code>').
285
<pre>[% VIEW myview %]
290
[% BLOCK directory %]
292
[% item.content(myview) FILTER indent %]
296
The view <code>print()</code> method can then be called, passing the
297
<code>Directory</code> object as an argument.
299
<pre>[% USE dir = Directory(dirpath, recurse=1) %]
300
[% myview.print(dir) %]</pre>
302
When a directory is presented to a view, either as <code>[%
303
myview.print(dir) %]</code> or <code>[% dir.present(view) %]</code>, then
304
the <code>directory</code> <code>BLOCK</code> within the
305
<code>myview</code> <code>VIEW</code> is processed. The <code>item</code>
306
variable will be set to alias the <code>Directory</code> object.
308
<pre>[% BLOCK directory %]
310
[% item.content(myview) FILTER indent %]
313
In this example, the directory name is first printed and the
314
content(view) method is then called to present each item within the
315
directory to the view. Further directories will be mapped to the
316
<code>directory</code> block, and files will be mapped to the
317
<code>file</code> block.
320
With the recurse option disabled, as it is by default, the
321
<code>directory</code> block should explicitly call a <code>scan()</code>
324
<pre>[% VIEW myview %]
329
[% BLOCK directory %]
332
[% item.content(myview) FILTER indent %]
336
[% USE dir = Directory(dirpath) %]
337
[% myview.print(dir) %]</pre>
340
<div class="section">
342
<h1 id="AUTHORS" onclick="switch_section(this)" title="Click title to show/hide section content.">AUTHORS</h1>
343
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
347
Michael Stevens wrote the original Directory plugin on which this is
348
based. Andy Wardley split it into separate <a href="../../../modules/Template/Plugin/File.html">File</a> and <a href="../../../modules/Template/Plugin/Directory.html">Directory</a> plugins,
349
added some extra code and documentation for <code>VIEW</code> support,
350
and made a few other minor tweaks.
354
<div class="section">
356
<h1 id="COPYRIGHT" onclick="switch_section(this)" title="Click title to show/hide section content.">COPYRIGHT</h1>
357
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
361
Copyright (C) 2000-2007 Michael Stevens, Andy Wardley.
364
This module is free software; you can redistribute it and/or modify it
365
under the same terms as Perl itself.
369
<div class="section">
371
<h1 id="SEE_ALSO" onclick="switch_section(this)" title="Click title to show/hide section content.">SEE ALSO</h1>
372
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
376
<a href="../../../modules/Template/Plugin.html">Template::Plugin</a>, <a
377
href="../../../modules/Template/Plugin/File.html">Template::Plugin::File</a>, <a href="../../../modules/Template/View.html">Template::View</a>
384
<div class="pageinfo">
385
/modules/Template/Plugin/Directory.html last modified 10:54:58 31-May-2007
390
<a href="http://opensource.org/" class="osi"></a>
391
<div class="controls">
393
<a href="../../../modules/Template/Plugin/Date.html" title="Template::Plugin::Date" class="go back">Back<span class="about"><h4>Template::Plugin::Date</h4></span></a>
394
<a href="../../../modules/Template/Plugin/index.html" title="Template::Plugin::* Modules" class="go up">Up<span class="about"><h4>Template::Plugin::* Modules</h4></span></a>
395
<a href="../../../modules/Template/Plugin/Dumper.html" title="Template::Plugin::Dumper" class="go next">Next<span class="about"><h4>Template::Plugin::Dumper</h4></span></a>
398
<div class="copyright">
399
Copyright © 1996-2007 <a href="http://wardley.org/">Andy Wardley</a>. All Rights Reserved.
401
<div class="licence">
402
The <a href="http://template-toolkit.org/">Template Toolkit</a> is <a href="http://opensource.org/">Open Source</a> software.
403
You can redistribute and/or modify it under the terms of the <a href="http://www.opensource.org/licenses/gpl-license.php">GNU Public Licence</a>
404
or the <a href="http://www.opensource.org/licenses/artistic-license.php">Perl Artistic Licence</a>.
409
<li class="first"><a href="#" class="blue" onclick="set_style('Clear Blue')"></a></li>
410
<li><a href="#" class="orange" onclick="set_style('Clear Orange')"></a></li>
411
<li><a href="#" class="green" onclick="set_style('Clear Green')"></a></li>
412
<li><a href="#" class="purple" onclick="set_style('Clear Purple')"></a></li>
413
<li><a href="#" class="grey" onclick="set_style('Clear Grey')"></a></li>