====== Directory Listing Syntax PlugIn ======

---- plugin ----
description: Show content of server directories.
author     : Natalia Pujol
email      : naty@eslamejor.com
type       : syntax
lastupdate : 2005-09-20
compatible : 
depends    : 
conflicts  : 
similar    : dir
tags       : directory, ls, dir
----


Use it carefully, you can use it at your own risk. 

^--- Be aware that if you have anonymous editable pages users can show local directory contents!!! ---^

===== Usage =====

To view "c:\repository" directory:
  <dirlisting "c:\repository">

...and with directory name like a title: 
  <dirlisting title "c:\repository">

===== Installation =====

  - Create a ''dokuwiki/lib/plugins/dirlisting'' directory in DokuWiki's plugin directory.
  - Copy the [[#Plugin Source|plugin source]] below to a file called ''syntax.php'' in the directory.
  - Make sure both the new directory and the new file are readable by the web-server e.g.

===== Plugin Source =====

Copy this PHP source to DokuWiki's plugin directory as described [[#installation|above]]:

<code php>
<?php
/**
 * Plugin dirlisting: Inserts content of selected directory.
 * v1.0
 *
 * Usage: <dirlisting "c:\mydir\">
 *        <dirlisting title "c:\mydir\">
 * 
 * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
 * @author     Natalia Pujol <naty@eslamejor.com>
 */
 
if(!defined('DOKU_INC')) define('DOKU_INC',realpath(dirname(__FILE__).'/../../').'/');
if(!defined('DOKU_PLUGIN')) define('DOKU_PLUGIN',DOKU_INC.'lib/plugins/');
require_once(DOKU_PLUGIN.'syntax.php');
 
/**
 * All DokuWiki plugins to extend the parser/rendering mechanism
 * need to inherit from this class
 */
class syntax_plugin_dirlisting extends DokuWiki_Syntax_Plugin {

	function getInfo() {
		return array(
			'author' => 'Natalia Pujol',
			'email' => 'naty@eslamejor.com',
			'date' => '2005-09-20',
			'name' => 'Directory Listing Plugin',
			'desc' => 'Insert content of selected directory',
			'url' =>  'http://www.dokuwiki.org/plugin:dirlisting');
	} // getInfo()

	function connectTo($aMode) {
		$this->Lexer->addSpecialPattern('<dirlisting.*?>', $aMode, 'plugin_dirlisting');
	} // connectTo()
 
	function getSort() {
		return 7;
	} // getSort()
 
	function getType() {
		return 'substition';
	} // getType()
 
	function handle($match, $state, $pos, &$handler) {
		if ($state = DOKU_LEXER_SPECIAL) {
			if (eregi("<dirlisting[\t ]+(title[\t ]+){0,1}\"(.+)\"[\t ]*>", $match, $out))
				return array($state, array($out[2],$out[1]));
		}
		return array();
	} // handle()
 
	function render($aFormat, &$aRenderer, $aData) {
		if ('xhtml' != $aFormat) {
			return FALSE;
		} // if
		list($state, $match) = $aData;
		if (DOKU_LEXER_SPECIAL == $state) {
			$aRenderer->doc .= "<pre>";
			// Disrectory exists?
			if (is_dir($match[0])) { 
				// Title
				if (trim($match[1])=="title")
					$aRenderer->doc .= '<b>'.$match[0].'</b><br />';
				$aRenderer->doc .= '<table cellspacing="0" cellpadding="0" border="0">';
				if ($dh = opendir($match[0])) { 
					while (($file = readdir($dh)) !== false) {
						$filename = $match[0]."/".$file;
						$size = filesize($filename);
						if ($size>=1073741824) {
							$size /= 1073741824;
							$unit = "Gb";
						} elseif ($size>=1048576) {
							$size /= 1048576;
							$unit = "Mb";
						} elseif ($size>=1024) {
							$size /= 1024;
							$unit = "Kb";
						} else {
							$unit = "bytes";
						}
						$aRenderer->doc .= "<tr><td>".$file;
						$aRenderer->doc .= "</td><td align=\"right\">&nbsp;".(is_dir($filename)?"</td><td>&lt;DIR&gt;":number_format($size,($unit=="bytes"?0:1),".","")."<td>&nbsp;$unit</td>");
						$aRenderer->doc .= "</td></tr>";
					} 
					closedir($dh);
				} 
				$aRenderer->doc .= "</table>";
			} else {
				$aRenderer->doc .= "<br />[Directory not exists!!]<br />";
			}
			$aRenderer->doc .= "</pre>";
		} // if
		return TRUE;
	} // render()
 
  //@}
} // class syntax_plugin_dirlisting
?>
</code>


//[[naty@eslamejor.com|Natalia Pujol]] 2005-09-21//

===== Discussion =====
Hints, comments, suggestions ...


Some notes:
  - **Security**. I'd strongly suggest to limit the accepted/processed file space to DokuWiki's 'pages' directory (and sub-directories). I don't think it's acceptable to //any// webmaster to allow for showing arbitrary parts of the server's disks.
  - The (X)HTML code produced is **invalid**. There must not be any markup inside PRE tags (except some inline like STRONG etc.). So either remove the ''PRE'' tags and just use the ''TABLE'' markup, or -- better -- remove the ''TABLE/TR/TD'' stuff thus creating a table by indentions (i.e. ''TABs'' etc.) which not only saves processing time at both the server's and the user's machine but as well shows the dir-listing in a easyly recognized preformatted format.
  - You could move most parts of the actual processing from the ''render()'' to the ''handle()'' method the latter returning an array holding the relevant data while the former justs performs the markup.
  - Priority: I can't see a reason for a priority of 7 returned by ''getsort()''. I'd suggest using a value between 300 - 500.

//[[support@mwat.de|Matthias Watermann]] 2005-09-24//


\\