view release on metacpan or  search on metacpan

README  view on Meta::CPAN

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

README  view on Meta::CPAN

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