~ubuntu-branches/ubuntu/quantal/libtemplate-perl/quantal

« back to all changes in this revision

Viewing changes to html/old/modules/Template/Plugin/Directory.html

  • Committer: Package Import Robot
  • Author(s): Benjamin Mako Hill
  • Date: 2012-04-08 19:06:29 UTC
  • mfrom: (0.7.1) (0.5.2) (5.1.3 sid)
  • Revision ID: package-import@ubuntu.com-20120408190629-wbcbs2ea39mex6lt
Tags: 2.24-1
* New upstream release (Closes: #664561)
* Bump Standards-Version to 3.9.3
* Changed to the short description to mention the term "Template
  Toolkit". (LP: #688836)

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
1
 
 
2
 
 
3
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Strict//EN">
 
4
<html>
 
5
  <head>
 
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">
 
12
    <!--[if IE 6]>
 
13
    <link rel="stylesheet" type="text/css" href="../../../css/ie6.css" />
 
14
    <![endif]-->
 
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">
 
19
  </head>
 
20
  <body id="body"> 
 
21
    <div id="layout">
 
22
        <div id="header">
 
23
          <a href="../../../index.html" id="logo" alt="" title="Click for the Home Page"><span class="alt">TT2 Home Page</span></a>
 
24
          <ul id="trail">
 
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>
 
29
          </ul>
 
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>
 
33
            </a>
 
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>
 
36
            </a>
 
37
          
 
38
          <div class="pager">
 
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>
 
42
          </div>
 
43
          </div>
 
44
          <h1 class="headline">Template::Plugin::Directory</h1>
 
45
          <h2 class="subhead">Plugin for generating directory listings</h1>
 
46
        
 
47
        </div>
 
48
        <div id="page">
 
49
          <div id="sidebar">
 
50
            <a href="../../../index.html" id="logo"></a>
 
51
            <div id="menu">
 
52
              <ul class="menu">
 
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>
 
101
              </ul>
 
102
              <div class="foot"></div>
 
103
            </div>
 
104
          </div>
 
105
          <div id="content">
 
106
          <div class="section">
 
107
            <div class="head">
 
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>
 
110
            </div>
 
111
            <div class="body">
 
112
              <ul class="toc">
 
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>
 
118
              
 
119
              </ul>
 
120
            </div>
 
121
          </div>
 
122
          
 
123
                <div class="pod">
 
124
            <div class="section">
 
125
              <div class="head">
 
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>
 
128
              </div>
 
129
              <div class="body">
 
130
                <pre>[% USE dir = Directory(dirpath) %]
 
131
 
 
132
# files returns list of regular files
 
133
[% FOREACH file = dir.files %]
 
134
   [% file.name %] [% file.path %] ...
 
135
[% END %]
 
136
 
 
137
# dirs returns list of sub-directories
 
138
[% FOREACH subdir = dir.dirs %]
 
139
   [% subdir.name %] [% subdir.path %] ...
 
140
[% END %]
 
141
 
 
142
# list returns both interleaved in order
 
143
[% FOREACH item = dir.list %]
 
144
   [% IF item.isdir %]
 
145
      Directory: [% item.name %]
 
146
   [% ELSE 
 
147
      File: [% item.name %]
 
148
   [% END %]
 
149
[% END %]
 
150
 
 
151
# define a VIEW to display dirs/files
 
152
[% VIEW myview %]
 
153
   [% BLOCK file %]
 
154
   File: [% item.name %]
 
155
   [% END %]
 
156
 
 
157
   [% BLOCK directory %]
 
158
   Directory: [% item.name %] 
 
159
   [% item.content(myview) | indent -%]
 
160
   [% END %]
 
161
[% END %]
 
162
 
 
163
# display directory content using view
 
164
[% myview.print(dir) %]</pre>
 
165
              </div>
 
166
            </div>
 
167
            <div class="section">
 
168
              <div class="head">
 
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>
 
171
              </div>
 
172
              <div class="body">
 
173
                <p>
 
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.
 
179
                    </p>
 
180
                    <p>
 
181
                      The constructor expects a directory name as an argument.
 
182
                    </p>
 
183
                    <pre>[% USE dir = Directory('/tmp') %]</pre>
 
184
                    <p>
 
185
                      It then provides access to the files and sub-directories contained within
 
186
                      the directory.
 
187
                    </p>
 
188
                    <pre># regular files (not directories)
 
189
[% FOREACH file IN dir.files %]
 
190
   [% file.name %]
 
191
[% END %]</pre>
 
192
                    <pre># directories only
 
193
[% FOREACH file IN dir.dirs %]
 
194
   [% file.name %]
 
195
[% END %]</pre>
 
196
                    <pre># files and/or directories
 
197
[% FOREACH file IN dir.list %]
 
198
   [% file.name %] ([% file.isdir ? 'directory' : 'file' %])
 
199
[% END %]</pre>
 
200
                    <p>
 
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
 
208
                      scanning.
 
209
                    </p>
 
210
                    <p>
 
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
 
220
                      a regular file.
 
221
                    </p>
 
222
                    <pre>[% FOREACH file = dir.list %]
 
223
   [% IF file.isdir %]
 
224
      * Directory: [% file.name %]
 
225
   [% ELSE %]
 
226
      * File: [% file.name %]
 
227
   [% END %]
 
228
[% END %]</pre>
 
229
                    <p>
 
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.
 
234
                    </p>
 
235
                    <pre>[% USE dir = Directory(dirpath) %]
 
236
* [% dir.path %]
 
237
[% INCLUDE showdir %]
 
238
 
 
239
[% BLOCK showdir -%]
 
240
  [% FOREACH file = dir.list -%]
 
241
    [% IF file.isdir -%]
 
242
    * [% file.name %]
 
243
      [% file.scan -%]
 
244
      [% INCLUDE showdir dir=file FILTER indent(4) -%]
 
245
    [% ELSE -%]
 
246
    - [% f.name %]
 
247
    [% END -%]
 
248
  [% END -%]
 
249
 [% END %]</pre>
 
250
                    <p>
 
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:
 
253
                    </p>
 
254
                    <pre>* test/dir
 
255
    - file1
 
256
    - file2
 
257
    * sub_one
 
258
        - bar
 
259
        - foo
 
260
    * sub_two
 
261
        - waz.html
 
262
        - wiz.html
 
263
    - xyzfile</pre>
 
264
                    <p>
 
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.
 
270
                    </p>
 
271
                    <pre>[% USE dir = Directory(dirpath, recurse=1) %]
 
272
   ...
 
273
 
 
274
    [% IF file.isdir -%]
 
275
    * [% file.name %]
 
276
      [% INCLUDE showdir dir=file FILTER indent(4) -%]
 
277
    [% ELSE -%]
 
278
       ...</pre>
 
279
                    <p>
 
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>').
 
284
                    </p>
 
285
                    <pre>[% VIEW myview %]
 
286
[% BLOCK file %]
 
287
   - [% item.name %]
 
288
[% END %]
 
289
 
 
290
[% BLOCK directory %]
 
291
   * [% item.name %]
 
292
     [% item.content(myview) FILTER indent %]
 
293
[% END %]
 
294
[% END %]</pre>
 
295
                    <p>
 
296
                      The view <code>print()</code> method can then be called, passing the
 
297
                      <code>Directory</code> object as an argument.
 
298
                    </p>
 
299
                    <pre>[% USE dir = Directory(dirpath, recurse=1) %]
 
300
[% myview.print(dir) %]</pre>
 
301
                    <p>
 
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.
 
307
                    </p>
 
308
                    <pre>[% BLOCK directory %]
 
309
   * [% item.name %]
 
310
     [% item.content(myview) FILTER indent %]
 
311
[% END %]</pre>
 
312
                    <p>
 
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.
 
318
                    </p>
 
319
                    <p>
 
320
                      With the recurse option disabled, as it is by default, the
 
321
                      <code>directory</code> block should explicitly call a <code>scan()</code>
 
322
                      on each directory.
 
323
                    </p>
 
324
                    <pre>[% VIEW myview %]
 
325
[% BLOCK file %]
 
326
   - [% item.name %]
 
327
[% END %]
 
328
 
 
329
[% BLOCK directory %]
 
330
   * [% item.name %]
 
331
     [% item.scan %]
 
332
     [% item.content(myview) FILTER indent %]
 
333
[% END %]
 
334
[% END %]
 
335
 
 
336
[% USE dir = Directory(dirpath) %]
 
337
[% myview.print(dir) %]</pre>
 
338
              </div>
 
339
            </div>
 
340
            <div class="section">
 
341
              <div class="head">
 
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>
 
344
              </div>
 
345
              <div class="body">
 
346
                <p>
 
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.
 
351
                    </p>
 
352
              </div>
 
353
            </div>
 
354
            <div class="section">
 
355
              <div class="head">
 
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>
 
358
              </div>
 
359
              <div class="body">
 
360
                <p>
 
361
                      Copyright (C) 2000-2007 Michael Stevens, Andy Wardley.
 
362
                    </p>
 
363
                    <p>
 
364
                      This module is free software; you can redistribute it and/or modify it
 
365
                      under the same terms as Perl itself.
 
366
                    </p>
 
367
              </div>
 
368
            </div>
 
369
            <div class="section">
 
370
              <div class="head">
 
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>
 
373
              </div>
 
374
              <div class="body">
 
375
                <p>
 
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>
 
378
                    </p>
 
379
              </div>
 
380
            </div>
 
381
            
 
382
            </div></div>
 
383
          <br class="clear" />
 
384
          <div class="pageinfo">
 
385
            /modules/Template/Plugin/Directory.html last modified 10:54:58 31-May-2007
 
386
          </div>
 
387
        </div>
 
388
        
 
389
        <div id="footer">
 
390
          <a href="http://opensource.org/" class="osi"></a>
 
391
          <div class="controls">
 
392
          <div class="pager">
 
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>
 
396
          </div>
 
397
          </div>
 
398
          <div class="copyright">
 
399
            Copyright &copy; 1996-2007 <a href="http://wardley.org/">Andy Wardley</a>.  All Rights Reserved.
 
400
          </div>
 
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>.
 
405
          </div>
 
406
        </div>
 
407
        <div id="palette">
 
408
          <ul>
 
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>
 
414
          </ul>
 
415
        </div>
 
416
    </div>  </body>
 
417
</html>