NAME

HTML::EP::Explorer - Web driven browsing of a filesystem

SYNOPSIS

<ep-explorer-browse>

DESCRIPTION

This application was developed for DHW, a german company that wanted to give its users access to files stored on a file server via certain applications defined by an administrator. (See

http://www.dhw.de/

if you are interested in the sponsor.) The rough idea is as follows:

The users are presented a view similar to that of the Windows Explorer or an FTP servers directory listing. On the top they have a list of so-called actions. The users may select one or more files and then execute an action on them.

INSTALLATION

The system is based on my embedded HTML system HTML::EP. It should be available at the same place where you found this file, or at any CPAN mirror, in particular

ftp://ftp.funet.fi/pub/languages/perl/CPAN/authors/id/JWIED/

The installation of HTML::EP is described in detail in the README, I won't explain it here. However, in short it is just as installing HTML::EP::Explorer: Assumed you have a file

HTML-EP-Explorer-0.1003.tar.gz

then you have to execute the following steps:

gzip -cd HTML-EP-Explorer-0.1003.tar.gz | tar xf -
perl Makefile.PL
make		# You will be prompted some questions here
make test
make install

Installation will in particular create a file

lib/HTML/EP/Explorer/Config.pm

which will contain your answers to the following questions:

```
Install HTML files?
```
If you say y here (the default), the installation script will install some HTML files at a location choosed by you. Usually you will say yes, because the system is pretty useless without it's associated HTML files. However, if you already did install the system and modified the HTML files you probably want to avoid overriding them. In that case say n.
```
Directory for installing HTML files?
```
If you requested installing the HTML files, you have to choose a location. By default the program suggests
```
F</home/httpd/html/explorer>
```
which is fine on a Red Hat Linux box. Users of other systems will modify this to some path below your your web servers root directory.
```
Directory for installing CGI binaries?
```
If HTML files are installed, you must install some CGI binaries too. This question allows you to select an installation path, by default the subdirectory cgi within the directory for installing HTML files.

Note that you need to configure the httpd so that it treats this directory as a CGI directory. For example Apache users may add the following to srm.conf:
```
ScriptAlias /home/httpd/html/explorer/cgi
```
```
UID the httpd is running as?
```
The explorer scripts need write access to some files, in particular the configuration created by the site administrator. To enable write access, these files are owned by the Unix user you enter here, by default the user nobody.

In most cases this will be the same user that your httpd is running as, but it might be different, for example if your Apache is using the suexec feature. Contact your webmaster for details.

If you didn't already do so, configure your web server for feeding files with extension .ep into the CGI binary ep.cgi or into the mod_perl module Apache::EP. The README of HTML::EP tells you how. See HTML::EP(3).

That's it! Assuming the directory /home/httpd/html/explorer is reachable as /explorer in your browser, point it to

http://localhost/explorer/

You should now see a directory listing. If so, proceed to CONFIGURATION.

CONFIGURATION

Besides the questions you already answered when installing the explorer, the system is configurable via any Web browser. Assuming the Explorer is reachable below http://localhost/explorer/, Point your browser to

http://localhost/explorer/admin/prefs.ep

Security considerations

The first thing you probably notice is that you need not supply a password for accessing this page. This should be changed. A typical configuration requests that only the user root can visit this page. For example, with Apache, you could insert the following into your httpd.conf:

<Location /explorer/admin>
  AuthUserFile /etc/passwd
  AuthName "Explorer Administration"
  AuthTyoe basic
  require user root
</Location>

(Of course one can discuss whether this is a secure thing, as it could allow deducing the root password by using some sort of crack mechanism. On the systems where I use it there ary typically lots of other possibilities for doing the same ... :-)

E-Mail address of the administrator

From time to time the system will use this address for sending emails to you.

Actions

This is the explorers heart. Actions are merely shell scripts, to which the files will be fed, that your users have selected.

To create an action, fill out the following fields:

Name

This is some short text that your users will see on the web frontend. For example, it could be Printing on the LaserJet.

Icon

This (optional) entry means that the explorer will use the named image file to display it instead of the name above. For example, this could be a small gif with the word LaserJet on it.

You must supply an URL here. If you are using Apache, then a lot of nice icons are accessible in your httpd's icons directory. See the README file.

Script

This is a shell command that the explorer will execute for performing the action. The command may use the variables file (the filename) or user (the users name). For example, one could use

lpr -Plaserjet -U $user $file

The user name is deduced by looking at the environment variable REMOTE_USER: If your directory /explorer is password protected, then this variable will contain the users name as set by the web server. If the variable is empty, then the user name anonymous is used.

Don't try to protect the user or file name with quotes: The Explorer will use Perl's quotemeta function to secure these variables. For example, if your tricky users supply a file name

