source: trunk/doc/src/docbook/userdoc/file_system.xml @ 5362

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC 
    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN" 
    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
<!--
  $Id: file_system.xml 5362 2010-06-16 12:28:36Z nicklas $
  
  Copyright (C) 2007 Peter Johansson, Nicklas Nordborg, Martin Svensson
  
  This file is part of BASE - BioArray Software Environment.
  Available at http://base.thep.lu.se/
  
  BASE is free software; you can redistribute it and/or
  modify it under the terms of the GNU General Public License
  as published by the Free Software Foundation; either version 3
  of the License, or (at your option) any later version.
  
  BASE is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.
  
  You should have received a copy of the GNU General Public License
  along with BASE. If not, see <http://www.gnu.org/licenses/>.
-->

<chapter id="file_system">
  <?dbhtml dir="filesystem"?>
  <title>File management</title>
  <sect1 id="file_system.system">
    <title>File system</title>
    <para>
      Files in BASE are managed from the page at
      <menuchoice>
        <guimenu>View</guimenu>
        <guimenuitem>Files</guimenuitem>
      </menuchoice>. The basic layout on the page is the same as for all the other list pages 
      in BASE but
      there are some differences e.g. there is a navigation tree to the left, used to browse
      the directory structure, and there are some buttons in the toolbar, that are special for
      files and directories. The figure below is a representation of the files and
      directories-page and is followed with a short description to some of the special
      functions.
    </para>
    <figure id="file.system.figures.filepage">
      <title>The file page</title>
      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/filepage.png" format="PNG" 
            scalefit="1" width="100%" />
          </imageobject>
        </mediaobject>
      </screenshot>
    </figure>
    <variablelist>
      <varlistentry>
        <term>
          <interface>1. Home directory for current user</interface>
        </term>
        <listitem>
          <para>
            This is the logged in user's home directory with sub directories. It is
            visible if the current user has a home directory and is then always located at
            the top of the navigation tree. More about this can be read in
            <xref linkend="file_system.system.browse.tree.home" />.
            Click on a directory to display it's contents to the right
            or click on the plus sign to expand the directory and view the
            sub directories (no plus sign = no sub directories).
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <interface>2. Other users</interface>
        </term>
        <listitem>
          <para>
            The other users' home directories that the current user has permission
            to read are listed here, including his/her own.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <interface>3. Button toolbar</interface>
        </term>
        <listitem>
          <para>
            The button toolbar contains functions that are relevent for the 
            navigation tree. Use the <guibutton>Refresh</guibutton> button
            to update the directory tree, for example, after creating a new
            subdirectory. Use the <guibutton>Search</guibutton> button to
            search for files and directories no matter where they are located.
            The search form is displayed to the right and is the same as the
            usual file and directory listing, except that it will not show
            any files if there is no filter.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <interface>4. Current directory</interface>
        </term>
        <listitem>
          <para>Shows the full BASE path to current directory.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <interface>5. View a file's contents</interface>
        </term>
        <listitem>
          <para>
            A click on this icon will open the file's contents in a new window. If the
            browser does not has support to view the file there will be a dialog window
            to download the file instead.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <interface>6. Download file</interface>
        </term>
        <listitem>
          <para>
            Download the file to a local computer with this icon. The download will
            start in a new dialog window.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <interface>7. Re-upload a file</interface>
        </term>
        <listitem>
          <para>
            This icon is only visible for those files that have been moved offline and
            it can be used to re-upload the file to the BASE. Start to
            upload the file to the same position by clicking on the icon.
          </para>
          
          <note>
            <title>Replace an existing file</title>
            <para>
              It is possible to re-upload file that are on-line, but this
              has to be done from the single-item view.
            </para>
          </note>
        </listitem>
      </varlistentry>
    </variablelist>

    <sect2 id="file_system.system.browse">
      <title>Browse the file system</title>
      <para>
        Browsing the BASE file system is done from the navigation bar by clicking on a
        directory in the tree to view it's contents. Both sub directories and files in the
        selected directory are showed. A directory with sub directories can be expand with a
        click on the plus-sign.
      </para>
      <note>
        <title>Browse a directory</title>
        <para>
          A directory can only be open from the navigation tree and never from the list. A
          click on a directory's name in the list will open the directory's edit window.
        </para>
      </note>
      <sect3 id="file_system.system.browse.tree">
        <title>Navigation tree</title>
        <para>
          The navigation tree contains of folders/directories that the logged in user has
          permission to read. At the top is the current user's home directory and under it
          is a folder with all accessible home directories.
        </para>
        <para>
          The tree can be updated with the refresh-button at the bottom of the panel (the
          tree is not self-refreshing).
        </para>
        <sect4 id="file_system.system.browse.tree.home">
          <title>Home directory - 'My home'</title>
          <para>
            To make it easier for the logged in user to find his/her directory without
            having to scroll through the whole list of home directories, his or hers
            home directory is located at the top of the navigation tree under the
            <interface>My home</interface>
            folder.
          </para>
          <note>
            <title>No home directory</title>
            <para>
              Not all users have a home directory connected to their accounts. If
              <interface>My home</interface>
              is missing, it most certainly depends on that the current user account
              have not got a home directory. Home directories are managed by the 
              administrator of the BASE server.
            </para>
          </note>
        </sect4>
      </sect3>
    </sect2>
    <sect2 id="file_system.system.quota">
      <title>Disk space quota</title>
      <para>
        Normally, a user is assigned limited disk space for files. 
        More information about how much quota the current account has and how much of it
        that is occupied can be found at the account's home page, described in
        <xref linkend="webclient.intro.homepage" />.
      </para>
      
      <para>
        See <xref linkend="user_administration.quota" /> for more information about 
        the quota system.
      </para>
    </sect2>
  </sect1>

  <sect1 id="file_system.handling">
    <title>Handling files</title>
    
    <sect2 id="file_system.handling.upload">
      <title>Upload a new file</title>
      <para>
        Uploading a file is started by clicking on
        <guibutton>Upload file&hellip;</guibutton>
        in the toolbar. The uploaded file will be placed in current directory.
      </para>
      
      <figure id="file_system.figures.upload">
        <title>Upload new file</title>
        <screenshot>
          <mediaobject>
            <imageobject><imagedata 
              fileref="figures/upload_file.png" format="PNG"
              /></imageobject>
          </mediaobject>
        </screenshot>
      </figure>
      
      <helptext external_id="file.upload" title="Upload a file">
        <para>
          <variablelist>
            <varlistentry>
              <term>
                <guilabel>Directory</guilabel>
              </term>
              <listitem>
                <para>
                  Shows the current directory, where the file will be uploaded.
                  This property cannot be changed and is only for information.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>File</guilabel>
              </term>
              <listitem>
                <para>
                  This field is required and needs to have a valid file path for
                  the local computer before the upload is started. Use
                  <guibutton>Browse&hellip;</guibutton>
                  to choose which file to upload.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Replace existing</guilabel>
              </term>
              <listitem>
                <para>
                  Tick this checkbox if you want to overwrite an existing file
                  that has the same name as the one you are going to upload.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Write protected</guilabel>
              </term>
              <listitem>
                <para>
                  Mark this checkbox if you want the file to be write 
                  protected. A write protected file cannot be deleted,
                  moved offline or replaced with another file. It is
                  still possible to change other metadata, such as
                  the name, description, file type, MIME type, etc.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Store compressed</guilabel>
              </term>
              <listitem>
                <para>
                  You can select if you want BASE to store your file in a 
                  compressed format or in it's normal format. Compressing
                  the file may save a lot of disk space and it also uses
                  less quota. There are three options:
                  <itemizedlist>
                  <listitem>
                    <para>
                      <guilabel>auto</guilabel>: Let BASE automatically
                      decide if the file should be compressed or not. The file
                      is compressed if (1): it is uploaded to a directory that
                      has the <emphasis>compress files</emphasis> flag set
                      or (2): if the matching MIME type has the 
                      <emphasis>compress files</emphasis> flag set.
                    </para>
                  </listitem>
                  <listitem>
                    <para>
                      <guilabel>yes</guilabel>: Store the file in a compressed
                      format.
                    </para>
                  </listitem>
                  <listitem>
                    <para>
                      <guilabel>no</guilabel>: Store the file in it's normal format.
                    </para>
                  </listitem>
                  </itemizedlist>
                  
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Type</guilabel>
              </term>
              <listitem>
                <para>
                  This is the file-type that the uploaded file should get. 
                  <nohelp>The
                  file-types to choose between from the drop-down list are
                  described in
                  <xref linkend="file_system.filetypes" />.</nohelp>
                  Select
                  <userinput>- none -</userinput>
                  if the file should not be associated with any file type.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Description</guilabel>
              </term>
              <listitem>
                <para>
                  A description about the uploaded file can be put into this text
                  area. Use the magnifying glass to edit the text in a pop-up
                  window with a larger text area.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Max transfer rate</guilabel>
              </term>
              <listitem>
                <para>
                  This shows the maximum transfer rate that the upload will
                  approximately reach. The transfer rate is set by the
                  server admin and cannot be changed.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Compressed file</guilabel>
              </term>
              <listitem>
                <para>
                  These settings are only active if you select
                  a compressed file format that BASE knows how to
                  unpack. BASE ships with support for some of the most common
                  compressed file formats, such as zip and tar,
                  but this can be extended by the use of plug-ins. 
                  <nohelp>See <xref linkend="plugin_developer.other.unpacker" 
                    /> for more information.</nohelp>
                    
                  <itemizedlist>
                    <listitem>
                      <para>
                        <guilabel>Unpack file</guilabel>:
                        Mark this checkbox if the compressed file should
                        be unpacked after it had been uploaded. The
                        files will be unpacked with the same sub-directory
                        structure as in the compressed file.
                      </para>
                    </listitem>
                    
                    <listitem>
                      <para>
                        <guilabel>Overwrite existing files</guilabel>:
                        Mark this checkbox if the unpacking is allowed
                        to overwrite existing files.
                      </para>
                    </listitem>
                    <listitem>
                      <para>
                        <guilabel>Keep the compressed file</guilabel>:
                        Mark this checkbox if you want to keep the
                        compressed file after upload. Otherwise, only
                        the unpacked files are kept.
                      </para>
                    </listitem>
                  </itemizedlist>
                </para>
              </listitem>
            </varlistentry>
          </variablelist>
        </para>
        <para>
          Finish the configuration by clicking on either
          <guibutton>Upload</guibutton>, which will start uploading the selected file, or
          &gbCancel; to abort the upload procedure.
        </para>
      </helptext>
      
      <sect3 id="file_system.handling.actions.reupload">
        <title>Replace an existing file</title>
        <para>
          It is possible to replace an existing file. This is done by clicking
          on the <guilabel>replace</guilabel> link on the single-item view
          for the file you want to replace. If the file has been moved offline,
          you can also use the icon
          in the actions-column, see number 7 in
          <xref linkend="file.system.figures.filepage" />.
          The procedure to upload the file is the same as when uploading a new file,
          except that compressed files cannot be unpacked. There is also an
          extra option, <guilabel>Validate MD5</guilabel>, that tells BASE to 
          check that the file is the same as the one it is replacing. This option
          is useful when you are re-uploading a file that has been moved offline
          and want to be certain that it is the same file as the original.
        </para>
        
        <para>
          You cannot replace a file which has been marked as 
          <emphasis>write protected</emphasis>.
        </para>
      </sect3>
      
    </sect2>
    
    <sect2 id="file_system.handling.external">
      <title>External files</title>
      <para>
      Files doesn't have to be stored on the BASE server. It is possible to register
      an external file by giving the URL to it. In most cases, BASE will be able to 
      use the external file in the same way as a file that has been uploaded to the
      BASE server. To create an external file reference, use the 
      <guibutton>New URL...</guibutton> button.
      </para>
      
      <figure id="file_system.figures.external">
        <title>Create external file</title>
        <screenshot>
          <mediaobject>
            <imageobject><imagedata 
              fileref="figures/external_file.png" format="PNG"
              /></imageobject>
          </mediaobject>
        </screenshot>
      </figure>
      
      <para>
        The dialog is more or less the same as the <guilabel>Edit file</guilabel> dialog,
        but has additional fields for the <guilabel>URL</guilabel> and an optional 
        <guilabel>File server</guilabel>.
      </para>
      
      <helptext external_id="file.external" title="External file properties">
        <variablelist>
          <varlistentry>
            <term>
              <guilabel>URL</guilabel>
            </term>
            <listitem>
              <para>
                The full URL to the referenced file. Currently, BASE
                only supports <emphasis>http</emphasis> or 
                <emphasis>https</emphasis> URLs.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <guilabel>Load metadata</guilabel>
            </term>
            <listitem>
              <para>
                Check this box if you want BASE to try to load metadata such
                as MIME type, size, last modification date etc. for the file.
                This will also verify that the file actually exists.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <guilabel>Server</guilabel>
            </term>
            <listitem>
              <para>
                Select a file server for this file. This is optional, but is
                needed to access password-protected files or for some https 
                connections.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
        <seeother>
          <other external_id="fileserver.edit">File servers</other>
          <other external_id="file.edit">Other file properties</other>
        </seeother>
      </helptext>
      
      <sect3 id="file_system.handling.fileservers">
        <title>File servers</title>
      
        <helptext external_id="fileserver.edit" title="Edit file server">
          <para>
            File server are used for external files that are password
            protected and for files that are using the https protocol and
            require certificates to connect to the server.
          </para>
          <variablelist>
          <varlistentry>
            <term>
              <guilabel>Name</guilabel>
            </term>
            <listitem>
              <para>
                The name of the file server.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <guilabel>Username/password</guilabel>
            </term>
            <listitem>
              <para>
                If the file server requires authorization to access the files
                you should add a username and password. This will be used by
                BASE to access the files. Currently, BASE supports 
                <emphasis>Basic</emphasis> and <emphasis>Digest</emphasis>
                authentication.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <guilabel>Description</guilabel>
            </term>
            <listitem>
              <para>
                Enter a description of the file server.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <guilabel>Certificates</guilabel>
            </term>
            <listitem>
              <para>
                On this tab you may specify server and client certificates. A 
                <guilabel>server certificate</guilabel> may be needed to access files with the https 
                protocol on servers that use certificates that can't automatically be trusted,
                for example, a self-signed certificate. The server certificate is uploaded
                as a file and must be a X.509 certificate in either binary or base64-encoded DER format.
              </para>
              <para>
                A <guilabel>client certificate</guilabel> may be needed to access files with the https 
                protocol on servers that require that clients authenticate themselves with a certificate.
                The certificate is typically issued by the owner of the server and may be
                password-protected. The client certificate is uploaded as a file and must be in
                PKCS #12 format.
              </para>
              <para>
                Use the <guilabel>Remove existing...</guilabel> checkboxes to remove previously
                uploaded certificates. Leave everything empty to keep things as they are.
              </para>
            </listitem>
          </varlistentry>
          </variablelist>
        <seeother>
          <other external_id="file.external">External files</other>
        </seeother>
        </helptext>
      
      </sect3>
      
    </sect2>
    
    <sect2 id="file_system.handling.edit">
      <title>Edit a file</title>
      <para>
        The edit window to set a file's property in can either be open with
        &gbEdit;
        that is located in the toolbar at the file's view page or by holding down
        <keycap>CTRL</keycap>, <keycap>ALT</keycap>
        or <keycap>SHIFT</keycap>
        when clicking on the file's name in the list. It requires that the current user has
        write permission on the file to be able to edit and set the properties.
      </para>

      <helptext external_id="file.edit" title="Edit file properties">
        <variablelist>
          <varlistentry>
            <term>
              <guilabel>Path</guilabel>
            </term>
            <listitem>
              <para>
                This is the path where the file is located. This can only be changed
                by moving the file.
                <nohelp>Read more about how this is done in
                <xref linkend="file_system.handling.move" /></nohelp>.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <guilabel>URL, Server</guilabel>
            </term>
            <listitem>
              <para>
                See <emphasis>External files</emphasis> below.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>
              <guilabel>Name</guilabel>
            </term>
            <listitem>
              <para>
                The file's name, which cannot be left empty and must be unique in
                current directory. The maximum length of the file name is 255
                characters and it can contain blank spaces but not any of
                <keycap>~</keycap>,
                <keycap>\</keycap>,
                <keycap>/</keycap>,
                <keycap>:</keycap>,
                <keycap>;</keycap>,
                <keycap>*</keycap>,
                <keycap>&#63;</keycap>,
                <keycap>&lt;</keycap>,
                <keycap>&gt;</keycap>
                or
                <keycap>|</keycap>.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <guilabel>Write protected</guilabel>
            </term>
            <listitem>
              <para>
                Mark this checkbox if you want the file to be write 
                protected. A write protected file cannot be deleted,
                moved offline or replaced with another file. It is
                still possible to change other metadata, such as
                the name, description, file type, MIME type, etc.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <guilabel>Type</guilabel>
            </term>
            <listitem>
              <para>
                Sets which kind of type the file is. Select the file type to use
                from the drop down list with available types. The option
                <guilabel>-none-</guilabel>
                should be used if the file should not be associated with any kind of
                file type.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <guilabel>MIME type</guilabel>
            </term>
            <listitem>
              <para>
                The file's content/media type. This is normally set automatically
                when uploading the file into BASE but it can be changed by an user,
                that has write permissions, at any time.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <guilabel>Description</guilabel>
            </term>
            <listitem>
              <para>
                This text area can be used to store relevant information about file
                and it's contents. Use the magnifying glass, located to the right
                under the text area, to edit the text in a larger window.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
        <para>
          Finish the editing process by pressing either
          &gbSave;
          to save the properties to the database or
          &gbCancel;
          to abort and discard the changes.
        </para>
        
        <seeother>
          <other external_id="file.external">External files</other>
          <other external_id="fileserver.edit">File servers</other>
        </seeother>
      </helptext>

    </sect2>
    <sect2 id="file_system.handling.move">
      <title>Move files</title>
      
      <para>
        These functions are used to manage the location of the files on the
        server. They are all accessed from the <guibutton>Move</guibutton>
        button on the list view of from the single-item view. On the list view,
        you must first select one or more files / directories.
      </para>
      
      <tip>
        <title>Write protect your files!</title>
        <para>
        If you mark a file as <emphasis>write protected</emphasis> it will
        not be possible to delete, move or replace the file. Use this options
        for important data files that you do not want to loose by accident.
        </para>
      </tip>
      
      <sect3 id="file_system.handling.move.directory">
        <title>To another directory</title>
        <para>
          Files and directories can be moved to other directories for re-organization. The
          user need write permission on the target directory to be able to move the
          files/directories to it.
        </para>
        <para>
          First, select all files and directories in the current path that should be moved
          and then click on
          <menuchoice>
            <guibutton>Move&hellip;</guibutton>
            <guisubmenu>To another directory</guisubmenu>
          </menuchoice>
          in the toolbar to open a window with the directory tree where the target directory
          can be picked.
        </para>
        <para>
          Choose a directory which the selected items should be moved to. It
          is possible to create new sub-directories with the 
          &gbNew; button.
        </para>
        <para>
          Click on
          &gbOk;
          to carry out the move or
          &gbCancel;
          to abort.
        </para>
      </sect3>
      
      <sect3 id="file_system.handling.move.offline">
        <title>Offline</title>
        <para>
          Moving a file offline means that the actual file contents is deleted from the 
          server's disk space but information about the file will still exist as an item 
          in the database. This makes it possible to save disk space but still be 
          able to associated the file with other items in BASE.
        </para>
        <para>
          First, select all files in current path that should be moved offline
          and then click on
          <menuchoice>
            <guibutton>Move&hellip;</guibutton>
            <guisubmenu>Offline</guisubmenu>
          </menuchoice>
          in the toolbar. 
        </para> 
        <warning>
          <para>
          Be careful! The selected files will be removed from the server. 
          The only way to recover the contents again is to re-upload the files.
          </para>
        </warning>
      </sect3>

      <sect3 id="file_system.handling.move.secondary">
        <title>To the secondary storage</title>

        <para>
          This option is only available if the server administrator
          has enabled it.
        </para>

        <para>
          The secondary storage is a kind of storage were it is appropriate
          to store files that have been used and no longer requires immediate
          access. Moving a file to and from the secondary storage is the job
          of a plug-in, which is usually executed once or twice a day.
        </para>
        
        <para>
          First, select all files in the current path that should be moved
          and then click on
          <menuchoice>
            <guibutton>Move&hellip;</guibutton>
            <guisubmenu>To secondary location</guisubmenu>
          </menuchoice>
          in the toolbar. The only thing that will happen is that BASE sets a flag
          on each file. The next time the secondary storage plug-in
          is executed, the files will be moved to the secondary storage. The
          actual file contents is deleted from the server's disk.
        </para>
        
        <para>
          While the file is in the secondary storage BASE behaves in the same way as
          if the file is offline. Th file cannot be used to import data from, or
          other things. To use the file again, the file must be moved back to
          the primary storage.
        </para>
        
        <para>
          To bring files back from the secondary storage, select the files
          and then click on 
          <menuchoice>
            <guibutton>Move&hellip;</guibutton>
            <guisubmenu>To primary location</guisubmenu>
          </menuchoice> in the toolbar. The files will be moved back the next
          time the secondary storage plug-in is executed.
        </para>
        
        <note>
          <title>Do not forget to set quota for the secondary storage</title>
          <para>
            The default installation does not assign quota for the
            secondary storage. Unless the administrator assigns quota
            the move will silently fail.
          </para>
        </note>
      </sect3>

    </sect2>

    <sect2 id="file_system.handling.actions">
      <title>Viewing and downloading files</title>
      <para>
        In <guilabel>Actions</guilabel> column in the list view there
        are icons you can click on to perform different kinds of actions on a
        file, like downloading the file and viewing the file. The same icons appear
        on the single-item view and in most other places where files are used.
        You cannot view or download files that have been moved offline or to the
        secondary storage.
      </para>
      <sect3 id="file_system.handling.actions.download">
        <title>Download a file</title>
        <para>
          This will let the user to download the contents of a file to a path on a local
          computer. The window that opens contains the selected file's name, size e.t.c.
          and it will also open a download dialog window where the user can choose what to
          do with the file locally.
          <tip>
            <title>Download does not start</title>
            <para>
              Click on the file's path name in the pop-up window if the download
              dialog window does not appears.
            </para>
          </tip>
        </para>
        <para>
          Close the pop-up window and return to file page with
          &gbClose;.
        </para>
      </sect3>
      <sect3 id="file_system.handling.actions.view">
        <title>View the contents of file</title>
        <para>
          A file's contents can be displayed directly in the web browser if the
          browser supports displaying that kind of files. Typically all HTML, text
          files and images are supported. Click on the icon to view the contents
          in a new window. If the type is not supported by the browser there will be
          a dialog-window to download the file instead.
        </para>
      </sect3>
      <sect3 id="file_system.handling.actions.zippeddownload">
        <title>Download/compress multiple files</title>
        
        <para>
        You can download multiple files/directories at the same time. First,
        from the file browser, select one or more files/directories. Then, click
        on the &gbExport; button. Select the <userinput>Packed file exporter</userinput>
        plug-in and choose one of the file formats below it. On the &gbNext;
        page you can specify other options for the download:
        </para>
        
        <itemizedlist>
        <listitem>
          <para>
            <guilabel>Save as</guilabel>: The path to a file on the BASE file system
            where the selected files and directories should be packed. Leave this 
            field empty to download the files to your own computer.
          </para>
        </listitem>
        <listitem>
          <para>
            <guilabel>Overwrite</guilabel>: If you are saving to the BASE file system
            you may select if it is allowed to overwrite an existing file or not.
          </para>
        </listitem>
        <listitem>
          <para>
            <guilabel>Remove files/directories</guilabel>: If you select this option
            the selected files and directories will be marked as removed. You must still
            go to the <guilabel>Trashcan</guilabel> and remove the items permanently.
          </para>
        </listitem>
        </itemizedlist>
        
      </sect3>
    </sect2>
    <sect2 id="file_system.handling.directories">
      <title>Directories</title>
      <para>
        Directories in BASE are folders where files can be organized into. Click on
        <guibutton>New directory&hellip;</guibutton>
        in the toolbar to create a directory in current path and edit the properties as
        described below.
      </para>
      <sect3 id="file_system.handling.directories.edit">
        <title>Edit a directory</title>
        <para>
          The window to edit a directory's properties is opened either by clicking on the
          directory's name in the list or when creating a new directory.
        </para>
        <helptext external_id="directory.edit" title="Edit directory">
          <para>
            <variablelist>
              <title>Properties</title>
              <varlistentry>
                <term>
                  <guilabel>Path</guilabel>
                </term>
                <listitem>
                  <para>
                    This property is read-only in the edit window but can be
                    changed by moving the directory<nohelp>, described in
                    <xref linkend="file_system.handling.move" /></nohelp>.
                  </para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term>
                  <guilabel>Name</guilabel>
                </term>
                <listitem>
                  <para>
                    The directory's name to identify it with in the list. This
                    field must have a value and it has to be an unique name for
                    the current directory.
                  </para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term>
                  <guilabel>Compress files</guilabel>
                </term>
                <listitem>
                  <para>
                    Enable this option to let BASE store files that
                    are uploaded to this directory in a compressed format. 
                    This option only affect files that are uploaded later, 
                    it doesn't affect already existing files or files that
                    are moved between directories.
                  </para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term>
                  <guilabel>Share new files and sub-directories automatically</guilabel>
                </term>
                <listitem>
                  <para>
                    Enable this option to let BASE automatically share
                    new files and directories with the same permissions
                    as have been specified on this directory. This
                    option is useful when you have assigned a specific 
                    directory as a common area for a group of users and
                    you want to make sure that all users has access to
                    all files. Some restrictions apply:
                  </para>
                  <itemizedlist>
                  <listitem>
                    <para>
                    Permissions for the <emphasis>Everyone</emphasis>
                    group are not inherited if the logged in user doesn't
                    have the <emphasis>SHARE_TO_EVERYONE</emphasis> permission. 
                    </para>
                  </listitem>
                  <listitem>
                    <para>
                    If a project is active the new file/directory will be shared
                    to the active project as well.
                    </para>
                  </listitem>
                  </itemizedlist>
                  
                </listitem>
              </varlistentry>
              <varlistentry>
                <term>
                  <guilabel>Description</guilabel>
                </term>
                <listitem>
                  <para>
                    Any relevant information about the directory can be written
                    in this text area. The magnifying glass down to the right
                    can be used to edit the description text in a larger text
                    area, just click on the icon to open it in a separate pop-up
                    window.
                  </para>
                </listitem>
              </varlistentry>
            </variablelist>
          </para>
          <para>
            The editing process is completed with either
            &gbSave;, to save the properties into the database, or with
            &gbCancel;
            to discard the changes. Both of the buttons will close the edit window and
            if the directory is updated the list will be reloaded with the directory's
            new properties.
          </para>
          
          <note>
            The new directory does not appear in the navigation tree
            to the left automatically. You must click on the 
            <guibutton>Refresh</guibutton> button.
          </note>
          
        </helptext>
      </sect3>
    </sect2>

  </sect1>

  <sect1 id="file_system.filetypes">
    <title>File types</title>
    <para>
      A file can be associated with one of the file types that exists in BASE. File types
      make it possible to filter the files depending of what kind of file it is. Here
      is a list of file types that are defined in BASE.
      <menuchoice>
        <guimenu>Administrate</guimenu>
        <guisubmenu>Types</guisubmenu>
        <guimenuitem>File types</guimenuitem>
      </menuchoice>
    </para>
    <variablelist>
      <title>File types</title>
      <varlistentry>
        <term>Image</term>
        <listitem>
          <para>Indicates that the file is an image file.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Plate</term>
        <listitem>
          <para>The associated file is a file with information about plate/plates.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Plate mapping</term>
        <listitem>
          <para>Files with information about plate mapping.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Print map</term>
        <listitem>
          <para>Print map files</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Protocol</term>
        <listitem>
          <para>Files with protocol information</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Raw data</term>
        <listitem>
          <para>Raw data files</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Reporter</term>
        <listitem>
          <para>Files with information about reporters</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Reporter map</term>
        <listitem>
          <para>
            Files of this type contain information about how the reporters are mapped.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Spot images</term>
        <listitem>
          <para>A zip-file containing generated spot images in JPEG format.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </sect1>
</chapter>