Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Template::Plugin::DireUseryContributed Perl DocuTemplate::Plugin::Directory(3)

NAME
       Template::Plugin::Directory - Plugin for	generating directory listings

SYNOPSIS
	   [% USE dir =	Directory(dirpath) %]

	   # files returns list	of regular files
	   [% FOREACH file = dir.files %]
	      [% file.name %] [% file.path %] ...
	   [% END %]

	   # dirs returns list of sub-directories
	   [% FOREACH subdir = dir.dirs	%]
	      [% subdir.name %]	[% subdir.path %] ...
	   [% END %]

	   # list returns both interleaved in order
	   [% FOREACH item = dir.list %]
	      [% IF item.isdir %]
		 Directory: [% item.name %]
	      [% ELSE %]
		 File: [% item.name %]
	      [% END %]
	   [% END %]

	   # define a VIEW to display dirs/files
	   [% VIEW myview %]
	      [% BLOCK file %]
	      File: [% item.name %]
	      [% END %]

	      [% BLOCK directory %]
	      Directory: [% item.name %]
	      [% item.content(myview) |	indent -%]
	      [% END %]
	   [% END %]

	   # display directory content using view
	   [% myview.print(dir)	%]

DESCRIPTION
       This Template Toolkit plugin provides a simple interface	to directory
       listings.  It is	derived	from the Template::Plugin::File	module and
       uses Template::Plugin::File object instances to represent files within
       a directory.  Sub-directories within a directory	are represented	by
       further "Template::Plugin::Directory" instances.

       The constructor expects a directory name	as an argument.

	   [% USE dir =	Directory('/tmp') %]

       It then provides	access to the files and	sub-directories	contained
       within the directory.

	   # regular files (not	directories)
	   [% FOREACH file IN dir.files	%]
	      [% file.name %]
	   [% END %]

	   # directories only
	   [% FOREACH file IN dir.dirs %]
	      [% file.name %]
	   [% END %]

	   # files and/or directories
	   [% FOREACH file IN dir.list %]
	      [% file.name %] ([% file.isdir ? 'directory' : 'file' %])
	   [% END %]

       The plugin constructor will throw a "Directory" error if	the specified
       path does not exist, is not a directory or fails	to "stat()" (see
       Template::Plugin::File).	 Otherwise, it will scan the directory and
       create lists named '"files"' containing files, '"dirs"' containing
       directories and '"list"'	containing both	files and directories
       combined.  The "nostat" option can be set to disable all	file/directory
       checks and directory scanning.

       Each file in the	directory will be represented by a
       Template::Plugin::File object instance, and each	directory by another
       "Template::Plugin::Directory".  If the "recurse"	flag is	set, then
       those directories will contain further nested entries, and so on.  With
       the "recurse" flag unset, as it is by default, then each	is just	a
       place marker for	the directory and does not contain any further content
       unless its "scan()" method is explicitly	called.	 The "isdir" flag can
       be tested against files and/or directories, returning true if the item
       is a directory or false if it is	a regular file.

	   [% FOREACH file = dir.list %]
	      [% IF file.isdir %]
		 * Directory: [% file.name %]
	      [% ELSE %]
		 * File: [% file.name %]
	      [% END %]
	   [% END %]

       This example shows how you might	walk down a directory tree, displaying
       content as you go.  With	the recurse flag disabled, as is the default,
       we need to explicitly call the "scan()" method on each directory, to
       force it	to lookup files	and further sub-directories contained within.

	   [% USE dir =	Directory(dirpath) %]
	   * [%	dir.path %]
	   [% INCLUDE showdir %]

	   [% BLOCK showdir -%]
	     [%	FOREACH	file = dir.list	-%]
	       [% IF file.isdir	-%]
	       * [% file.name %]
		 [% file.scan -%]
		 [% INCLUDE showdir dir=file FILTER indent(4) -%]
	       [% ELSE -%]
	       - [% f.name %]
	       [% END -%]
	     [%	END -%]
	    [% END %]

       This example is adapted (with some re-formatting	for clarity) from a
       test in t/directry.t which produces the following output:

	   * test/dir
	       - file1
	       - file2
	       * sub_one
		   - bar
		   - foo
	       * sub_two
		   - waz.html
		   - wiz.html
	       - xyzfile

       The "recurse" flag can be set (disabled by default) to cause the
       constructor to automatically recurse down into all sub-directories,
       creating	a new "Template::Plugin::Directory" object for each one	and
       filling it with any further content.  In	this case there	is no need to
       explicitly call the "scan()" method.

	   [% USE dir =	Directory(dirpath, recurse=1) %]
	      ...

	       [% IF file.isdir	-%]
	       * [% file.name %]
		 [% INCLUDE showdir dir=file FILTER indent(4) -%]
	       [% ELSE -%]
		  ...

       The directory plugin also provides support for views. A view can	be
       defined as a "VIEW ... END" block and should contain "BLOCK"
       definitions for files ('"file"')	and directories	('"directory"').

	   [% VIEW myview %]
	   [% BLOCK file %]
	      -	[% item.name %]
	   [% END %]

	   [% BLOCK directory %]
	      *	[% item.name %]
		[% item.content(myview)	FILTER indent %]
	   [% END %]
	   [% END %]

       The view	"print()" method can then be called, passing the "Directory"
       object as an argument.

	   [% USE dir =	Directory(dirpath, recurse=1) %]
	   [% myview.print(dir)	%]

       When a directory	is presented to	a view,	either as "[%
       myview.print(dir) %]" or	"[% dir.present(view) %]", then	the
       "directory" "BLOCK" within the "myview" "VIEW" is processed. The	"item"
       variable	will be	set to alias the "Directory" object.

	   [% BLOCK directory %]
	      *	[% item.name %]
		[% item.content(myview)	FILTER indent %]
	   [% END %]

       In this example,	the directory name is first printed and	the
       content(view) method is then called to present each item	within the
       directory to the	view.  Further directories will	be mapped to the
       "directory" block, and files will be mapped to the "file" block.

       With the	recurse	option disabled, as it is by default, the "directory"
       block should explicitly call a "scan()" on each directory.

	   [% VIEW myview %]
	   [% BLOCK file %]
	      -	[% item.name %]
	   [% END %]

	   [% BLOCK directory %]
	      *	[% item.name %]
		[% item.scan %]
		[% item.content(myview)	FILTER indent %]
	   [% END %]
	   [% END %]

	   [% USE dir =	Directory(dirpath) %]
	   [% myview.print(dir)	%]

AUTHORS
       Michael Stevens wrote the original Directory plugin on which this is
       based.  Andy Wardley split it into separate File	and Directory plugins,
       added some extra	code and documentation for "VIEW" support, and made a
       few other minor tweaks.

COPYRIGHT
       Copyright (C) 2000-2007 Michael Stevens,	Andy Wardley.

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

SEE ALSO
       Template::Plugin, Template::Plugin::File, Template::View

perl v5.32.1			  2020-07-13	Template::Plugin::Directory(3)

NAME | SYNOPSIS | DESCRIPTION | AUTHORS | COPYRIGHT | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Template::Plugin::Directory&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help