`rm -rf /`

then the Explorer will run the command

lpr -Plaserjet -U anonymous \`rm\ -rf \/\`

which is safe. See perlsec for more details on security considerations with Perl.

If your script command is able to process multiple files with one command, then you may prefer

lpr -Plaserjet -U $user $files

The Explorer will detect that you are using $files and not $file and will run a single command.

Status script

Similar to the action script, this one will try to guess the current status. A typical command might be

lpq -Plaserjet -U $user

The status script is suggested to produce output looking like that of lpq.

Logfile

Path of a logfile to view

Note that you see only one (empty) action at the start: If you fill it out and hit Save settings, then a second (empty) row will appear automatically. To be precise, you will always have one empty row at the bottom.

Actions can be removed by just blanking out the name and hitting Save settings.

Status cache

To save CPU time, you might like to make use of the Status cache. By setting this variable to a certain number of seconds, say 300, the Explorer will not always run the status script. Instead it will create a cache file in the subdirectory status and save the status script's output there. When the status is queried the next time, this cache file will be used, unless the cache file's modification time is more that the given number of seconds in the past. In that case a new cache file will be created by running the status script again.

Initial directories

In most cases you are not interested in giving your users access to the whole directory tree. For example, if your users use a Samba server to place files on your machine, than the Explorer should probably restrict your users to the Samba servers files.

To create an initial directory, fill out the following fields:

Name: This is a verbose name that your users will see instead of the directory path. For example, it could be a Samba share name.
Directory: The real directory path.

By default your users will still be able to access files outside of the initial directories and these paths are only suggestions. This can be changed by disabling Allow access to other directories.

Again, you will always see one empty directory at the bottom of the list. To create a new directory just fill this out and hit Save Settings. Wipe out the name for removing an existing directory.

File types

People are used to see only certain files when selecting them for actions. For example, when opening an existing document in Microsoft Word, then you will by default see only files with extension .doc.

A file type can be created by filling out the following fields:

Name

This is a description of the file type, that your users will see. For example, it could be

PostScript files (*.ps)

All Files (*)

Icon

This is an (optional) icon to use for showing the file type. For example, it could be

/icons/ps.gif

/icons/unknown.gif

(Note that these are indeed meaningful settings with any default Apache installation, because Apache has a lot of icons included. See the file icons/README from the Apache distribution.)

Regular Expression

This is a Perl Regular Expression which files must match in order to be of this type. For example it could be

\.ps$
\.pdf$
\.(?:ps|pdf)$
.*

for PostScript files, PDF files, PostScript or PDF files or all files. See perlre(3) for details on Perl's regular expressions.

MODIFYING THE EXPLORER

When modifying the explorer, you should know about the following methods:

Initializing the Explorer

Probably any HTML page using the explorer system should contain the following:

<ep-package name=HTML::EP::Explorer accept="de,en">
<ep-explorer-init noprefs=0>

The _ep_explorer_init method is initializing the users cookie. First it verifies, whether the user already has an explorer cookie set. If not, the user will be redirected to the prefs.ep page, unless the attribute noprefs is set. This page will allow him to fix his personal settings and return to the calling page.

The explorer class is a subclass of both HTML::EP::Locale and HTML::EP::Session. That means that the locale settings are still valid in the ep-package call (in particular the accept attribute that tells this page is ready for either german, aka de, or english). Likewise the attributes of ep-session are valid in the ep-explorer-init call. HTML::EP(3). HTML::EP::Session(3).

Reading and/or writing the admin settings

Within admin/prefs.ep and some other pages, you find the following call:

<ep-explorer-config file="config.pm" maysafe=0>

which read the admin settings from an external file, by default config.pm. The settings will instead be read from the CGI input and saved into the same file, if the CGI variable save and the attribute maysafe are true. (The latter should happen within the amdin dirctory only.)

The method will set the following EP variables:

$config$

The config hash ref, as read from the file config.pm.

$actions$

The list of actions. Shortcut for $config->actions$. An action looks like

{ 'name' => 'Print to lp',
  'icon' => '/icons/lp.gif', # May be undef
  'script' => 'lpr -Plp -U $user $file'
}

$directories$

The list of directories. Shortcut for $self->{'config'}->{'directories'}. A directory looks like

{ 'name' => 'Root directory',
  'dir' => '/'
}

$filetypes$

The list of file types. Shortcut for $self->{'config'}->{'filetypes'}. A file type looks like

{ 'name' => 'PostScript files (*.ps)'
  'icon' => '/icons/ps.gif', # May be undef
  're' => '\.ps$'
}

$num_directories$

The number of elements in $self->{'directories'}. May be 0.

Reading and/or writing the users settings

The users settings can be read and/or written by calling

<ep-explorer-prefs>

This will call _ep_explorer_init internally, by setting the noprefs attribute to true. If either of the CGI variables save or save_and_return is set, it will read the users new settings from the CGI environment by running $self->ReadPrefs and store the session (that is, return a cookie) by calling ep-session-store.

If the current oage is called from another page (that is, the CGI variable return_to is set to the calling page) and the CGI variable save_and_return is set, then the calling page is included with ep-include.

Setting the Explorers current directory

The method

<ep-explorer-basedir>

will read the users current directory from the session or CGI variable basedir. The current directory will be compared against the list of initial directories and the following EP variables will be set:

$basedir$

The selected current directory. If this is different from $session-basedir> then the latter will be modified and $modified$ will be set.

$in_top_dir$

True, if the current directory is one of the initial directories or in /, False otherwise.

$in_base_dir$

If the current directory is below one of the initial directories, then this variable will contain the associated element from the directory list. That is $in_base_dir->name$ is set to the name of this initial directory and $in_base_dir->dir$ the path.

Otherwise the variable is set to undef. If this is the case and the administrator has set "Allow access outside initial directories" to True, then a system error is triggered.

$display_dir$

If $in_base_dir$ is set, then this variable is set to the current directories path, relative to the directory from $in_base_dir$. For example, if you are in /usr/local/bin and the initial directory is /usr/local, then the display directory is /bin.

Setting the sorting mode

The method

<ep-explorer-sortby>

attempts to guess the requested sorting mode from the CGI or session variable sortby. The guessed mode (by default name) will be stored in $sortby$. If this is different from $session->sortby$, then the latter becomes set to the new value and $modified$ is set.

Setting the file type

The method

<ep-explorer-filetype>

attempts to guess the file type that the user requests (That is, whether the user wants to see only certain files.) by looking at the CGI or session variable filetype. By default the first file type from the list $filetypes$ is choosen. If no list is set, then all files become selected.

If a file type was choosen, the file type is stored in $filetype$. and $filetype->selected$ is set to true. (Note, you must not call ep-explorer-config later!) If $filetype->name$ is different from $session->filetype$, then the latter is modified and $modified$ is set to true.

Creating the directory listing

The listing becomes created with

<ep-set var=dir_template>
  <tr><td><!-- HTML code for listing a directory
  		 You may assume that $l$ is an instance of
               HTML::EP::Explorer::Dir.
            -->
      </td></tr>
</ep-set>
<ep-set var=file_template>
  <tr><td><!-- HTML code for listing a file
  		 You may assume that $l$ is an instance of
               HTML::EP::Explorer::File.
            -->
      </td></tr>
</ep-set>
<ep-explorer-browse basedir="$env->DOCUMENT_ROOT$" item=l>

The method is calling ep-explorer-basedir, ep-explorer-filetype and ep-explorer-sortby internally. Then a directory listing is created and sorted, according to these methods results.

Finally, HTML code is generated for any item in the list by using the templates $dir_template$ or $file_template$, depending on the items type.

Performing an action

The method

<p>I will execute the following command:</p>
<pre>
  <ep-explorer-action action="myaction" file="myfile" execute=0>
</pre>
Here you can see the output:
<pre>
  <ep-explorer-action action="myaction" file="myfile" execute=1>
</pre>

performs an action, as requested by the user. The method is reading an action name from the CGI variable faction or the attribute faction. The corresponding action, if any, is stored in $action$. If no action is found, a system error is triggered.

Then the method is looking for either of the CGI variable files or the attribute files. If this is set, it is treated as a blank separated list of file names. (Tab, Carriage return etc. are counting as blanks.)

Otherwise the method expects a single file name in the CGI variable file or the attribute file. If neither is set, a system error is triggered.

If the attribute execute is set to false, then no commands are executed. Instead the method returns the commands being executed. Otherwise the command is executed and the output returned.

AUTHOR AND COPYRIGHT

This module is

Copyright (C) 1998-1999	Jochen Wiedmann
                      	Am Eisteich 9
                      	72555 Metzingen
                      	Germany

                      	Phone: +49 7123 14887
                      	Email: joe@ispsoft.de

You may distribute this module under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

INSTALLATION

CONFIGURATION

Security considerations

E-Mail address of the administrator

Actions

Status cache

Initial directories

File types

MODIFYING THE EXPLORER

Initializing the Explorer

Reading and/or writing the admin settings

Reading and/or writing the users settings

Setting the Explorers current directory

Setting the sorting mode

Setting the file type

Creating the directory listing

Performing an action

AUTHOR AND COPYRIGHT

SEE ALSO

Module Install Instructions