source: trunk/doc/src/docbook/user/webclient.xml @ 7982

<?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 7982 2021-06-14 08:01:21Z nicklas $

  Copyright (C) 2007 Jari Häkkinen, 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="webclient">
  <?dbhtml dir="webclient" filename="index.html" ?>
  <title>Using the web client</title>
    <sect1 id="webclient.introduction">
      <?dbhtml filename="introduction.html" ?>
      <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 demo server. Go to the
          URL <ulink url="https://base.onk.lu.se/demo/">https://base.onk.lu.se/demo/</ulink>
          and enter <userinput>base2</userinput> for the login and <userinput>base2</userinput>
          for the password. NOTE! The demo server is currently down!
        </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.
        </para>
        
        <note>
          <title>Problems with the start page</title>
          <para>
            If you have selected a non-default start page
            and there happens to be a problem with it 
            it may prevent you from accessing BASE. In
            the worst scenario all that is displayed is a cryptic
            error message. In this case, it is good to know that
            holding down either one of the <guilabel>ALT</guilabel>
            or <guilabel>CTRL</guilabel> or <guilabel>SHIFT</guilabel>
            keys while clicking the <guibutton>Login</guibutton>
            button will force BASE to use the regular start page.
          </para>
        </note>
        
      </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 does not 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.2-factor-login">
        <title>2-factor login</title>
        <para>
          BASE supports a 2-factor login system that sends out one-time
          verification codes via email the first time you try to
          login from a new browser. The system has been designed to
          protect your account in case your login information and password
          is compromised. If 2-factor login has been enabled on the 
          server and for your user account (see <xref linkend="webclient.configuration.contact" />), 
          an additional screen is displayed.
        </para>

        <figure id="webclient.figures.2-factor-login">
          <title>2-factor login: Enter verification code</title>
          <screenshot>
            <mediaobject>
              <imageobject><imagedata fileref="figures/verification_code.png" format="PNG"
                scalefit="1" width="100%"/></imageobject>
            </mediaobject>
          </screenshot>
        </figure>

        <para>
          To complete the login, you need to enter the verification code (6 digits)
          that is sent to your registered email address. If you keep the 
          <guilabel>Remember this device</guilabel> checked then BASE will remember
          the browser you are using and not ask you about a verification code the next
          time.
        </para>
        
        <tip>
          <para>
            If you are on a public computer you should uncheck the 
            <guilabel>Remember this device</guilabel> to prevent someone
            else from logging into your account at a later time from that
            computer.
          </para>
          
          <para>
            If you go to <menuchoice><guimenu>BASE</guimenu><guimenuitem>Devices</guimenuitem></menuchoice>
            you can see all registered devices/browsers that you have used to access the BASE server.
            We recommend that you check this list once in a while and delete browsers that
            you no longer use. 
          </para>
        </tip>
        
        <note>
          <title>Private browsing mode</title>
          
          <para>
            BASE need to store a token on your computer to make the 2-factor login system
            work. If you are using a browser in private or incognito mode the 2-factor login
            may not work.
          </para>
        </note>
        
      </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>
        menu.
      </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%"/></imageobject>
          </mediaobject>
        </screenshot>
      </figure>
        
      <variablelist>
        <varlistentry>
          <term><interface>New messages</interface></term>
          <listitem>
            <para>
            Messages are, for example, sent by plug-ins 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"/>. The list
            displays the most recently used projects first and then fills up
            with the rest sorted by name.
            </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>
            
            <tip>
              <title>Subscribe to the RSS news feed.</title>
              <para>
                Click on the RSS icon <guiicon>
              <inlinemediaobject>
              <imageobject><imagedata fileref="figures/rss.png" format="PNG" /></imageobject>
              </inlinemediaobject>
            </guiicon> in the <interface>News and announcements</interface>
                title bar. This allows you to subscribe to the news feed 
                from the BASE server so that you don't miss anything interesting.
              </para>
            </tip>
          </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 pop-up dialog window. 
          For example, the
          <menuchoice><guimenu>Biomaterial LIMS</guimenu><guimenuitem>Samples</guimenuitem></menuchoice>
          menu will take you to the page listing samples and 
          <menuchoice><guimenu>BASE</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>
            <guiicon>
              <inlinemediaobject>
              <imageobject><imagedata fileref="figures/project.png" format="PNG" /></imageobject>
              </inlinemediaobject>
            </guiicon>
            <interface>
            Projects
            </interface>
          </term>
          <listitem>
            <para>
            A list of all projects you are a member of. The most recently used projects are
            listed first, then the list is filled with the rest of your projects up to a
            maximum of 15. If you have more projects an option to display the remaining 
            projects is activated. Selecting a project in the list will make that project 
            the active project. 
            </para>
            <tip>
              <para>
              The sort order in the menu of non-recent projects is the same as the sort order on the
              projects list page. If you, for example, want to sort the newest
              project first (after the most recently used ones), select to sort by the 
              <guilabel>Registered</guilabel> column in descending order on the list page. 
              The menu will automatically use the same order.
              </para>
            </tip>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>            
            <guiicon>
              <inlinemediaobject>
              <imageobject><imagedata fileref="figures/refresh.png" format="PNG" 
                /></imageobject>
              </inlinemediaobject>
            </guiicon> 
            <interface>
            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>      
            <guiicon>     
              <inlinemediaobject>
              <imageobject><imagedata fileref="figures/recent.png" format="PNG"/></imageobject>
              </inlinemediaobject>
            </guiicon>
            <interface>
            Recent items
            </interface>
          </term>
          <listitem>
            <para>
            Shortcut to the most recently viewed items. The number of items are
            configurable and you can also make some item types 
            <emphasis>sticky</emphasis>. This will for example keep the shortcut
            to the last experiment even if you have viewed lots of other items
            more recently.
            See <xref linkend="webclient.configuration.preferences.mostrecent"/>
            for configuration information.
            </para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term>
            <guiicon>
              <inlinemediaobject>
              <imageobject><imagedata fileref="figures/user.png" format="PNG" /></imageobject>
              </inlinemediaobject>
            </guiicon>
            <interface>
            Logged in user
            </interface>
          </term>
          <listitem>
            <para>
            Displays the name of the currently logged in user and allows
            you to quickly log out 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>
              On-line context-sensitive help
            </term>
            <listitem>
              <para>
              Whenever you find a small help icon 
              <guiicon>
                <inlinemediaobject>
                <imageobject><imagedata fileref="figures/help.png" format="PNG" /></imageobject>
                </inlinemediaobject>
              </guiicon>
              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 pop-up 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 on-line 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">
      <?dbhtml filename="configuration.html" ?>
      <title>Configuring your account</title>
      
      <sect2 id="webclient.configuration.contact">
        <title>Contact information</title>
        
        <para>
          Use the <menuchoice><guimenu>BASE</guimenu>
          <guimenuitem>Contact information</guimenuitem></menuchoice>
          menu to bring up the user information dialog. 
        </para>
          
          <figure id="webclient.figures.contactinformation">
            <title>Contact information</title>
            <screenshot>
              <mediaobject>
                <imageobject><imagedata fileref="figures/contact_information.png" format="PNG" /></imageobject>
              </mediaobject>
            </screenshot>
          </figure>
        
        <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 
              do not 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). If an email has been specified and if the
                server administrator has enabled email notifications, you also have the
                option to select if messages should be sent as emails. This can be useful
                to keep track of jobs that take a long time to complete.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Enable 2-factor login</guilabel>
              </term>
              <listitem>
                <para>
                Enables 2-factor login for your account. This causes BASE to send out
                an email message with a one-time verification code the first time you
                login with an unknown device/browser. When you enable this option BASE
                will also send an email to verify your email address.
                Note that this option is only available if the server administrator has 
                configure BASE to use it.
                </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 &gbSave; to save the changes or 
            &gbCancel; to abort.
          </para>
          
          <seeother>
            <other external_id="userpreferences.password">Change password</other>
            <other external_id="userpreferences.other">Other information</other>
            <other external_id="userpreferences.verifyemail">Verify email</other>
          </seeother>
        </helptext>
        
        <sect3 id="webclient.configuration.verifyemail">
          <title>Verify email</title>

          <figure id="webclient.figures.verifyemail">
            <title>Verify email</title>
            <screenshot>
              <mediaobject>
                <imageobject><imagedata fileref="figures/verify_email.png" format="PNG" /></imageobject>
              </mediaobject>
            </screenshot>
          </figure>
          
          <helptext external_id="userpreferences.verifyemail" title="Verify email">
          <para>
            If you enable <guilabel>2-factor login</guilabel> or change your email
            address while it is enabled, BASE will send out an email with a verification
            code and display this dialog. You need to enter the verification code to
            enable 2-factor login. If the code is incorrect or if you cancel this dialog
            2-factor login will be disabled.
          </para>
          </helptext>
          
        </sect3>
        
      </sect2>
      
      <sect2 id="webclient.configuration.other">
        <title>Other information</title>
        <para>
          Use the
          <menuchoice>
            <guimenu>BASE</guimenu>
            <guimenuitem>Other information&hellip;</guimenuitem>
          </menuchoice>
          menu to bring up the other information dialog.
        </para>

          <figure id="webclient.figures.otherinformation">
            <title>Other information</title>
            <screenshot>
              <mediaobject>
                <imageobject><imagedata fileref="figures/other_information.png" format="PNG" /></imageobject>
              </mediaobject>
            </screenshot>
          </figure>


        <helptext external_id="userpreferences.other" title="Other information">
          <para>
            This dialog has three tabs,
            <guilabel>Contact information</guilabel>,
            <guilabel>Password</guilabel> and
            <guilabel>Other information</guilabel>
            (selected).
          </para>
          <para>
            The look of the
            <guilabel>Other information</guilabel>
            tab can differ a bit between different servers, depending on what settings
            the server is installed with. There are three inputs in a fresh BASE
            installation but it is only the
            <guilabel>Description</guilabel>
            text area that is static, the others can be removed or more fields can be
            added (managed by the server administrator). The three fields, included in a
            the BASE installation, are
            <variablelist>
              <varlistentry>
                <term>
                  <guilabel>Mobile</guilabel>
                </term>
                <listitem>
                  <para>Your mobile number(Optional).</para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term>
                  <guilabel>Skype</guilabel>
                </term>
                <listitem>
                  <para>Your Skype contact information(Optional).</para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term>
                  <guilabel>Description</guilabel>
                </term>
                <listitem>
                  <para>
                    Text area where you can put useful information that couldn't
                    be stored anywhere else(Optional).
                  </para>
                </listitem>
              </varlistentry>
            </variablelist>
          </para>
          <para>Press &gbSave; to save the changes or &gbCancel; to abort.</para>
          <seeother>
            <other external_id="userpreferences.contact">Contact information</other>
            <other external_id="userpreferences.password">Change password</other>
          </seeother>
        </helptext>
      </sect2>

      <sect2 id="webclient.configuration.password">
        <title>Changing password</title>
        
        <para>
          Use the <menuchoice><guimenu>BASE</guimenu>
          <guimenuitem>Change password</guimenuitem></menuchoice>
          menu to bring up the change password dialog.
        </para>
        
          <figure id="webclient.figures.changepassword">
            <title>Change password</title>
            <screenshot>
              <mediaobject>
                <imageobject><imagedata fileref="figures/change_password.png" format="PNG" /></imageobject>
              </mediaobject>
            </screenshot>
          </figure>
        
        <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 
              do not 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>BASE</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>Recent items</guilabel>.
        </para>
        
        <sect3 id="webclient.configuration.preferences.appearance">
          <title>The Appearance tab</title>

          <figure id="webclient.figures.appearance">
            <title>The Appearance tab</title>
            <screenshot>
              <mediaobject>
                <imageobject><imagedata fileref="figures/preferences_appearance.png" format="PNG" /></imageobject>
              </mediaobject>
            </screenshot>
          </figure>
          
          <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 pop-up windows.
                This setting exists because different browsers render 
                pages differently. If you often find that pop-up 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>Display long texts</guilabel>
              </term>
              <listitem>
                <para>
                This setting is used to control how long description texts
                are displayed in tables and other places with limited space.
                There are three settings:
                </para>
                <itemizedlist>
                  <listitem>
                    <simpara>
                    <guilabel>Always</guilabel>: The full text is always displayed. This may
                    cause tables, etc. to become hard to read since cells will automatically 
                    grow to be able to display the full text.
                    </simpara>
                  </listitem>
                  <listitem>
                    <simpara>
                    <guilabel>On hover</guilabel>: A short version of the text is
                    displayed and the full text is automatically displayed when
                    the mouse is moved over the text. Texts that are not fully
                    visible are indicated with a dotted line to the right.
                    </simpara>
                  </listitem>
                  <listitem>
                    <simpara>
                    <guilabel>On click</guilabel>: A short version of the text is
                    displayed and the full text is displayed when the mouse is clicked
                    somewhere on the short text. Texts that are not fully visible
                    are indicated with a grey line to the right.
                    </simpara>
                  </listitem>
                </itemizedlist>
                
                <warning>
                  The 'On click' mode may not perform so well if lots of items are
                  displayed in a single list. This is particularly so with Internet
                  Explorer (version 7) which is 5-10 times slower than Firefox to
                  render the page. If you experience problems with this mode you should
                  either use a different mode or display less items on a single page.
                </warning>
                
              </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>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-white-yellow.
                The list of presets contains other useful color combinations
                (for example, the BASE version 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://download.oracle.com/javase/6/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://download.oracle.com/javase/6/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 base number of decimals to display for numerical floating point values.
                The default is 2. This setting is used for values between 1 and 10. For higher
                or lower values, the number of decimals is adapted in order to not loose 
                information (eg. 0.0059 instead of 0.01) or give the impression of very 
                high precision (eg. 135000 instead of 135000.00).
                </para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>
                <guilabel>Dialogs</guilabel>
              </term>
              <listitem>
                <para>
                  Check the <guilabel>Remember positions</guilabel> option
                  to let BASE remember the position and size of dialogs
                  so that they always open in the same place as the last
                  time. The positions are remembered during the current 
                  session only and are forgotten if the browser is closed.
                </para>
              </listitem>
            </varlistentry>
            
            <varlistentry>
              <term>
                <guilabel>Start page</guilabel>
              </term>
              <listitem>
                <para>
                  Select the start page that should be displayed after logging 
                  in to BASE. The default and only built-in start page is the 
                  <menuchoice>
                    <guimenu>BASE</guimenu>
                    <guimenuitem>Home</guimenuitem>
                  </menuchoice>. Other start pages may be enabled by
                  extensions.
                </para>
                
                <note>
                  <title>Problems with the start page</title>
                  <para>
                    If there are problems with the selected start page
                    it may prevent the user from accessing BASE. In
                    the worst scenario all that is displayed is a cryptic
                    error message. In this case, it is good to know that
                    holding down either one of the <guilabel>ALT</guilabel>
                    or <guilabel>CTRL</guilabel> or <guilabel>SHIFT</guilabel>
                    keys while clicking the <guibutton>Login</guibutton>
                    button will force BASE to use the regular start page.
                  </para>
                </note>
                
              </listitem>
            </varlistentry>
            
          </variablelist>
        
          </helptext>
        
        </sect3>
        
        <sect3 id="webclient.configuration.preferences.plugins">
          <title>The Plugins tab</title>
          
          <figure id="webclient.figures.preferences.plugins">
            <title>The Plugins tab</title>
            <screenshot>
              <mediaobject>
                <imageobject><imagedata fileref="figures/preferences_plugins.png" format="PNG" /></imageobject>
              </mediaobject>
            </screenshot>
          </figure>
          
          <helptext external_id="userpreferences.plugins" title="Preferences - Plugins">
          
          <para>
            This tab contains settings that affect plug-in 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 plug-in completes execution. This setting
                can be overridden each time you start a plug-in. You'll
                receive the message as a notification in BASE, but it may 
                also be possible to get the message as an email.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Remove jobs</guilabel>
              </term>
              <listitem>
                <para>
                  This checkbox should be marked if you want the jobs, done by
                  import or export plug-ins, to be marked as removed if they
                  finished successfully. This setting can be overridden each time
                  you start a plug-in.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Show warnings</guilabel>
              </term>
              <listitem>
                <para>
                  This checkbox should be marked if you want to show warning
                  messages from plug-ins in the <guilabel>Select plug-in</guilabel>
                  dialog. Warning-level messages usually originates from plug-ins
                  that are unrelated to the current task and are only of interest to
                  plug-in developers. Error messages that are related to the
                  current task are always shown.
                </para>
              </listitem>
            </varlistentry>
          </variablelist>
          </helptext>
          
        </sect3>
        
        <sect3 id="webclient.configuration.preferences.mostrecent">
          <title>The Recent items tab</title>
          
          <figure id="webclient.figures.preferences.recentitems">
            <title>The Recent items tab</title>
            <screenshot>
              <mediaobject>
                <imageobject><imagedata fileref="figures/preferences_recentitems.png" format="PNG" /></imageobject>
              </mediaobject>
            </screenshot>
          </figure>
          
          <helptext external_id="userpreferences.mostrecent" 
            title="Preferences - Recent items">
          
          <para>
            This tab contains settings that affect the <guilabel>Recent
            items</guilabel> menu and selection lists in many edit dialogs. 
          </para>
          
          <variablelist>
          <varlistentry>
            <term>
              <guilabel>Recently viewed items</guilabel>
            </term>
            <listitem>
              <para>
              The number of recently <emphasis>viewed</emphasis> items to remember. 
              The default is to remember 6 items. The remembered items
              will be displayed in the <guilabel>Recent items</guilabel>
              menu in the menu bar.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <guilabel>Recently used items</guilabel>
            </term>
            <listitem>
              <para>
              The number of recently <emphasis>used</emphasis> items to remember.
              The default is to remember 4 items. The remembered items will
              be displayed in edit dialogs where they have been used before.
              Each type of edit operation has it's own list of remembered items.
              For example, there is one list that remembers the most recently used
              protocols when creating a sample, and there is another list that
              remembers the most recently used scanners when creating a scan.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>
              <guilabel>Load the names of all items</guilabel>
            </term>
            <listitem>
              <para>
              If checked, the names of the items will be loaded and
              displayed in the menu, otherwise only the ID and type of item
              is displayed.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>
              <guilabel>Sticky items</guilabel>
            </term>
            <listitem>
              <para>
              Always remember the last viewed item of the selected types.
              For example, if you have selected <emphasis>Experiment</emphasis>
              as a sticky item, the last viewed experiment will be remembered
              even if you view hundreds of other items. Use the arrow buttons
              to move item types between the lists and sort the sticky items list.
              Sticky items will be displayed in the <guilabel>Recent items</guilabel>
              menu in the menu bar.             
              </para>
            </listitem>
          </varlistentry>
          </variablelist>
          </helptext>
          
        </sect3>

        <sect3 id="webclient.configuration.preferences.roles">
          <title>The Inactive roles tab</title>
          
          <figure id="webclient.figures.preferences.roles">
            <title>The Inactive roles tab</title>
            <screenshot>
              <mediaobject>
                <imageobject><imagedata fileref="figures/preferences_roles.png" format="PNG" /></imageobject>
              </mediaobject>
            </screenshot>
          </figure>
          
          <helptext external_id="userpreferences.inactiveroles" 
            title="Preferences - Inactive roles">
          
          <para>
            <nohelp>
              <inlinemediaobject>
                <imageobject>
                  <imagedata fileref="figures/preferences_roles_menu.png" format="PNG" align="right"/>
                </imageobject>
              </inlinemediaobject>
            </nohelp>
            With this tab you can control which roles that
            are active or inactive after logging in.
            This is, for example, useful if you have a power user 
            role that is rarely needed. Setting that role as 
            <guilabel>Inactive at login</guilabel> prevents
            you from accidentally do things by mistake. When you need
            the full power user role, it can easily be
            activated from the popupmenu you get when clicking on your own
            name in the upper right corner.
          </para>
          
          <variablelist>
          <varlistentry>
            <term>
              <guilabel>Default roles - Inactive at login</guilabel>
            </term>
            <listitem>
              <para>
              All roles that you have been assigned are listed here.
              Put a checkbox before those roles that should not be
              active after logging in. Note that the settings only
              apply when using the web client. Logging in via
              other means (for example the FTP server) always
              enables all assigned roles.
              </para>
            </listitem>
          </varlistentry>
          </variablelist>
          </helptext>
          
        </sect3>
      </sect2>
  
    </sect1>
    
    <sect1 id="webclient.items">
      <?dbhtml filename="items.html" ?>
      <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 
        <menuchoice>
          <guimenu>Biomaterial LIMS</guimenu>
          <guimenuitem>Samples</guimenuitem>
        </menuchoice>
        to work with samples, and 
        <menuchoice>
          <guimenu>View</guimenu>
          <guimenuitem>Experiments</guimenuitem>
        </menuchoice>
        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. 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. See <xref linkend="webclient.itemlist"/> for more information.
            </para>
          </listitem>
        </varlistentry>
      
        <varlistentry>
          <term>Single-item view</term>
          <listitem>
            <para>
            Displays information about a single item. For some items it is very little,
            but for some 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 pop-up window. Quite often the popup has
            multiple tabs, but the most important information is found on the
            first tab. Information that is required is always found on the
            first tab.
            </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 &gbNew; button in the
          toolbar. The button is disabled if you do not have permission to create new experiments. 
          Otherwise, click on it and enter any required information in the pop-up 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 &gbSave; button to save the new
          item to the database or on the &gbCancel; 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 does not
            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 
            <guilabel>Recently used items</guilabel> setting (default is 4),
            allowing you to quickly select one of those protocols. 
            <xref linkend="webclient.configuration.preferences.mostrecent" /> 
            contains more information about the setting.
            </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 &gbEdit;
          button in the toolbar that opens a pop-up dialog for editing the properties
          of the item. This button is disabled if the logged in user does not have
          write permission for the item.
        </para>
        
        <para>
          You can also open the edit pop-up 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 pop-up. 
          If you do not have write permission
          on the item there is no meaning to open the edit pop-up and you will 
          be taken to the single-item view page instead.
        </para>

        <para>
          Click on the &gbSave; button to save the changes
          to the database or on the &gbCancel; 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, deleted items are only moved to
          the trashcan. No information is removed from the database. This allows
          you to restore items if you later find out that you need them 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 items from the database you have two options:
          <orderedlist>
          <listitem>
            <para>
            Go to the trashcan 
            <menuchoice><guimenu>View</guimenu><guimenuitem>Trashcan</guimenuitem></menuchoice>
            and delete it from there. From the trashcan you can delete several items
            in one go. See <xref linkend="webclient.trashcan"/>.
            </para>
          </listitem>
          <listitem>
            <para>
            Click on the small trashcan icon in the list or single-item view. 
            You can only delete one item at a time.
            </para>
          </listitem>
          </orderedlist>
          </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 &gbDelete; 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 
          &gbDelete; button in the toolbar. The page will refresh
          itself automatically and a small trashcan icon should be displayed.
          If you do not 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 is described in
          <xref linkend="webclient.trashcan"/>.
        </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 &gbRestore; 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 
          &gbRestore; button in the toolbar. The page will refresh
          itself automatically and the small trashcan icon should be gone.
          If you do not 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
          follow 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
          according to the settings of 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 &gbShare; button.
          If you are on a single-item page, click on the &gbShare; 
          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" />
            </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>A</guilabel> = Annotate</simpara> (only visble if sharing items that are annotatable)</listitem>
                <listitem><simpara><guilabel>W</guilabel> = Write</simpara></listitem>
                <listitem><simpara><guilabel>D</guilabel> = Delete</simpara></listitem>
                <listitem><simpara><guilabel>O</guilabel> = Set owner</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>
                
                <para>
                  The <guilabel>Permission templates</guilabel> part of the list
                  is always empty to begin with.
                </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 change to indicate the current permissions. 
                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>
                <para>
                The permission boxes are disabled if a permission template
                is selected. The permissions are already part of the template
                and can't be changed here.
                </para>
              </listitem>
            </varlistentry>           

            <varlistentry>
              <term><guibutton>Add users</guibutton></term>
              <listitem>
                <para>
                Opens a pop-up window that allows you to select
                users to share the items to. In the pop-up window, mark
                one or more users and click on the &gbOk;
                button. The pop-up window will only list users that you have
                permission to read. Unless you are an administrator, this
                usually means that you can only see users that: 
                </para>
                <itemizedlist>
                  <listitem>
                    <para>
                    you share group memberships with  (the <emphasis>Everyone</emphasis> 
                    group or groups with hidden members doesn't count)
                    </para>
                  </listitem>
                  <listitem>
                    <para>
                    are members of the currently active project, if any.
                    </para>
                  </listitem>
                </itemizedlist>
                <para>
                Users that already have access to the item are not included in the
                list. If you don't see a user that you want to share an item to,
                you'll need to talk to an administrator for setting up the proper
                group membership.
                </para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><guibutton>Add groups</guibutton></term>
              <listitem>
                <para>
                Opens a pop-up window that allows you to select
                groups to share the items to. In the pop-up window, mark
                one or more groups and click on the &gbOk;
                button. Unless you are an administrator, the pop-up window 
                will only list groups where you are a member. It will not list
                groups that already have access to the items. The
                <emphasis>Everyone</emphasis> groups is normally not visible unless
                have a specific permission to share items with this group.
                </para>
              </listitem>
            </varlistentry>
            
            <varlistentry>
              <term><guibutton>Add projects</guibutton></term>
              <listitem>
                <para>
                Opens a pop-up window that allows you to select
                projects to share the items to. In the pop-up window, mark
                one or more projects and click on the &gbOk;
                button. Unless you are an administrator, the pop-up 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>Templates</guibutton></term>
              <listitem>
                <para>
                Opens a pop-up window that allows you to select 
                permission templates. In the pop-up window, mark
                one or more templates and click on the &gbOk;
                button. Unless you are an administrator, the pop-up window 
                will only list templates that you are allowed to use. It will 
                not list templates that have already been added.
                </para>
                
                <note>
                  <para>
                  The permissions from the selected templates are <emphasis>copied</emphasis>
                  to the items when the access permissions are saved. If you re-open the share dialog,
                  the actual permissions are shown and the permission templates 
                  section is empty. Modifying the permission template later doesn't 
                  affect the permissions on existing items. See <xref linkend="project_permission.templates" /> 
                  for more information about permission templates.
                  </para>
                </note>
                
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>&gbRemove;</term>
              <listitem>
                <para>
                Click on this button to revoke access permissions from
                the selected users, groups and projects.
                </para>
              </listitem>   
            </varlistentry>
            
            <varlistentry>
              <term><guilabel>Apply permissions to all sub-directories and their files</guilabel></term>
              <listitem>
                <para>
                This option shows up if at least one of the selected items
                is a directory. If this option is selected the permissions given
                to the directory will recursively be copied to all files and 
                sub-directories. Existing permissions on those items will be
                overwritten with the new permissions.
                </para>
              </listitem>   
            </varlistentry>
          </variablelist>
        
          <para>
            Use the &gbSave; button to save your
            changes or the &gbCancel; button to
            close the pop-up without saving.
          </para>
        </helptext>

      </sect2>

      <sect2 id="webclient.items.changeowner">
        <title>Change owner of items</title>
        <para>
          Sometimes it may be necessary to change the owner of an item.
          This can be done by everyone with <emphasis>Set owner</emphasis>
          permission on the item.
          For a user to have the rights to change owner of an item, the item must 
          either be owned by or shared with <emphasis>Set owner</emphasis> 
          permission to the user . 
          See <xref linkend="webclient.items.share" />.
        </para>
        
        <para>
          An user with <emphasis>Set owner</emphasis> permission can go to a list view 
          (or the single-item view), mark the checkboxes for the items to change owner of, 
          and click on the <guibutton>Set owner</guibutton> button.  
          A dialog window, like the screen-shot below, will appear.
        </para>
        <helptext external_id="ownership.configure" title="Change owner">
        <variablelist>
        <varlistentry>
          <term><guilabel>New owner</guilabel></term>
          <listitem>
          <para>
            The user to be the new owner of selected item(s).
            By default the current user will be selected but other
            users can be picked from the <emphasis>currently used</emphasis> part of the drop-down 
            list or by clicking on <guibutton>Select</guibutton>.
          </para>
          </listitem>
        </varlistentry>
        </variablelist>
        <para>
          Use the &gbSave; button to set the new owner
          or the &gbCancel; button to
          close the pop-up without saving.
        </para>
        </helptext> 
        <figure id="webclient.figures.selectowner">
          <title>Select a new owner</title>
          <screenshot>
            <mediaobject>
              <imageobject><imagedata fileref="figures/select_owner.png" format="PNG"
                scalefit="1" width="100%" /></imageobject>
            </mediaobject>
          </screenshot>
        </figure>
        
        <warning>
          <para>
          If you are the original owner of the items, you should be aware of that
          after the change you may no longer have access to the items. If you
          make a mistake you may have to talk to an administrator to correct it.
          </para>
        </warning>
        
      </sect2>
      
    </sect1>
    
    <sect1 id="webclient.itemlist">
      <?dbhtml filename="lists.html" ?>
      <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 menu 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.
      </para>

      <tip>
        An example of a list page that can list
        items of several types is found by going to 
        <menuchoice>
          <guimenu>View</guimenu>
          <guimenuitem>All items</guimenuitem>
        </menuchoice>.
        This page lists all items that you are the owner of. It has a few limitations:
        
        <itemizedlist>
          <listitem>
            <para>
              It support only a limited set of columns (id, item type, name and description) 
              since these are the only properties that are common among all items. It is also
              possible to display sharing information.
            </para>
          </listitem>
          
          <listitem>
            <para>
              The list may have not have full support for filtering and
              sorting. This is due to a limitation in the 
              query system used to generate the list.
            </para>
          </listitem>
        </itemizedlist>
        
        <para>
          There are also several similarities:
        </para>
        
        <itemizedlist>
          <listitem>
            <para>
              It supports all of the regular multi-item 
              operations such as delete, restore, share
              and change owner.
            </para>
          </listitem>
          
          <listitem>
            <para>
              Clicking on the name of the item will take you to the
              single-item view of that item. Holding down <keycap>CTRL</keycap>, 
              <keycap>ALT</keycap> or <keycap>SHIFT</keycap> while clicking,
              will open the edit pop-up.
            </para>
          </listitem>
        </itemizedlist>       
        
      </tip>
      
      <figure id="webclient.figures.listpage">
        <title>A typical list page</title>
        <screenshot>
          <mediaobject>
            <imageobject><imagedata fileref="figures/listpage.png" format="PNG"
              scalefit="1" width="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
            &gbNew; for creating a new item, 
            &gbDelete; 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 do not 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. Use the <guiicon>
                  <inlinemediaobject>
                    <imageobject>
                      <imagedata fileref="figures/add.png" format="PNG" />
                    </imageobject>
                  </inlinemediaobject>
                </guiicon> icon to add more filter rows.
            </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 cannot 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 character 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>
          If you want to filter on several values at the same time, separate the 
          values in the filter input box with the <quote>|</quote> character.
          For example, a filter text like <informalexample>Experiment A|C%</informalexample>
          matches both <quote>Experiment A</quote> and values  
          that begin with <quote>C</quote>.
        </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). Supports
                filtering on more then one 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). Supports
                filtering on more then one value.
              </simpara>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><keycap>==</keycap></term>
            <listitem>
              <simpara>
                Same as <keycap>=</keycap> but interprets <quote>|</quote>, <quote>%</quote> 
                and other special characters literally. Use this when you need an exact 
                string match.
              </simpara>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><keycap>&gt;&lt;</keycap></term>
            <listitem>
              <simpara>
                Within a range. Two values separated by <quote>|</quote> are required.
                For example, <code>&gt;&lt;10|20</code> to find values between 10 
                and 20 (inclusive).
              </simpara>
            </listitem>
          </varlistentry>
        </variablelist>
        
        <variablelist id="webclient.itemlist.filter.special">
          <title>Other special characers used by the free-text filter</title>
          <varlistentry>
            <term><keycap>¤</keycap></term>
            <listitem>
              <simpara>Can be used as a suffix in annotation columns where
              the annotation type supports project-specific annotations. 
              When present, the filter will only match items that:
              
              <orderedlist>
                <listitem>
                Has a default value (can be any value).
                </listitem>
                <listitem>
                Has a project-specific annotation that matches the filter.
                </listitem>
              </orderedlist>
              <informalexample>=10¤</informalexample> matches items that
              have a default value (any) and a project-specific annotation
              with the value 10.
              <informalexample>&lt;&gt;¤</informalexample> matches 
              all items that has a project-specific value overriding the 
              default.
              </simpara>
              
              <note>
                Just because an item has a project-specific annotation
                there is no guarantee that the value is actually different
                from the default value.
              </note>
              
            </listitem>
          </varlistentry>
        </variablelist>
        
        <sect3 id="webclient.itemlist.filter.extending">
          <title>Extending the search with multiple filter rows</title>
          <para>
          Most list pages allows you to add more than one filter row by clicking on the 
            <guiicon>
              <inlinemediaobject>
                <imageobject>
                  <imagedata fileref="figures/add.png" format="PNG" />
                </imageobject>
              </inlinemediaobject>
            </guiicon> icon at the start of the row. Each filter row is an independent filter set
            that extends the search result with more items (eg. it is logically equivalent to an OR 
            condition). 
          </para>
          
          <para>
            Use the
            <guiicon>
              <inlinemediaobject>
                <imageobject>
                  <imagedata fileref="figures/remove.png" format="PNG" />
                </imageobject>
              </inlinemediaobject>
            </guiicon> icon to remove an existing filter row.
          </para>
        </sect3>
        
        <sect3 id="webclient.itemlist.filter.units">
          <title>Units</title>
          <para>
            Some (numeric) columns have values with units. There are, for example,
            the <emphasis>Original quantity</emphasis> and <emphasis>Remaining quantity</emphasis>
            columns for biomaterials, which have values in micrograms (µg), and 
            annotations which may have any unit.
          </para>
          <para>
            When filtering on a column that has a unit, numeric values without units are
            interpreted as the default unit for that column. But it is also possible to
            add a unit to the filter value. The examples below are filtering on the
            original quantity column of a biomaterial:
          </para>
          <para>
            <informalexample>&gt;=0.5mg</informalexample> matches biomaterials with
            an original quantity &gt;=500µg.
          </para>
          <para>
            <informalexample>=100|200|300µg</informalexample> matches biomaterials with
            exactly 100, 200 or 300 micrograms.
          </para>
          <para>
            It is also possible to mix units in a single filter:
            <informalexample>=100|200|300µg|0.5|1mg</informalexample> which matches
            100, 200, 300, 500 and 1000 micrograms.
          </para>
          
          <warning>
            <title>Be aware of rounding errors</title>
            <para>
              All filter values with a unit that is different from the default
              unit are converted to the default unit before being applied. Since
              numeric conversions are never exact down to the last decimal, this may 
              result in problems to filter with an exact match. The last example above
              could, for example, be converted to: 100, 200, 300, 500.000001 and
              999.99999998.
            </para>
          </warning>
          
          <tip>
            <title>Hard-to-type characters</title>
            <para>
              Some units contains hard-to-type characters. For example,
              the greek letter µ in µg, and m² and m³ for areas and volumes.
              In all those cases it is also possible to use ug, m2 and m3, 
              respectively.
            </para>
          </tip>
          
          <note>
            <title>Units are case-sensitive</title>
            <para>
              All units are case sensitive. The main reason for this is that
              it must be possible to tell the difference between 
              <emphasis>milli (m)</emphasis> and <emphasis>mega (M)</emphasis> 
              prefixes, for example, <emphasis>mJ</emphasis> and <emphasis>MJ</emphasis>.
            </para>
          </note>
          
        </sect3>
      </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. There are several ways to change
          which columns that are visible and in which order.
        </para>
        
        <itemizedlist>
          <listitem>
            <para>
              Right-click on any column header. This will bring up a
              context-sensitive menu containing all possible columns.
              Select a column in the menu to show it. It will be inserted 
              right after the column that was right-clicked.
              If the selected column is already visible it is hidden instead.
            </para>
          </listitem>
          
          <listitem>
            <para>
              When hovering with the mouse inside a column header, an
              <guilabel>×</guilabel> is displayed in the top right
              corner. Click the <guilabel>×</guilabel> to hide the column.
            </para>
          </listitem>
          
          <listitem>
            <para>
              It is possible to drag columns to change their order.
              When hovering with the mouse inside a column header,
              left-click the mouse and hold it. Move the mouse 
              to another column either to the left or right and release
              the mouse button. The dragged column is moved to the location
              indicated by the black vertical bar.
            </para>
          </listitem>

          <listitem>
            <para>
              Use the <guibutton>Columns&hellip;</guibutton> button to open 
              a dialog (see below) that allows you to select which columns to show
              and the order in which they are shown. This is the most
              powerful way to configure the columns and includes the possibility
              to save a certain configuration as a preset.
            </para>
          </listitem>
        </itemizedlist>
          
        <figure id="webclient.figures.configure_columns">
          <title>Configuring which columns to show</title>
          <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata 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 cannot 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>Sticky column</guilabel></term>
          <listitem>
            <para>
              In most lists one column can be selected to be <emphasis>sticky</emphasis>,
              which means that it will always be visible and stick to either the left or right
              side of the browser window when scrolling would take outside the visible area.
              In most lists the <guilabel>Name</guilabel> column is the default sticky
              column.
            </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 only affects the visible columns
              and not filters or sort order.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><guilabel>Add inherited annotations...</guilabel></term>
          <listitem>
            <para>
              Used for adding columns representing annotations that are inherited from parent items.
              Since a system may define a lot of different annotation types, there are no pre-defined
              columns that represent inherited annotations. Clicking on the buttons opens a
              dialog that allows you to select any annotation type that you have access to. Selected
              columns will be marked with <guilabel>[I]</guilabel> after their names.
            </para>
            
            <note>
              <title>Not all items can inherit annotations</title>
              <para>
                This functionality is of course only available in lists that display
                item that can inherit annotations. For more information about
                inheriting annotations see <xref linkend="annotations.inheriting" />.
              </para>
            </note>
            
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><guilabel>Add parent or child item columns...</guilabel></term>
          <listitem>
            <para>
              This function can be used to add columns that display data from
              a parent or child items. The function is enabled for biosources,
              samples, extracts, and the physical, derived and raw bioassays,
              and requires that items are classified with a subtype. 
            </para>

          </listitem>
        </varlistentry>

        </variablelist>
        
          <para>
            Use the &gbSave; button to apply your
            changes or the &gbCancel; button to
            close the pop-up without saving.
          </para>
          
          <seeother>
            <other external_id="columns.configure.add_relateditem_column"
              >Add parent or child item columns</other>
          </seeother>

        </helptext>

      </sect2>
      
      <sect2 id="webclient.itemlist.relateditem-columns">
        <title>Parent and child item columns</title>
        
        <figure id="webclient.figures.configure_relateditem_columns">
          <title>Add parent and child item columns</title>
          <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/configure_relateditems_columns.png" format="PNG"/>
            </imageobject>
          </mediaobject>
          </screenshot>
        </figure>
        
        <helptext external_id="columns.configure.add_relateditem_column" 
          title="Add parent and child item columns">
        
        <variablelist>
        <varlistentry>
          <term><guilabel>Item type</guilabel></term>
          <listitem>
            <para>
              Select the main item type of the parent or child items. This list
              will have different options depending on the current context.
            </para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><guilabel>Subtype</guilabel></term>
          <listitem>
            <para>
              This list will automatically be updated with all available subtypes
              for the selected main item type. It is not possible to select items
              without a subtype.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><guilabel>Column</guilabel></term>
          <listitem>
            <para>
              Once the subtype has been selected, this list will display all possible
              columns that can be added to the table. Most regular properties such as
              <guilabel>Name</guilabel> and <guilabel>Registration date</guilabel>
              can be selected, as well as all annotation types that has been defined
              and linked to the selected subtype (marked with <guilabel>[A]</guilabel>).
            </para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><guilabel>Show annotations for all subtypes</guilabel></term>
          <listitem>
            <para>
              By default, only annotations that are linked to the
              selected subtype are included in the list. Enable this option
              to include all annotations that are enabled for the 
              selected main item type.
            </para>
          </listitem>
        </varlistentry>

        </variablelist>
        
          <para>
            Use the <guibutton>Add</guibutton> button to add columns to the table. 
            It is possible change the main item type and subtype to add more columns.
            When you are done, use the &gbClose; button to close the dialog.
          </para>
        
          <note>
            <title>Limitations for parent and child item columns</title>
            <para>
              While it is possible to display and filter by the values from the
              parent and child items, it is not possible to use them for sorting.
              This is because the values are not loaded immediately together with
              the rest of the table. Instead, there are placeholders that will be
              filled with values later. This is usually quick, but may take several
              seconds depending on the amount of intermediate steps between the
              parent and child items.
            </para>
          </note>
        
        </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" float="right">
          <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 configure columns dialog box, described in 
                  <xref linkend="webclient.itemlist.columns"/>.</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 does not 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 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 &gbOk; button to save the preset
            or the &gbCancel; button to
            close the pop-up 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 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 cannot be undone. Unlike other
            items, the presets are not moved to the trashcan. Click on
            &gbOk; 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 &gbClose; button to
            close the pop-up.
          </para>
          
          
          </helptext>
          
        </sect3>
        
      </sect2>
    </sect1>


    <sect1 id="webclient.trashcan">
      <?dbhtml filename="trashcan.html" ?>
      <title>Trashcan</title>
      <para>
        All items that have been deleted, and are owned by you, are
        listed in your trashcan. This list page is accessed with
        <menuchoice>
          <guimenu>View</guimenu>
          <guimenuitem>Trashcan</guimenuitem>
        </menuchoice>
        and it differs a bit from the other common list pages. The
        most significant difference is that the trashcan page can
        contain more then one item type, actually all removable item
        types in BASE can be listed in the trashcan. Items that neither
        can be removed or deleted, <emphasis>i.e.,</emphasis> items
        like sessions, nor clients' help texts since these are deleted
        from the database immediately in list/item view will be shown
        in the trashcan page.
      </para>
      <warning>
        <para>
          Some item types do not have any owner and these are listed
          in the trashcans for everyone with delete permission on that
          specific item type.
        </para>
      </warning>

      <para>
        Things that the trashcan page have in common with other list
        pages are the possibility to restore and view/edit items, see
        <xref linkend="webclient.items.restore" /> and
        <xref linkend="webclient.items.edit" /> . If an item is
        restored, it will of course disappear from the trashcan.
      </para>

      <sect2 id="webclient.trashcan.deleteitem">
        <title>Delete items permanently</title>
        <para>
          Items can be permanently deleted from BASE only if they are
          not used by other items.  Items that are used have the icon
          <inlinemediaobject>
            <imageobject>
              <imagedata fileref="figures/used.png" format="PNG" />
            </imageobject>
          </inlinemediaobject>
          in the first column and by clicking on it you can get more
          information about the dependencies, see
          <xref linkend="webclient.trashcan.viewdependencies" /> .
          <note>
            <simpara>
              This view is NOT the same view page as when clicking on
              the item's name, which brings you to the item's view
              page.
            </simpara>
          </note>
        </para>
        <para>
          To delete one or several items permanently from the trashcan
          you first have to select them and then to click on the
          &gbDelete; button. Press then on either &gbOk; (completes
          the deletion) or &gbCancel; (no items will be deleted) in
          the dialog window that appears.
        </para>

        <sect3 id="webclient.trashcan.deleteitem.empty">
          <title>Empty trashcan</title>
          <para>
            If all items in the trashcan should be deleted permanently
            the <guibutton>Empty trash</guibutton> button can be
            used. This function will remove all items that are listed
            in your trashcan, except those items which other items,
            not marked for deletion or cannot be deleted, are
            dependent on.
          </para>
        </sect3>
      </sect2>

      <sect2 id="webclient.trashcan.viewdependencies">
        <title>View dependencies of a trashed item</title>
        <helptext external_id="trash.view.properties" title="Properties for a trashed item">
          <para>
            This view can only be accessed from trashed items that are
            linked together with other items. Beside the item's
            <guilabel>item type</guilabel>, <guilabel>name</guilabel>,
            and <guilabel>description</guilabel> there is a list at
            the bottom of the view page with those items that are
            using the current item in some way.
          </para>
        </helptext>
        <para>
          <nohelp>
            <figure id="webclient.trashcan.figures.viewtrasheditem">
              <title>Item view of a trashed item.</title>
              <screenshot>
                <mediaobject>
                  <imageobject>
                    <imagedata fileref="figures/trashview.png" format="PNG" 
                               scalefit="1" width="100%" />
                  </imageobject>
                </mediaobject>
              </screenshot>
            </figure>
          </nohelp>
          <orderedlist>
            <listitem>
              <para>
                This icon indicates that the item cannot be deleted
                permanently cause of some dependencies, listed below.
              </para>
            </listitem>
            <listitem>
              <para>Common properties for all removable items.</para>
            </listitem>
            <listitem id="webclient.trashcan.lists.dependentitem3">
              <para>
                A list of other items that are using the current item, 
                blocking permanent removal.
              </para>
            </listitem>
          </orderedlist>
        </para>
      </sect2>
    </sect1>
    
  <sect1 id="webclient.itemoverview">
    <?dbhtml filename="itemoverview.html" ?>
    <title>Item overview</title>

    <helptext external_id="item.overview" 
      title="Item overview">
    
    <para>
      With the <guilabel>Item overview</guilabel> 
      function you can get an overview of all bioassays,
      extracts, samples, annotations, raw data sets, etc. that are
      related to a given item. In the overview you can also validate
      the data to find possibly missing or incorrect information.
    </para>
    
    <nohelp>
    <para>
      You can access the overview for an item by navigating
      to the single-item view of the item you are interested in.
      Then, switch to the <guilabel>Overview</guilabel> tab that
      is present on that page. Here is an example of what is displayed:
    </para>
    
    <figure id="webclient.figures.itemoverview">
      <title>The item overview</title>
      <screenshot>
        <mediaobject>
          <imageobject><imagedata 
            scalefit="1" width="100%"
            fileref="figures/item_overview.png" format="PNG"
            /></imageobject>
        </mediaobject>
      </screenshot>
    </figure>
    </nohelp>
    
    <para>
      The page is divided into three sections:
    </para>
    
    <itemizedlist>
      <listitem>
        <para>
        To the left is a tree displaying items that are related 
        to the current item. The tree is loaded gradually when 
        you click your way through the sublevels. 
        The only exception is after a validation has been done, 
        in this case the whole tree is loaded through the validation-process.               
        </para>
      </listitem>
      
      <listitem>
        <para>
        The lower right shows a list of warnings and error
        messages that was found when validating the data.
        This section is empty if no validation has been done. 
        Click on the <guibutton>Validate</guibutton> button 
        to validate the data and load errors and warnings.        
        <nohelp>
          In the example you can see that we have failed to 
          specify a value for the <guilabel>Temperature</guilabel> 
          protocol parameter for one of the samples. 
        </nohelp> 
        </para>
      </listitem>
        
      <listitem>
        <para>
          The upper right shows information about the
          currently selected item in the tree. This part will also
          contain more information about errors or warnings for this
          item, but only if a validation has been done. 
          It may also present you with one or more suggestions
          about how to fix the problem and with a link that
          takes you to the most probable location where you can fix
          the error or warning.
        </para>
        
      </listitem>
        
    </itemizedlist>
    
    <seeother>
      <other external_id="item.overview.validationoptions"
        >Validation options</other>
      <other external_id="item.overview.fixfailures"
        >How to fix validation failures</other>
    </seeother>
    
    </helptext>
    
    <sect2 id="webclient.itemoverview.validationoptions">
      <title>Validation options</title>
      <para>
        Click on the <guibutton>Validation options</guibutton>
        button in the toolbar to open the <guilabel>Validation
        options</guilabel> dialog.
      </para>
      
      <figure id="webclient.figures.validationoptions">
        <title>Validation options</title>
        <screenshot>
          <mediaobject>
            <imageobject><imagedata 
              fileref="figures/validation_options.png" format="PNG"
              /></imageobject>
          </mediaobject>
        </screenshot>
      </figure>         
      
      <helptext external_id="item.overview.validationoptions" 
        title="Validation options">
        <para>
          The validation procedure is highly 
          configurable and you can select what you want to
          ignore, and what should be displayed as an error
          or warning.
        </para>
        
        <variablelist>
          <varlistentry>
            <term>
            <guilabel>Presets</guilabel></term>
            <listitem>
              <para>
              The list contains predefined and
              user defined validation options.
              Use the <guibutton>Save as&hellip;</guibutton>
              button to save the current options as a user defined
              preset. The <guibutton>Remove&hellip;</guibutton>
              button is used to remove the currently selected
              preset. Predefined presets cannot be deleted.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term><guilabel>Project defaults</guilabel></term>
            <listitem>
              <para>
              The options in this section are used to check
              if your experiment uses the same values as set
              by the project default values of the currently active
              project<nohelp>
              (see <xref linkend="project_permission.projects" />)</nohelp>. 
              If no project is active these options are ignored. 
              The validation is only performed if the project has at least one
              item with a matching type. For example, if no default array 
              design has been added to the project, all array designs
              are allowed. For items that can have a subtype, the 
              subtype is also considered. For example, if only a default
              sampling protocol has been selected, no warnings are
              generated for extraction protocols.
              </para>
            </listitem>
            
          </varlistentry>
          
          <varlistentry>
            <term><guilabel>Missing items</guilabel></term>
            <listitem>
              <para>
              The options in this section are used to check if
              you have specified values for optional items. 
              For example, there is an option that warns you if 
              you have not specified a protocol. For items that
              can have a subtype, the rule here is to use the information 
              about related subtypes before reporting a missing item.
              For example, the <emphasis>labeled extract</emphasis>
              subtype is related to the <emphasis>label</emphasis>
              subtype and if a label is missing it is reported as a
              warning. If there is no related subtype no warning is
              generated.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term><guilabel>Subtypes</guilabel></term>
            <listitem>
              <para>
              The options in this section are used to check that related items 
              have a subtype that matches the subtype of the main item. For example, 
              if we have an <emphasis>extract</emphasis>
              which is a <emphasis>labeled extract</emphasis> subtype the subtype for 
              the related tag should be <emphasis>label</emphasis>, but if the extract
              is a <emphasis>library</emphasis> the subtype of the tag should be 
              <emphasis>barcode</emphasis>.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><guilabel>Annotations</guilabel></term>
            <listitem>
              <para>
              The options in this section are used to check 
              problems related to annotations. The most
              important ones are listed here:
              </para>
              
              <itemizedlist>
              <listitem>
                <simpara>
                <emphasis>Missing MIAME annotation value</emphasis>:
                Checks that you have specified values
                for all annotations marked as 
                <guilabel>Required for MIAME</guilabel>.
                </simpara>
              </listitem>
              
              <listitem>
                <simpara>
                <emphasis>Missing factor value</emphasis>:
                Checks that you have specified values for
                all annotations used as experimental factors in
                the experiment. This is only checked when an experiment
                is selected as the root item.
                </simpara>
              </listitem>
              
              <listitem>
                <simpara>
                <emphasis>Missing parameter value</emphasis>:
                Checks that you have specified values
                for all protocol parameters.
                </simpara>
              </listitem>

              <listitem>
                <simpara>
                <emphasis>Annotation is protocol parameter</emphasis>:
                Checks if an item has been annotated with a 
                an annotation that is actually a protocol parameter.
                </simpara>
              </listitem>

              <listitem>
                <simpara>
                <emphasis>Annotation has invalid value</emphasis>:
                Checks if annotation values are correct with 
                respect to the rules given by the annotation type.
                This might include numeric values that are outside 
                the valid range, or values not in the list
                of allows values for an enumerated annotation type.
                </simpara>
              </listitem>

              <listitem>
                <simpara>
                <emphasis>Inheriting annotation from non-parent</emphasis>:
                Checks if inherited annotations really comes from a
                parent item. This might happen if you rearrange 
                parent-child relationship because you found that
                they were incorrectly linked.
                </simpara>
              </listitem>
              </itemizedlist>
              
            
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term><guilabel>Files</guilabel></term>
            <listitem>
              <para>
              The options in this section are related to the validity of 
              data files that can be attached to some items, for example,
              raw bioassays and array designs. The data files are usually
              validated immediately when they are used and the result is saved
              to the database. The options in this dialog can be used to find
              (or ignore) problems with data files.
              </para>
            </listitem>
          </varlistentry>

          
          <varlistentry>
            <term><guilabel>Denied access</guilabel></term>
            <listitem>
              <para>
              The options in this section are used to
              check if you do not have access (read permission)
              to an item in the experiment hierarchy. If this 
              happens the validation cannot proceed in that branch.
              This might mask other validation problems.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term><guilabel>Link consistency</guilabel></term>
            <listitem>
              <para>
              The options in this section are used to check
              that links between (multiple) items are consistent
              with each other. The most
              important options are:
              </para>

              <itemizedlist>
                <listitem>
                  <simpara>
                  <emphasis>Array design mismatch</emphasis>:
                  Checks if the array design specified for
                  a raw bioassay is the same array design
                  specified for the physical bioassay.
                  </simpara>
                </listitem>
                
                <listitem>
                  <simpara>
                  <emphasis>Multiple array designs</emphasis>:
                  Checks if all raw bioassays in an experiment 
                  use the same array design or not. This is only
                  checked when the root item is an experiment.
                  </simpara>
                </listitem>
                
                <listitem>
                  <simpara>
                  <emphasis>Circular reference to pooled item</emphasis>:
                  If you have used pooling, checks that no 
                  circular references have been created.
                  </simpara>
                </listitem>
                
                <listitem>
                  <simpara>
                  <emphasis>Multiple extracts with same tag+position</emphasis>:
                  Checks if the extracts on a physical bioassay have a
                  unique combination of tag+position. This is usually 
                  required to be able to assign measured data correctly 
                  downstreams.
                  </simpara>
                </listitem>
                
              </itemizedlist>

            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term><guilabel>Other</guilabel></term>
            <listitem>
              <para>
              This section collects options that does not fit
              into any of the other sections. The most
              important options are:
              </para>
              
              <itemizedlist>
                <listitem>
                  <simpara>
                  <emphasis>Non-unique name</emphasis>:
                  Checks if two items of the same type
                  have the same name. It is usually a good idea to
                  have unique names within an experiment if the data is
                  going to be exported and in other circumstances.
                  </simpara>
                </listitem>

              </itemizedlist>
              
            </listitem>
          </varlistentry>
          
        </variablelist>
        
        <para>
          Click on the &gbSave; button
          to use the current settings. The display will
          automatically refresh itself.
        </para>
        
      </helptext>
      
      <helptext external_id="item.overview.validationoptions.savepreset" 
        title="Save preset" webonly="1">
        
        <para>
        Saves all validation options as a preset. 
        </para>
        
        <variablelist>
          <varlistentry>
            <term><guilabel>Name</guilabel></term>
            <listitem>
              <para>
                The name of the preset. The name must be unique
                and if a preset with the same name already exists
                you will be asked if you want to overwrite it or not.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
        
        <para>
          Click on the &gbSave; button
          to save the preset or &gbCancel;
          to abort.
        </para>
      </helptext>
      
    </sect2>
    
    <sect2 id="webclient.itemoverview.fixfailures">
      <title>Fixing validation failures</title>
      <helptext external_id="item.overview.fixfailures" 
        title="How to fix validation failures">
        
        <para>        
        The overview includes a function that allows
        you to quickly fix most of the problems found during the 
        validation. The easiest way to use the function is:
        </para>
        
        <orderedlist>
          <listitem>
            <simpara>
            Click on an error or warning in the list of failures in 
            the lower right
            pane. The tree in the left pane and the item overview in the
            top right pane will automatically be updated to show the
            exact location of the faulty item.
            </simpara>
          </listitem>
          <listitem>
            <simpara>
            The upper right pane should contain a list labeled
            <guilabel>Failure details</guilabel> with more information
            about each failure and also one or more suggestions for fixing
            the problem. For example, a failure due to a missing item
            should suggest that you add or select an item.
            </simpara>
          </listitem>
          
          <listitem>
            <simpara>
            The suggestions should also have links that takes
            you to an edit view where you can do the changes.
            </simpara>
          </listitem>
          
          <listitem>
            <simpara>
            After saving the changes you must click on the
            <guibutton>Validate</guibutton> button to update the
            interface. If you want, you can fix more than one 
            failure before clicking on the button.
            </simpara>
          </listitem>
            
        </orderedlist>
        
        <note>
          <title>Inactive links?</title>
          If you do not have permission to fix a problem the links will be inactive
          and you'll have to talk to someone with more powers.
        </note>
      
      </helptext>
    </sect2>
    
  </sect1>

</chapter>