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.

    *       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 the
    HTML::EP(3) manpage.

    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 the
    CONFIGURATION manpage.

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 the perlsec manpage 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.

    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*.

  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)

        or

          All Files (*)

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

          /icons/ps.gif

        or

          /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 the perlre(3) manpage 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. the HTML::EP(3) manpage. the HTML::EP::Session(3) manpage.

  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

    All rights reserved.

    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.

SEE ALSO
    the HTML::EP(3) manpage, the HTML::EP::Session(3) manpage

