source: trunk/doc/src/docbook/userdoc/webclient.xml @ 3346

<?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: webclient.xml 3346 2007-05-16 12:10:14Z nicklas $

  Copyright (C) Authors contributing to this file.

  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 2
  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 this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place - Suite 330,
  Boston, MA  02111-1307, USA.
-->

<chapter id="webclient">
  <?dbhtml dir="webclient"?>
  <title>Using the web client</title>
    <sect1 id="webclient.introduction">
      <title>Introduction</title>
      
      <sect2 id="webclient.intro.login">
        <title>Logging in</title>
        <para>
          There are three things that you need to know
          before you can use BASE:
        </para>
        
        <orderedlist>
        <listitem><simpara>The address (URL) to a BASE server</simpara></listitem>
        <listitem><simpara>A username to login with</simpara></listitem>
        <listitem><simpara>A password</simpara></listitem>
        </orderedlist>
        
        <para>
          You may, for example, try the BASE 2 demo server. Go to the
          URL <ulink url="http://base2.thep.lu.se:8080/demo/">http://base2.thep.lu.se:8080/demo/</ulink>
          and enter <userinput>base2</userinput> for the login and <userinput>base2</userinput>
          for the password.
        </para>
        
        <para>
          You need to get all three things from an administrator
          of the BASE server. If you know only the address to the
          BASE server, you may check the front page if the administrator
          has added any information about how to get a username/password
          there. Look for the <guilabel>Get an account!</guilabel> link on
          the front page.
        </para>
        
        <para>
          Logging in is simple, just enter your <guilabel>login</guilabel> 
          and <guilabel>password</guilabel> in the form on the front page
          and click the <guibutton>Login</guibutton> button. There is
          a checkbox which allows you to <guilabel>encrypt the password</guilabel>
          before it is sent to the BASE server. It is checked by default, and
          it is a good idea to leave it checked unless you have problems logging
          in. If you are sure you are entering the correct login and password,
          but still can't log in, try unchecking the encryption option.
          If the checkbox isn't visible, which happens if the server is
          using an external authentication server, the password is not encrypted.
        </para>
      </sect2>
      
      <sect2 id="webclient.intro.forgotten_password">
        <title>Forgotten password</title>
        <para>
          If you forget your password you will need to get a new one.
          BASE stores the passwords in an encrypted form that doesn't allow
          anyone, not even the server administrator, to find out the 
          un-encrypted password.
        </para>
        <para>
          To get a new password you will have to contact the server
          administrator. There may be a <guilabel>Forgot your password?</guilabel>
          link on the front page where the server administrator has entered
          information about how to get a new password.
        </para>
      </sect2>

      <sect2 id="webclient.intro.homepage">
        <title>The home page</title>
      
      <para>
        When you have been logged in the home page will be displayed. It
        displays some useful information. You can also go to the home page
        using the 
        <menuchoice><guimenu>View</guimenu><guimenuitem>Home</guimenuitem></menuchoice>
      </para>
        
      <figure id="webclient.figures.homepage">
        <title>The home page</title>
        <screenshot>
          <mediaobject>
            <imageobject><imagedata fileref="figures/homepage.png" format="PNG"
              scalefit="1" width="100%" contentdepth="100%"/></imageobject>
          </mediaobject>
        </screenshot>
      </figure>
        
      <variablelist>
        <varlistentry>
          <term><interface>New messages</interface></term>
          <listitem>
            <para>
            Messages are sent by plugins to notify you about finished jobs. In the
            future, you may get messages from other sources as well. As of today,
            messages are not used for communication between users.
            </para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><interface>Projects</interface></term>
          <listitem>
            <para>
            A list of projects that you are a member of. Projects are an important
            part of BASE and are the best way to share data when you are 
            cooperating with other users. We recommend
            that you always use a project when working with BASE. 
            For more information read <xref linkend="project_permission"/>.
            </para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><interface>Disk usage</interface></term>
          <listitem>
            <para>
            An overview of how much disk space you have been assigned and
            how much you are using.
            </para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><interface>Help</interface></term>
          <listitem>
            <para>
            Links for getting help and reporting bugs. The number
            of links displayed here may vary depending on the server
            configuration.
            </para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><interface>News and announcements</interface></term>
          <listitem>
            <para>
            A list of important news and announcements from the
            server administrator. Here you may, for example, find
            information about server upgrades and maintenance.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
        
      </sect2>
      
      <sect2 id="webclient.intro.menubar">
        <title>Using the menu bar</title>
        <para>
          On the top of the home page is the <interface>Menu bar</interface>.
          This is the main navigation tool in BASE. It works the same way 
          as the regular menu system found in most other applications. Use
          the mouse to click and select an item from the menu. 
        </para>
        
        <para>
          Most of the menu is in two levels, ie. clicking on a top-level menu
          will open a submenu just below it. Clicking on something in the
          submenu will take you to another page or open a popup dialog window. 
          For example, the
          <menuchoice><guimenu>View</guimenu><guimenuitem>Samples</guimenuitem></menuchoice>
          menu will take you to the page listing samples and 
          <menuchoice><guimenu>File</guimenu><guimenuitem>Contact information</guimenuitem></menuchoice>
          opens a dialog where you can modify your contact information details.
        </para>
        
        <para>
          The menu bar also contains shortcuts to some often-used
          actions:
        </para>
        
        
      <variablelist>
        <varlistentry>
          <term>
            <interface>
            <inlinemediaobject>
            <imageobject><imagedata fileref="figures/refresh.gif" format="GIF" align="left"
              scalefit="1" width="100%" contentwidth="100%"/></imageobject>
            </inlinemediaobject>
            Refresh page
            </interface>
          </term>
          <listitem>
            <para>
            Refresh/reload the current page. This is useful when you add
            or modify items in BASE. Most of the time the page is refreshed
            automatically, but in some cases you will have to use
            this button to refresh the page.
            </para>
            
            <warning>
              <para>
              Do not use your browser's <guibutton>Refresh</guibutton> button.
              Most browsers will take you to the login page again.
              </para>
            </warning>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term>
            <interface>
            <inlinemediaobject>
            <imageobject><imagedata fileref="figures/recent.png" format="PNG" align="left"/></imageobject>
            </inlinemediaobject>
            Recent items
            </interface>
          </term>
          <listitem>
            <para>
            Go to the most recently viewed item. By default, the list contains links to
            the most recently viewed experiment and bioassayset, but this
            is configurable. If you, for example, work a lot with protocols, you may
            add a link to the most recently viewed protocol.
            See <xref linkend="webclient.configuration.preferences.mostrecent"/>
            </para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term>
            <interface>
            <inlinemediaobject>
            <imageobject><imagedata fileref="figures/project.gif" format="GIF" align="left"/></imageobject>
            </inlinemediaobject>
            Projects
            </interface>
          </term>
          <listitem>
            <para>
            A list of all projects you are a member of. Selecting a project in the
            list will make that project the active project.
            </para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term>
            <interface>
            <inlinemediaobject>
            <imageobject><imagedata fileref="figures/user.png" format="PNG" align="left"/></imageobject>
            </inlinemediaobject>
            Logged in user
            </interface>
          </term>
          <listitem>
            <para>
            Displays the name of the currently logged in user and allows
            you to quickly logout and switch to another user.
            </para>
          </listitem>
        </varlistentry>
        
      </variablelist>
        
      </sect2>
      
      <sect2 id="webclient.intro.help">
        <title>Getting help</title>
        <para>
          Besides reading this document there are more ways to get help:
        </para>
        <variablelist>
          <varlistentry>
            <term>
              Online context-sensitive help
            </term>
            <listitem>
              <para>
              Whenever you find a small help icon (
              <inlinemediaobject>
              <imageobject><imagedata fileref="figures/help.gif" format="GIF" /></imageobject>
              </inlinemediaobject>
              ) or button you may
              click it to get help about the part of the page
              you are currently viewing. The icon is located in the title
              bar in most popup dialog windows and in the toolbar in most
              other pages.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>
              Using the <menuchoice><guimenu>Help</guimenu></menuchoice> menu
            </term>
            <listitem>
              <para>
              The <menuchoice><guimenu>Help</guimenu></menuchoice> menu
              contains links for getting online help. These links
              may be configured by a server administrator, so they may be 
              different from server to server. By default links for reporting
              a bug and accessing this document are installed.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>
              Mailing lists and other resources
            </term>
            <listitem>
              <para>
              See <xref linkend="resources" />.
              </para>
            </listitem>
          </varlistentry>

        </variablelist>
        
      </sect2>
    
    </sect1>
    
    <sect1 id="webclient.configuration">
      <title>Configuring your account</title>
      
      <sect2 id="webclient.configuration.contact">
        <title>Contact information</title>
        
        <para>
          Use the <menuchoice><guimenu>File</guimenu>
          <guimenuitem>Contact information</guimenuitem></menuchoice>
          menu to bring up the user information dialog. 
        </para>
        
        <helptext external_id="userpreferences.contact" title="Contact information">
        
          <para>
          This dialog has three tabs, <guilabel>Contact information</guilabel>
          (selected), <guilabel>Password</guilabel> and <guilabel>Other information</guilabel>.
          The logged in user can update the following contact information 
          details.
          </para>
        
          <note>
            <title>Multi-user accounts</title>
            <para>
              If you are using a multi-user account, for example a demo-account, you 
              don't have permission to change the contact information.
            </para>
          </note>
        
          <variablelist>
            <varlistentry>
              <term>
                <guilabel>Full name</guilabel>
              </term>
              <listitem>
                <para>
                Your full name. You are not allowed to change this. If
                it is not correct, contact an administrator to do it for 
                you.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Email</guilabel>
              </term>
              <listitem>
                <para>
                Your email address (optional).
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Organisation</guilabel>
              </term>
              <listitem>
                <para>
                The name of the organisation you work for or represent (optional).
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Address</guilabel>
              </term>
              <listitem>
                <para>
                Your postal address as it should be printed on letters to you 
                (optional).
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Phone</guilabel>
              </term>
              <listitem>
                <para>
                Your phone number (optional). You may enter multiple phone numbers, 
                for example your work phone number and a mobile number.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Fax</guilabel>
              </term>
              <listitem>
                <para>
                Your fax number (optional).
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Url</guilabel>
              </term>
              <listitem>
                <para>
                An URL to your home page or your organisation's home page (optional).
                </para>
              </listitem>
            </varlistentry>
          </variablelist>
          
          <para>
            Press <guibutton>Save</guibutton> to save the changes or 
            <guibutton>Cancel</guibutton> to abort.
          </para>
          
          <seeother>
            <other external_id="userpreferences.password">Change password</other>
            <other external_id="userpreferences.other">Other information</other>
          </seeother>
        </helptext>
        
      </sect2>

      <sect2 id="webclient.configuration.password">
        <title>Changing password</title>
        
        <para>
          Use the <menuchoice><guimenu>File</guimenu>
          <guimenuitem>Change password</guimenuitem></menuchoice>
          menu to bring up the change password dialog.
        </para>
        
        <helptext external_id="userpreferences.password" title="Change password">

          <para>
          This dialog has three tabs, <guilabel>Contact information</guilabel>,
          <guilabel>Password</guilabel> (selected) and <guilabel>Other information</guilabel>.
          </para>

          <variablelist>
            <varlistentry>
              <term>
                <guilabel>New password</guilabel>
              </term>
              <listitem>
                <para>
                Enter the new password.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Retype password</guilabel>
              </term>
              <listitem>
                <para>
                Retype the same password. You must do this to 
                avoid spelling mistakes.
                </para>
              </listitem>
            </varlistentry>
          </variablelist>

          <note>
            <title>Multi-user accounts</title>
            <para>
              If you are using a multi-user account, for example a demo-account, you 
              don't have permission to change the password.
            </para>
          </note>
        
          <note>
            <title>Empty passwords</title>
            <para>
              If you leave both fields empty the password will not be changed. It
              is not possible to have an empty password.
            </para>
          </note>
          
          <seeother>
            <other external_id="userpreferences.contact">Contact information</other>
            <other external_id="userpreferences.other">Other information</other>
          </seeother>
          
        </helptext>
      </sect2>

      <sect2 id="webclient.configuration.preferences">
        <title>Preferences</title>
        
        <para>
          Use the <menuchoice><guimenu>File</guimenu>
          <guimenuitem>Preferences</guimenuitem></menuchoice>
          menu to bring up the preferences dialog.
          This dialog has three tabs, <guilabel>Appearance</guilabel>,
          <guilabel>Plugins</guilabel> and <guilabel>Most recent</guilabel>.
        </para>
        
        <sect3 id="webclient.configuration.preferences.appearance">
          <title>The Appearance tab</title>
          
          <helptext external_id="userpreferences.appearance" title="Preferences - Appearance">
          
          <para>
          This tab contains settings that affect the appearance of the
          web client.
          </para>
          
          <variablelist>
            <varlistentry>
              <term>
                <guilabel>Font size</guilabel>
              </term>
              <listitem>
                <para>
                Select a basic font size. You can choose between
                five sizes: extra small (XS), small (S), medium (M),
                large (L) and extra large (XL). The default font size is
                medium.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Scale factor</guilabel>
              </term>
              <listitem>
                <para>
                The scale factor affects the size of popup windows.
                This setting exists because different browsers render 
                pages differently. If you often find that popup windows
                are too small you can change this setting to make them
                bigger.
                </para>
                <note>
                  <para>
                    The scale factor is automatically changed if the 
                    font size is changed.
                  </para>
                </note>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Toolbar</guilabel>
              </term>
              <listitem>
                <para>
                You may choose if the toolbar buttons should
                have only images, only text or both images and text.
                The default is that they have both images and text.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Recently used items</guilabel>
              </term>
              <listitem>
                <para>
                The number of items to remember in the list
                of recently used items. The default is to remember 
                4 items.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Ratio color range</guilabel>
              </term>
              <listitem>
                <para>
                Select three colors to use when displaying 
                data that is suitable for color coding, for
                example the intensity ratio in two-color 
                experiments. The default setting is blue-black-yellow.
                The list of presets contains other useful color combinations
                (for example, the BASE 1 red-yellow-green) and the most
                recently used color combinations.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Date format</guilabel>
              </term>
              <listitem>
                <para>
                A format string describing how dates should be displayed.
                We support all formatting options supported by the Java
                language. For more information see:
                <ulink url="http://java.sun.com/j2se/1.5.0/docs/api/java/text/SimpleDateFormat.html">SimpleDateFormat documentation</ulink>
                The most useful format patterns are:
                </para>
                
                <itemizedlist>
                  <listitem><simpara>yy: two-digit year</simpara></listitem>
                  <listitem><simpara>yyyy: four-digit year</simpara></listitem>
                  <listitem><simpara>MM: two-digit month</simpara></listitem>
                  <listitem><simpara>MMM: month name (short)</simpara></listitem>
                  <listitem><simpara>MMMM: month name (full)</simpara></listitem>
                  <listitem><simpara>dd: two-digit day in month</simpara></listitem>
                </itemizedlist>
                
                <para>
                The list of presets contains the most commonly/recently
                used date formats.
                </para>
                
              </listitem>
            </varlistentry>
            
            <varlistentry>
              <term>
                <guilabel>Date-time format</guilabel>
              </term>
              <listitem>
                <para>
                A format string describing how dates with times should be displayed.
                We support all formatting options supported by the Java
                language. For more information see:
                <ulink url="http://java.sun.com/j2se/1.5.0/docs/api/java/text/SimpleDateFormat.html">SimpleDateFormat documentations</ulink>
                The most useful time-format patterns are:
                </para>
                
                <itemizedlist>
                  <listitem><simpara>HH: two-digit hour (0-23)</simpara></listitem>
                  <listitem><simpara>hh: two-digit hour (1-12)</simpara></listitem>
                  <listitem><simpara>a: AM/PM marker</simpara></listitem>
                  <listitem><simpara>mm: two-digit minute</simpara></listitem>
                  <listitem><simpara>ss: two-digit second</simpara></listitem>
                </itemizedlist>
                
              </listitem>
            </varlistentry>
            
            <varlistentry>
              <term>
                <guilabel>Decimals</guilabel>
              </term>
              <listitem>
                <para>
                The number of decimals to display for numeric values.
                The default is 2.
                </para>
              </listitem>
            </varlistentry>
            
          </variablelist>
        
          </helptext>
        
        </sect3>
        
        <sect3 id="webclient.configuration.preferences.plugins">
          <title>The Plugins tab</title>
          
          <helptext external_id="userpreferences.plugins" title="Preferences - Plugins">
          
          <para>
            This tab contains settings that affect plugin execution.
          </para>
          
          <variablelist>
            <varlistentry>
              <term>
                <guilabel>Messages</guilabel>
              </term>
              <listitem>
                <para>
                Mark the checkbox if you want to have a message sent
                to you when a plugin completes execution. This setting
                can be overridden each time you start a plugin.
                </para>
              </listitem>
            </varlistentry>
          </variablelist>
          </helptext>
          
        </sect3>
        
        <sect3 id="webclient.configuration.preferences.mostrecent">
          <title>The Most recent tab</title>
          
          <helptext external_id="userpreferences.mostrecent" title="Preferences - Most recent">
          
          <para>
            This tab contains settings that affect the <guilabel>Most
            recent</guilabel> menu. You can select which items should
            appear in the menu by moving them to the left list. Use
            the up and down arrows to change the order in which they appear.
          </para>
          
          <para>
            If the <guilabel>Load the names of all recent items</guilabel> checkbox
            is checked the name of the items will be displayed in the menu (for example,
            Experiment: My experiment). Otherwise only the type of the item is 
            displayed (for example, Experiment).
          </para>
          </helptext>
          
        </sect3>
      </sect2>
  
    </sect1>
    
    <sect1 id="webclient.items">
      <title>Working with items</title>
      
      <para>
        No matter what you are doing in BASE some things works more
        or less in the same way. This section covers things that are
        common for most parts of BASE.
      </para>
      
      <para>
        You mostly work with a single type of item at a time. This is
        reflected in the menu system. For example, use <guimenu>View</guimenu>
        <guimenuitem>Samples</guimenuitem> to work with samples, and 
        <guimenu>View</guimenu><guimenuitem>Experiments</guimenuitem> to 
        work with experiments. In most cases the list view for that type
        of item is displayed. The list view, as the name says, 
        is used to list all items. There are two more standard views, the 
        single-item view and the edit view.
      </para>
      
      <variablelist>
        <varlistentry>
          <term>List view</term>
          <listitem>
            <para>
            This view lists all items of a certain type. Gives you
            an overview of your items. The view allows you to search
            and it is possible to configure which information to show
            for each item. It also contains functions that
            can be used on multiple items at the same time, for example,
            delete, share and export.
            </para>
          </listitem>
        </varlistentry>
      
        <varlistentry>
          <term>Single-item view</term>
          <listitem>
            <para>
            Displays information about a single item. Sometimes it is very little,
            sometimes it is very much and the information may be divided
            into multiple tabs.
            </para>
          </listitem>
        </varlistentry>
      
        <varlistentry>
          <term>Edit view</term>
          <listitem>
            <para>
            This view is used for editing the information
            about a single item. It is always displayed as a popup window.
            </para>
          </listitem>
        </varlistentry>
      </variablelist> 
              
      <sect2 id="webclient.items.new">
        <title>Create a new item</title>
        
        <para>
          New items are mostly created from the list view. For example,
          to create a new experiment go to the 
          <menuchoice><guimenu>View</guimenu> <guimenuitem>Experiments</guimenuitem></menuchoice>
          page. Here you will find a <guibutton>New&hellip;</guibutton> button in the
          toolbar. The button is disabled if you don't have permission to create new experiments. 
          Otherwise, click on it and enter any required information in the popup dialog.
          Sometimes there are multiple tabs in this dialog. In the case of experiments
          there are three tabs: <guilabel>Experiment</guilabel>, <guilabel>Publication</guilabel>
          and <guilabel>Experimental factors</guilabel>.
          
          As a general rule, only the first tab has information that is required. 
          The information in all other tabs are optional.
        </para>
        
        <para>
          In some places you will also find actions that create items
          directly in the list. For example in the list of samples or on
          the single-item view for a sample you can create an extract using that
          sample as the parent. If you use such links the parent
          item will in most cases be selected automatically, which saves
          you a few clicks when creating new items.
        </para>
        
        <para>
          Click on the <guibutton>Save</guibutton> button to save the new
          item to the database or on the <guibutton>Cancel</guibutton> button
          to abort.
        </para>

        <note>
          <para>
          To speed up data entry when adding multiple new items there
          are a few tricks you can use to make the web client supply
          default values for most properties. To find a default value
          the following checklist is used in this order:
          </para>
        
        <orderedlist>         
          <listitem>
            <para>
            If the list have an active filter the filter values are
            used as default property values for the new item. For example,
            if you are listing experiments with <guilabel>Genepix</guilabel>
            raw data type the new experiment will automatically have
            <guilabel>Genepix</guilabel> selected. This trick should work
            for all properties except annotations, if it doesn't
            report it as a bug to the development team.
            </para>
          </listitem>
          
          <listitem>
            <para>
            When you link to other items the same item will be used the next time.
            For example, if you create an extract and selects an extraction protocol
            the same protocol is used the next time you create another extract.
            In fact, BASE will remember as many items as specified by
            the <link linkend="webclient.configuration.preferences.appearance">
            <guilabel>Recently used items</guilabel></link> setting (default is 4),
            allowing you to quickly select one of those protocols.
            </para>
          </listitem>
          
          <listitem>
            <para>
            If you have a project active and that project has specified default 
            values those values will be used for new items. A project can specify
            defaults for protocols, hardware and software and a few other settings.
            </para>
          </listitem>
          
        </orderedlist>
        
        </note>
        
      </sect2>
      
      <sect2 id="webclient.items.edit">
        <title>Edit an existing item</title>
        
        <para>
          On all single-item views there is an <guibutton>Edit&hellip;</guibutton>
          button in the toolbar that opens a popup dialog for editing the properties
          of the item. This button is disabled if the logged in user doesn't have
          write permission for the item.
        </para>
        
        <para>
          You can also open the edit popup in most other places where
          the item appears, for example, in lists or the single-item view
          of a related item. Press and hold one of the <keycap>CTRL</keycap>, 
          <keycap>ALT</keycap> or <keycap>SHIFT</keycap> keys while clicking
          on the link and the edit window will open in a popup. 
          If you don't have write permission
          on the item there is no meaning to open the edit popup and you will 
          be taken to the single-item view page instead.
        </para>

        <para>
          Click on the <guibutton>Save</guibutton> button to save the changes
          to the database or on the <guibutton>Cancel</guibutton> button
          to abort.
        </para>
      
      </sect2>

      <sect2 id="webclient.items.delete">
        <title>Delete items</title>

        <para>
          You can delete items either from the list view or from 
          a single-item view. In both cases, the item is only moved to
          the trashcan. No information is deleted from the database. This allows
          you to restore the item if you later find out that you need it again.
          In fact, there is nothing special about a removed item. It can still be
          used for the same things as any non-removed item can.
        </para>

        <important>
          <para>
          To really delete an item from the database you must use
          the trashcan. See <xref linkend="trashcan"/>
          </para>
        </important>
        
        <para>
          To delete items from the list view you must first mark
          the checkbox for each item you want to delete. Then, click on 
          the <guibutton>Delete</guibutton> button. The list should refresh itself
          automatically. If you want to confirm that the items have been removed
          use the <guilabel>view / presets</guilabel> dropdown and select
          the <guilabel>Removed</guilabel> option. The removed items should now
          be displayed in the list with a small trashcan icon to indicate that
          they are located in the trashcan.
        </para>

        <para>
          To delete items from the single-item view, click on the 
          <guibutton>Delete</guibutton> button in the toolbar. The page will refresh
          itself automatically and a small trashcan icon should be displayed.
          If you don't have permission to delete the item the delete button
          is disabled.
        </para>

      </sect2>
      
      <sect2 id="webclient.items.restore">
        <title>Restore deleted items</title>
        
        <para>
          You can restore deleted items either from the trashcan,
          from the list view or from the single-item view. This section only covers the last two
          cases. The trashcan has a <link linkend="trashcan">chapter of it's own</link>.
        </para>

        <para>
          To delete items from the list view you must first make the deleted
          items appear in the list. This is easy, just use the <guilabel>view / presets</guilabel> 
          dropdown and select the <guilabel>Removed</guilabel> option. The list should
          refresh itself automatically. The removed items are 
          displayed in the list with a small trashcan icon to indicate that
          they are located in the trashcan. Then, mark the checkbox for each item that you want
          to restore and click the <guibutton>Restore</guibutton> button. The list should 
          refresh itself automatically and the trashcan icon should be gone from the
          restored items.
        </para>
        
        <para>
          To restore items from the single-item view, click on the 
          <guibutton>Restore</guibutton> button in the toolbar. The page will refresh
          itself automatically and the small trashcan icon should be gone.
          If you don't have permission to restore the item the restore button
          is disabled.
        </para>

      </sect2>

      <sect2 id="webclient.items.share">
        <title>Share items to other users</title>
        <para>
          Sharing data with other users is an important feature
          of BASE, which allows you cooperate in teams. If you have
          followed the instructions in <xref linkend="project_permission" />
          you will find that you almost never have to share items manually
          to other users. This is because whenever you work with an active 
          project each new item you create will automatically be shared
          to that project. In most cases, this is all you need.
        </para>
        
        <para>
          If you still need to manually share your data with other users, 
          here is how to do it.
        </para>
        
        <para>
          From a list view, mark the checkbox for each item you want to share.
          Then, click on the <guibutton>Share&hellip;</guibutton> button.
          If you are on a single-item page, click on the <guibutton>Share&hellip;</guibutton> 
          button on that page. In both cases, this will open the 
          <guilabel>Set access permissions</guilabel>
          dialog window.
        </para>
        
        <figure id="webclient.items.share.set_permissions">
          <title>Sharing items to other users</title>
          <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/set_permissions.png" format="PNG" 
                scalefit="1" width="100%" contentdepth="100%" />
            </imageobject>
          </mediaobject>
          </screenshot>
        </figure>
        
        <helptext external_id="share.setpermissions" title="Set access permissions">
          <variablelist>
            <varlistentry>
              <term><guilabel>Members</guilabel></term>
              <listitem>
                <para>
                The list displays the users, groups and projects
                that already has access to the items you selected.
                The list shows the name and the permission level. 
                The permission level uses a one-letter code as follows:
                </para>
                
                <itemizedlist>
                <listitem><simpara><guilabel>R</guilabel> = Read</simpara></listitem>
                <listitem><simpara><guilabel>U</guilabel> = Use</simpara></listitem>
                <listitem><simpara><guilabel>W</guilabel> = Write</simpara></listitem>
                <listitem><simpara><guilabel>D</guilabel> = Delete</simpara></listitem>
                <listitem><simpara><guilabel>O</guilabel> = Take ownership</simpara></listitem>
                <listitem><simpara><guilabel>P</guilabel> = Set permission</simpara></listitem>
                </itemizedlist>
                
                <para>
                  Instead of a permission code, the word <guilabel>varying</guilabel>
                  may be displayed. This happens if the items you selected have been
                  shared with different permission.
                </para>
                
              </listitem>
            </varlistentry>
            
            <varlistentry>
              <term><guilabel>Permissions</guilabel></term>
              <listitem>
                <para>
                When you select a user, group or project in the
                list, the checkboxes will display the current permission. 
                The exception is if the permissions are varying, in which
                case no checkboxes are checked.
                To change the permissions just check the permissions you want to 
                grant or uncheck the permissions you want to revoke.
                You can select more than one user, group or project
                and change the permissions for all of them at once.
                </para>
              </listitem>
            </varlistentry>           

            <varlistentry>
              <term><guibutton>Add users</guibutton></term>
              <listitem>
                <para>
                Opens a popup window that allows you to select
                users to share the items to. In the popup window, mark
                one or more users and click on the <guibutton>Ok</guibutton>
                button. Unless you are an administrator, the popup window 
                will only list users that are members of at least one of the 
                groups where you also are a member. It will not list users that 
                already have access to the items.
                </para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><guibutton>Add groups</guibutton></term>
              <listitem>
                <para>
                Opens a popup window that allows you to select
                groups to share the items to. In the popup window, mark
                one or more groups and click on the <guibutton>Ok</guibutton>
                button. Unless you are an administrator, the popup window 
                will only list groups where you are a member. It will not list
                groups that already have access to the items.
                </para>
              </listitem>
            </varlistentry>
            
            <varlistentry>
              <term><guibutton>Add projects</guibutton></term>
              <listitem>
                <para>
                Opens a popup window that allows you to select
                projects to share the items to. In the popup window, mark
                one or more projects and click on the <guibutton>Ok</guibutton>
                button. Unless you are an administrator, the popup window 
                will only list projects where you are a member. It will not list
                projects that already have access to the items.
                </para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><guibutton>Remove</guibutton></term>
              <listitem>
                <para>
                Click on this button to revoke access permissions from
                the selected users, groups and projects.
                </para>
              </listitem>   
            </varlistentry>
          </variablelist>
        
          <para>
            Use the <guibutton>Save</guibutton> button to save your
            changes or the <guibutton>Cancel</guibutton> button to
            close the popup without saving.
          </para>
        </helptext>

      </sect2>

      <sect2 id="webclient.items.takeownership">
        <title>Take ownership of items</title>
        <para>
          Sometime it may be necessary to change the owner of an item.
          As an user you can't give the ownership of your items to another
          user. It is instead the other user that must take the ownership
          of your items. For this to work, you must first give the other user
          permission to do so. That it, you must share your items with 
          <guilabel>Take ownership</guilabel> permission to other user. 
          See <xref linkend="webclient.items.share" />.
        </para>
        
        <para>
          When the items have been shared, the other user has to go to the
          list view (or the single-item view), mark the checkboxes for
          the items, and click in the <guibutton>Take ownership</guibutton>
          button. A warning message about not being able to undo the action
          is displayed. Click on <guibutton>Ok</guibutton> to continue or
          <guibutton>Cancel</guibutton> to abort.
        </para>
        
        <note>
          <para>
          The original owner may not have access permissions to the items
          any longer. If that is desired, the new owner must share the items
          to the original owner.
          </para>
        </note>
        
      </sect2>
      
      <sect2 id="webclient.items.export">
        <title>Export items</title>
        <para>
          This has a chapter of it's own. See <xref linkend="import_export_data.export"/>.
        </para>
      </sect2>

    </sect1>
    
    <sect1 id="webclient.itemlist">
      <title>Listing items</title>
      
      <para>
        All pages that lists items are very similar in their appearance and
        functionality. In this section we will describe the things that are
        common for most (if not all) list pages.
      </para>
      
      <para>
        Use the <link linkend="webclient.intro.menubar">menu</link> to
        open a page listing items. Most list pages can only
        list one type of items. For example: use the 
        <menuchoice><guimenu>View</guimenu><guimenuitem>Samples</guimenuitem></menuchoice>
        menu to list samples and the 
        <menuchoice><guimenu>View</guimenu><guimenuitem>Experiments</guimenuitem></menuchoice>
        menu to list experiments. An example of a list page that can list
        items of several types is the <link linkend="trashcan">Trashcan</link>.     
        A typical list page is shown below.
      </para>
      
      <figure id="webclient.figures.listpage">
        <title>Example of a list page</title>
        <screenshot>
          <mediaobject>
            <imageobject><imagedata fileref="figures/listpage.png" format="PNG"
              scalefit="1" width="100%" contentdepth="100%" /></imageobject>
          </mediaobject>
        </screenshot>
      </figure>
      
      <para>
        The typical list page contains the following important
        elements:
      </para>

      <variablelist>
        <varlistentry>
          <term><interface>1. Toolbar</interface></term>
          <listitem>
            <para>
            A toolbar with buttons for various actions such as
            <guibutton>New&hellip;</guibutton> for creating a new item, 
            <guibutton>Delete</guibutton> for deleting items and 
            <guibutton>Columns&hellip;</guibutton> for configuring columns.
            Depending on the permissions of the logged in user
            some buttons may be disabled (greyed out) or not shown at all.
            </para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><interface>2. Navigation bar</interface></term>
          <listitem>
            <para>
            If there are many items the list will be divided into
            pages, each one showing a limited number of items.
            The navigation bar allows you to
            move to other pages and specify how many items each page
            should display. The navigation bar is repeated at the
            bottom of the list so you don't have to scroll back to the
            top of a long list just to get to another page.
            </para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><interface>3. List of presets</interface></term>
          <listitem>
            <para>
            A list with preconfigured settings which allows you to 
            quickly switch between different layouts (sort order, visible
            columns, filter settings, etc).
            </para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><interface>4. Column headers</interface></term>
          <listitem>
            <para>
            The columns headers can be used for selecting sort order.
            </para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><interface>5. Filter bar</interface></term>
          <listitem>
            <para>
            The filter bar allows you to search for items.
            </para>
          </listitem>
        </varlistentry>
        
      </variablelist>
      
      
      <sect2 id="webclient.itemlist.order">
        <title>Ordering the list</title>
        
        <para>
          Most lists are by default sorted by the name of the item. This can
          be changed by clicking on the column header of another column.
          If you click on the same column twice the sort order is reversed.
          A downwards or upwards pointing arrow is displayed next to the 
          column header in the column that is currently used for sorting.
          Column headers that are black can't be used for sorting.
        </para>
        
        <para>
          It is possible to use more than one column for sorting. Press
          and hold one of the <keycap>CTRL</keycap>, 
          <keycap>ALT</keycap> or <keycap>SHIFT</keycap> keys while clicking 
          on another column header. The original sorting is kept and the new
          column is used for sub-sorting the list. The procedure can be 
          repeated with more columns if you need to sort on three or more
          columns. To revert to sort by only one column again click a 
          column header without holding down any key.
        </para> 
      </sect2>
    
      <sect2 id="webclient.itemlist.filter">
        <title>Filtering the list</title>
        
        <para>
          If the list contains many items you may need to use a filter to be
          able to find the item you are looking for. The input boxes on the
          line below the column headers are used for filtering. Most columns
          are filtered using a free-text input box, but some columns that can
          only take a few distinct values use a selection list or radio buttons
          instead. The selection list and radio buttons are very simple to use.
          Just select the alternative that you want to filter on. The list
          will be automatically updated when the selection has been made.
        </para>
        
        <para>
          The free-text filter is a bit more complex. By default, an exact match is
          required, use % as a wildcard that matches any character. 
          For example, the filter <informalexample>Experiment A</informalexample> 
          only matches the same exact string, but the filter 
          <informalexample>Exp%</informalexample> matches 
          <informalexample>Experiment A, Experiment B, etc.</informalexample>
        </para>
        
        <para>
          You can also use operators to find items which has a value that
          is greater than, less than or not equal to a specific value. This is
          mostly useful on numeric or date columns but also works on text
          columns. The operator must be entered first in the
          free-text box, for example
          <informalexample>&lt;=10</informalexample>
          to find items which has a value less than or equal to 10.   
          Here is a list of the supported operators:
        </para>
        
        <variablelist id="webclient.itemlist.filter.operators">
          <title>List of operators supported by the free-text filter</title>
          <varlistentry>
            <term><keycap>&lt;</keycap></term>
            <listitem><simpara>Less than</simpara></listitem>
          </varlistentry>
          <varlistentry>
            <term><keycap>&lt;=</keycap></term>
            <listitem><simpara>Less than or equal to</simpara></listitem>
          </varlistentry>
          <varlistentry>
            <term><keycap>&gt;</keycap></term>
            <listitem><simpara>Greater than</simpara></listitem>
          </varlistentry>
          <varlistentry>
            <term><keycap>&gt;=</keycap></term>
            <listitem><simpara>Greater than or equal to</simpara></listitem>
          </varlistentry>
          <varlistentry>
            <term><keycap>=</keycap></term>
            <listitem><simpara>Equal to (useful to find items with a null value)</simpara></listitem>
          </varlistentry>
          <varlistentry>
            <term><keycap>&lt;&gt;</keycap></term>
            <term><keycap>!=</keycap></term>
            <listitem><simpara>Not equal to (useful to find items with a non-null value)</simpara></listitem>
          </varlistentry>
        </variablelist>
      </sect2>
      
      <sect2 id="webclient.itemlist.columns">
        <title>Configuring which columns to show</title>
        
        <para>
          Most lists show only a small subset of the columns it
          is capable of showing. Use the 
          <guibutton>Columns&hellip;</guibutton> button to open 
          a dialog that allows you to select which columns to show
          and the order in which they are shown.
        </para>
        
        <figure id="webclient.figures.configure_columns">
          <title>Configuring which columns to show</title>
          <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata contentwidth="10cm" width="10cm"  fileref="figures/configure_columns.png" format="PNG"/>
            </imageobject>
          </mediaobject>
          </screenshot>
        </figure>
        
        <helptext external_id="columns.configure" 
          title="Set column order and visiblity">
        
        <variablelist>
        <varlistentry>
          <term><guilabel>Visible columns</guilabel></term>
          <listitem>
            <para>
              Shows the columns that are currently visible.
              Use the up/down arrow buttons to arrange the order of the 
              visible columns. The topmost column is shown to the left. 
              Use the right arrow button to move columns from this list
              to the hidden columns list. Columns marked with an <guilabel>×</guilabel> 
              are required
              and can't be hidden. In most lists the <guilabel>Name</guilabel> column
              is the only column that is required.
            </para>
          </listitem>
        </varlistentry>
          
        <varlistentry>
          <term><guilabel>Hidden columns</guilabel></term>
          <listitem>
            <para>
              Shows columns that are not currently visible in the
              list. Use the left arrow button to move columns from
              this list to the visible columns list.
            </para>
          </listitem>
        </varlistentry>
        
        
        <varlistentry>
          <term><guilabel>Presets</guilabel></term>
          <listitem>
            <para>
              A dropdown list that allows you to
              select a set of preconfigured columns. You may also create 
              your own preset if you often need to switch between different
              configurations. The list of presets is the same as the one
              described <link linkend="webclient.itemlist.presets">below</link>, 
              but if used from this dialog the presets doesn't affect filters,
              sort order, etc.
            </para>
          </listitem>
        </varlistentry>
        </variablelist>
        
          <para>
            Use the <guibutton>Save</guibutton> button to apply your
            changes or the <guibutton>Cancel</guibutton> button to
            close the popup without saving.
          </para>

        </helptext>

      </sect2>
      
      <sect2 id="webclient.itemlist.presets">
        <title>Presets</title>
        
        <para>
          The <guilabel>view / presets</guilabel> dropdown has three
          main functions:
        </para>
        
        <figure id="webclient.figures.viewpresets">
          <title>The view / presets dropdown</title>
          <screenshot>
            <mediaobject>
              <imageobject><imagedata fileref="figures/view_presets.png" format="PNG" 
                /></imageobject>
            </mediaobject>
          </screenshot>
        </figure>
        <orderedlist>
          <listitem>
            <para>
              Switch between different configuration presets.
              The top of the dropdown contains user-defined presets (<guilabel>Saved preset #1</guilabel> and 
              <guilabel>#2</guilabel>) and a few preconfigured presets. 
              The user-defined presets are used to store a complete table configuration,
              including:
            </para>
            
            <itemizedlist>
              <listitem><simpara>Which columns are visible and their order</simpara></listitem>
              <listitem><simpara>The column (or columns) used for sorting</simpara></listitem>
              <listitem><simpara>Filter settings</simpara></listitem>
              <listitem><simpara>The number of items per page and the current page</simpara></listitem>
            </itemizedlist>
            
            <para>              
              The preconfigured presets only affects
              the visible columns as follows:
            </para>
            
            <itemizedlist>
              <listitem>
                <para><guilabel>All columns</guilabel> - Show all columns.</para>
              </listitem>
              <listitem>
                <para><guilabel>Required columns</guilabel> - Show only the required columns. 
                  Usually only the <guilabel>Name</guilabel> column is required.</para>
              </listitem>
              <listitem>
                <para><guilabel>Default columns</guilabel> - Show the default set of columns.</para>
              </listitem>
              <listitem>
                <para><guilabel>Other&hellip;</guilabel> - 
                  Open the <link linkend="webclient.itemlist.columns">configure columns dialog box</link>.</para>
              </listitem>
            </itemizedlist>
            
          </listitem>
          
          <listitem>
            <para>
              Filter items by the removed status and the access
              permissions to an item.
            </para>
            
            <itemizedlist>
              <listitem>
                <para><guilabel>Removed</guilabel> - If checked, items that have been
                moved to the trashcan are shown, otherwise they are hidden.</para>
              </listitem>
              <listitem>
                <para><guilabel>Owned by me</guilabel> - If checked, items that the logged in user
                owns are displayed, otherwise they are hidden.</para>
              </listitem>
              <listitem>
                <para><guilabel>Shared to me</guilabel> - If checked, items that are owned
                by other users but shared to the logged in user are displayed, otherwise 
                they are hidden.</para>
              </listitem>
              <listitem>
                <para><guilabel>In current project</guilabel> - 
                  If checked, items that are linked with the current project are displayed,
                  otherwise they are hidden. It doesn't matter if the logged in user is the
                  owner or not. This option is only available if a project is active.
                </para>
              </listitem>
              <listitem>
                <para><guilabel>Owned by others</guilabel> - 
                  This option is only available to administrators and will display
                  items that are owned by other users.
                </para>
              </listitem>
            </itemizedlist>
            
            <para>
              The default is to display item that the current user
              owns and, if a project is active, items in that project.
            </para>
            
          </listitem>

          <listitem>
            <para>
              Administrate the presets
            </para>
            <itemizedlist>
              <listitem>
                <para><guilabel>Clear filter</guilabel> - Clears
                all filters.</para>
              </listitem>
              
              <listitem>
                <para><guilabel>Save as&hellip;</guilabel> - Save the
                current configuration as a preset.</para>
              </listitem>

              <listitem>
                <para><guilabel>Manage&hellip;</guilabel> - Opens a dialog
                where you can remove saved presets. You can also load
                saved presets from the dialog, but it is quicker to just
                use the dropdown list for this.</para>
              </listitem>
            </itemizedlist>
          </listitem>
        </orderedlist>
        
        <sect3 id="webclient.itemlist.presets.saveas">
          <title>Save a preset</title>
          
          <para>
            If you select the <guilabel>Save as&hellip;</guilabel>
            option from the <guilabel>view / presets</guilabel> dropdown
            the <guilabel>Save preset as</guilabel> dialog is opened.
          </para>
          
          <figure id="webclient.figures.savepresetas">
            <title>Save preset as</title>
            <screenshot>
              <mediaobject>
                <imageobject><imagedata contentwidth="10cm" width="10cm" fileref="figures/save_preset.png" format="PNG" /></imageobject>
              </mediaobject>
            </screenshot>
          </figure>
          
          <helptext external_id="contexts.saveas" title="Save preset as">
          
          <variablelist>
          <varlistentry>
            <term><guilabel>For item</guilabel></term>
            <listitem>
              <para>
              The type of item the preset is saved for.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><guilabel >Name</guilabel></term>
            <listitem>
              <para>
              The name of the preset. The name must be unique.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><guilabel>Overwrite existing</guilabel></term>
            <listitem>
              <para>
              If a preset with the same name already exists, it is
              overwritten if this checkbox is checked.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><guilabel>Public</guilabel></term>
            <listitem>
              <para>
              This options is only available for users
              which has the <emphasis>SHARE_TO_EVERYONE</emphasis>
              permission. If checked the preset is visible to
              all users.
              </para>
            </listitem>
          </varlistentry>
          </variablelist>
          
          <para>
            Use the <guibutton>Ok</guibutton> button to save the preset
            or the <guibutton>Cancel</guibutton> button to
            close the popup without saving.
          </para>
          
          
          </helptext>
          
        </sect3>
        
        <sect3 id="webclient.itemlist.presets.manage">
          <title>Manage presets</title>
          
          <para>
            If you select the <guilabel>Manage&hellip;</guilabel>
            option from the <guilabel>view / presets</guilabel> dropdown
            the <guilabel>Manage presets</guilabel> dialog is opened.
          </para>
          
          <figure id="webclient.figures.managepresets">
            <title>Manage presets</title>
            <screenshot>
              <mediaobject>
                <imageobject><imagedata contentwidth="7cm" width="7cm" fileref="figures/manage_presets.png" format="PNG" /></imageobject>
              </mediaobject>
            </screenshot>
          </figure>
          
          <helptext external_id="contexts.manage" title="Manage presets">
          
          <para>
            From this dialog you can delete or load presets.
          </para>
          
          <para>
            To delete presets, first mark the checkbox in front of
            each preset you want to delete. Then, click on the
            <guibutton>Delete&hellip;</guibutton> button. You will get
            a warning about that the action can't be undone. Unlike other
            items, the presets are not moved to the trashcan. Click on
            <guibutton>Ok</guibutton> to delete the preset.
          </para>
          
          <note>
            <title>Edit a preset</title>
            <para>
            It is not possible to edit a preset directly. To change an
            existing preset you must:
            
            <orderedlist>
            <listitem><simpara>Load the preset.</simpara></listitem>
            <listitem><simpara>Use the interface to change column settings, filter, 
              sort order, etc.</simpara></listitem>
            <listitem><simpara>Save the preset with the same name.</simpara></listitem>
            </orderedlist>
            </para>
          </note>
          
          <para>
            Use the <guibutton>Close</guibutton> button to
            close the popup.
          </para>
          
          
          </helptext>
          
        </sect3>
        
      </sect2>
    </sect1>
    
</chapter>