| <?xml version="1.0" encoding="UTF-8"?> |
| <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "document-v10.dtd"> |
| |
| <document> |
| <header> |
| <title>Directory Generator</title> |
| <version>1.0</version> |
| <type>Technical document</type> |
| <authors> |
| <person name="Carsten Ziegeler" email="cziegeler@apache.org"/> |
| <person name="Frank Ridderbusch" email="frank.ridderbusch@gmx.de"/> |
| <person name="John Morrison" email="morrijr@apache.org"/> |
| <person name="Jörg Heinicke" email="joerg@apache.org"/> |
| </authors> |
| <abstract>This document describes the Directory Generator of Cocoon.</abstract> |
| </header> |
| <body> |
| <s1 title="Directory Generator"> |
| <p>Generates an XML directory listing.</p> |
| <ul> |
| <li>Name: directory</li> |
| <li>Class: org.apache.cocoon.generation.DirectoryGenerator</li> |
| <li>Cacheable: yes</li> |
| </ul> |
| <p>The root node of the generated document will normally be a <code>directory</code> node. A |
| directory node can contain zero or more <code>file</code> or <code>directory</code> nodes. |
| A file node has no children. All generated elements have the namespace |
| <code>http://apache.org/cocoon/directory/2.0</code>. |
| </p> |
| <p>Each node will contain the following attributes:</p> |
| <ul> |
| <li><code>name</code>: the name of the file or directory.</li> |
| <li><code>lastModified</code>: the time the file was last modified, measured as the number |
| of milliseconds since the epoch (as in <code>java.io.File.lastModified</code>).</li> |
| <li><code>date</code>: the time the file was last modified in human-readable form.</li> |
| <li><code>size</code>: the file size (or 0 for directories).</li> |
| </ul> |
| <p>Additionally the node for the requested directory has the attributes:</p> |
| <ul> |
| <li><code>requested</code>: with the value set to <code>true</code>.</li> |
| <li><code>sort</code>: the sort order of the <code>file</code> and <code>directory</code> |
| nodes.</li> |
| <li><code>reverse</code>: determines whether reverse sort was chosen.</li> |
| </ul> |
| <p>This node needs not to be the root node as you will see later.</p> |
| </s1> |
| <s1 title="Configuration"> |
| <source><![CDATA[ |
| <map:generate type="directory" src="the/requested/directory"> |
| <map:parameter name="depth" value="2"/> |
| </map:generate> |
| ]]></source> |
| <p>The <code>src</code> attribute on the <code><map:generate/></code> must be set to the |
| directory the XML listing should be created of. This is the <em>requested</em> directory. |
| </p> |
| <p>The following parameter are all optional and can be specified in the pipeline for the |
| generate command (as seen in the example above for the parameter <code>depth</code>): |
| </p> |
| <ul> |
| <li>depth: Sets how deep Directory Generator should delve into the directory structure. If |
| set to 1 (the default), only the starting directory's immediate contents will be |
| returned.</li> |
| <li>dateFormat: Sets the format for the date attribute of each node as described in |
| <code>java.text.SimpleDateFormat</code>. If unset, the default format for the current |
| locale will be used.</li> |
| <li>refreshDelay: Sets the delay (in seconds, default is 1) between checks for updates on |
| the file system. So this option influences the caching of the directory listing.</li> |
| <li>sort: Sets the sort order in which the <code>file</code> and <code>directory</code> |
| nodes are returned. Possible values are <code>name</code>, <code>size</code>, |
| <code>time</code> and <code>directory</code> (where <code>directory</code> is the same |
| as <code>name</code>, except that directory entries are listed first). The default sort |
| order is <code>name</code>.</li> |
| <li>reverse: Reverses the sort order, defaults to <code>false</code>.</li> |
| <li>root: The root pattern. From the requested director upwards a directory is searched |
| using this pattern, that is added as root node to the document. The path from this root |
| node down to the requested directory will also be in the output. If no root pattern is |
| specified or no ancestor of the requested directory matches this pattern, the requested |
| directory will be the root in the output document.<br/> |
| The pattern is a regular expression as described in the API docs of the |
| <link href="http://jakarta.apache.org/regexp/apidocs/org/apache/regexp/RE.html"> |
| Apache RegExp project</link>.</li> |
| <li>include: The include pattern. Specifies the directories and files that should be |
| included. Also a regular expression.</li> |
| <li>exclude: The exclude pattern. Specifies the directories and files that should be |
| excluded. Also a regular expression.</li> |
| </ul> |
| </s1> |
| <s1 title="DTD"> |
| <p>XML generated by Directory Generator uses namespace |
| <code>http://apache.org/cocoon/status/2.0</code>. The DTD of XML generated by Directory |
| Generator: |
| </p> |
| <source><![CDATA[ |
| <!ELEMENT directory (directory|file)*> |
| <!ATTLIST directory |
| name CDATA #REQUIRED |
| lastModified CDATA #REQUIRED |
| date CDATA #REQUIRED |
| size CDATA #REQUIRED |
| requested CDATA #IMPLIED |
| sort CDATA #IMPLIED |
| reverse CDATA #IMPLIED> |
| |
| <!ELEMENT file #EMPTY> |
| <!ATTLIST file |
| name CDATA #REQUIRED |
| lastModified CDATA #REQUIRED |
| date CDATA #REQUIRED |
| size CDATA #REQUIRED> |
| ]]></source> |
| </s1> |
| <s1 title="Example"> |
| <p>The current Directory Generator may generate following xml:</p> |
| <source><![CDATA[ |
| <dir:directory xmlns:dir="http://apache.org/cocoon/directory/2.0" |
| name="stylesheets" lastModified="1056668768203" date="27.06.03 01:06" size="0" |
| requested="true" sort="name" reverse="false"> |
| <dir:directory name="sites" lastModified="1056668768203" date="27.06.03 01:06" size="0"/> |
| <dir:file name="dynamic-page2html.xsl" lastModified="1056668768203" date="27.06.03 01:06" size="4321"/> |
| <dir:file name="simple-xml2html.xslt" lastModified="1056668768203" date="27.06.03 01:06" size="1234"/> |
| </dir:directory> |
| ]]></source> |
| </s1> |
| </body> |
| </document> |
