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

Last change on this file since 5782 was 5782, checked in by Nicklas Nordborg, 10 years ago

References #1590: Documentation cleanup

Restructured documentation to generate shorter filenames.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Date Id
File size: 89.4 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE chapter PUBLIC
3    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
4    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
5<!--
6  $Id: webclient.xml 5782 2011-10-04 13:43:16Z nicklas $
7
8  Copyright (C) 2007 Jari Häkkinen, Peter Johansson, Nicklas Nordborg, Martin Svensson
9
10  This file is part of BASE - BioArray Software Environment.
11  Available at http://base.thep.lu.se/
12
13  BASE is free software; you can redistribute it and/or
14  modify it under the terms of the GNU General Public License
15  as published by the Free Software Foundation; either version 3
16  of the License, or (at your option) any later version.
17
18  BASE is distributed in the hope that it will be useful,
19  but WITHOUT ANY WARRANTY; without even the implied warranty of
20  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
21  GNU General Public License for more details.
22
23  You should have received a copy of the GNU General Public License
24  along with BASE. If not, see <http://www.gnu.org/licenses/>.
25-->
26
27<chapter id="webclient">
28  <?dbhtml dir="webclient" filename="index.html" ?>
29  <title>Using the web client</title>
30    <sect1 id="webclient.introduction">
31      <?dbhtml filename="introduction.html" ?>
32      <title>Introduction</title>
33     
34      <sect2 id="webclient.intro.login">
35        <title>Logging in</title>
36        <para>
37          There are three things that you need to know
38          before you can use BASE:
39        </para>
40       
41        <orderedlist>
42        <listitem><simpara>The address (URL) to a BASE server</simpara></listitem>
43        <listitem><simpara>A username to login with</simpara></listitem>
44        <listitem><simpara>A password</simpara></listitem>
45        </orderedlist>
46       
47        <para>
48          You may, for example, try the BASE demo server. Go to the
49          URL <ulink url="http://base2.thep.lu.se/demo/">http://base2.thep.lu.se/demo/</ulink>
50          and enter <userinput>base2</userinput> for the login and <userinput>base2</userinput>
51          for the password.
52        </para>
53       
54        <para>
55          You need to get all three things from an administrator
56          of the BASE server. If you know only the address to the
57          BASE server, you may check the front page if the administrator
58          has added any information about how to get a username/password
59          there. Look for the <guilabel>Get an account!</guilabel> link on
60          the front page.
61        </para>
62       
63        <para>
64          Logging in is simple, just enter your <guilabel>login</guilabel> 
65          and <guilabel>password</guilabel> in the form on the front page
66          and click the <guibutton>Login</guibutton> button. There is
67          a checkbox which allows you to <guilabel>encrypt the password</guilabel>
68          before it is sent to the BASE server. It is checked by default, and
69          it is a good idea to leave it checked unless you have problems logging
70          in. If you are sure you are entering the correct login and password,
71          but still cannot log in, try unchecking the encryption option.
72          If the checkbox is not visible, which happens if the server is
73          using an external authentication server, the password is not encrypted.
74        </para>
75      </sect2>
76     
77      <sect2 id="webclient.intro.forgotten_password">
78        <title>Forgotten password</title>
79        <para>
80          If you forget your password you will need to get a new one.
81          BASE stores the passwords in an encrypted form that does not allow
82          anyone, not even the server administrator, to find out the
83          un-encrypted password.
84        </para>
85        <para>
86          To get a new password you will have to contact the server
87          administrator. There may be a <guilabel>Forgot your password?</guilabel>
88          link on the front page where the server administrator has entered
89          information about how to get a new password.
90        </para>
91      </sect2>
92
93      <sect2 id="webclient.intro.homepage">
94        <title>The home page</title>
95     
96      <para>
97        When you have been logged in the home page will be displayed. It
98        displays some useful information. You can also go to the home page
99        using the
100        <menuchoice><guimenu>View</guimenu><guimenuitem>Home</guimenuitem></menuchoice>
101      </para>
102       
103      <figure id="webclient.figures.homepage">
104        <title>The home page</title>
105        <screenshot>
106          <mediaobject>
107            <imageobject><imagedata fileref="figures/homepage.png" format="PNG"
108              scalefit="1" width="100%"/></imageobject>
109          </mediaobject>
110        </screenshot>
111      </figure>
112       
113      <variablelist>
114        <varlistentry>
115          <term><interface>New messages</interface></term>
116          <listitem>
117            <para>
118            Messages are sent by plug-ins to notify you about finished jobs. In the
119            future, you may get messages from other sources as well. As of today,
120            messages are not used for communication between users.
121            </para>
122          </listitem>
123        </varlistentry>
124       
125        <varlistentry>
126          <term><interface>Projects</interface></term>
127          <listitem>
128            <para>
129            A list of projects that you are a member of. Projects are an important
130            part of BASE and are the best way to share data when you are
131            cooperating with other users. We recommend
132            that you always use a project when working with BASE.
133            For more information read <xref linkend="project_permission"/>. The list
134            displays the most recently used projects first and then fills up
135            with the rest sorted by name.
136            </para>
137          </listitem>
138        </varlistentry>
139       
140        <varlistentry>
141          <term><interface>Disk usage</interface></term>
142          <listitem>
143            <para>
144            An overview of how much disk space you have been assigned and
145            how much you are using.
146            </para>
147          </listitem>
148        </varlistentry>
149       
150        <varlistentry>
151          <term><interface>Help</interface></term>
152          <listitem>
153            <para>
154            Links for getting help and reporting bugs. The number
155            of links displayed here may vary depending on the server
156            configuration.
157            </para>
158          </listitem>
159        </varlistentry>
160       
161        <varlistentry>
162          <term><interface>News and announcements</interface></term>
163          <listitem>
164            <para>
165            A list of important news and announcements from the
166            server administrator. Here you may, for example, find
167            information about server upgrades and maintenance.
168            </para>
169          </listitem>
170        </varlistentry>
171      </variablelist>
172       
173      </sect2>
174     
175      <sect2 id="webclient.intro.menubar">
176        <title>Using the menu bar</title>
177        <para>
178          On the top of the home page is the <interface>Menu bar</interface>.
179          This is the main navigation tool in BASE. It works the same way
180          as the regular menu system found in most other applications. Use
181          the mouse to click and select an item from the menu.
182        </para>
183       
184        <para>
185          Most of the menu is in two levels, ie. clicking on a top-level menu
186          will open a submenu just below it. Clicking on something in the
187          submenu will take you to another page or open a pop-up dialog window.
188          For example, the
189          <menuchoice><guimenu>Biomaterial LIMS</guimenu><guimenuitem>Samples</guimenuitem></menuchoice>
190          menu will take you to the page listing samples and
191          <menuchoice><guimenu>BASE</guimenu><guimenuitem>Contact information</guimenuitem></menuchoice>
192          opens a dialog where you can modify your contact information details.
193        </para>
194       
195        <para>
196          The menu bar also contains shortcuts to some often-used
197          actions:
198        </para>
199       
200       
201      <variablelist>
202        <varlistentry>
203          <term>
204            <guiicon>
205              <inlinemediaobject>
206              <imageobject><imagedata fileref="figures/project.gif" format="GIF" align="left"/></imageobject>
207              </inlinemediaobject>
208            </guiicon>
209            <interface>
210            Projects
211            </interface>
212          </term>
213          <listitem>
214            <para>
215            A list of all projects you are a member of. The most recently used projects are
216            listed first, then the list is filled with the rest of your projects up to a
217            maximum of 15. If you have more projects an option to display the remaining
218            projects is activated. Selecting a project in the list will make that project
219            the active project.
220            </para>
221            <tip>
222              <para>
223              The sort order in the menu of non-recent projects is the same as the sort order on the
224              projects list page. If you, for example, want to sort the newest
225              project first (after the most recently used ones), select to sort by the
226              <guilabel>Registered</guilabel> column in descending order on the list page.
227              The menu will automatically use the same order.
228              </para>
229            </tip>
230          </listitem>
231        </varlistentry>
232        <varlistentry>
233          <term>           
234            <guiicon>
235              <inlinemediaobject>
236              <imageobject><imagedata fileref="figures/refresh.gif" format="GIF" align="left"
237                /></imageobject>
238              </inlinemediaobject>
239            </guiicon>
240            <interface>
241            Refresh page
242            </interface>
243          </term>
244          <listitem>
245            <para>
246            Refresh/reload the current page. This is useful when you add
247            or modify items in BASE. Most of the time the page is refreshed
248            automatically, but in some cases you will have to use
249            this button to refresh the page.
250            </para>
251           
252            <warning>
253              <para>
254              Do not use your browser's <guibutton>Refresh</guibutton> button.
255              Most browsers will take you to the login page again.
256              </para>
257            </warning>
258          </listitem>
259        </varlistentry>
260       
261        <varlistentry>
262          <term>     
263            <guiicon>     
264              <inlinemediaobject>
265              <imageobject><imagedata fileref="figures/recent.png" format="PNG" align="left"/></imageobject>
266              </inlinemediaobject>
267            </guiicon>
268            <interface>
269            Recent items
270            </interface>
271          </term>
272          <listitem>
273            <para>
274            Shortcut to the most recently viewed items. The number of items are
275            configurable and you can also make some item types
276            <emphasis>sticky</emphasis>. This will for example keep the shortcut
277            to the last experiment even if you have viewed lots of other items
278            more recently.
279            See <xref linkend="webclient.configuration.preferences.mostrecent"/>
280            for configuration information.
281            </para>
282          </listitem>
283        </varlistentry>
284       
285        <varlistentry>
286          <term>
287            <guiicon>
288              <inlinemediaobject>
289              <imageobject><imagedata fileref="figures/user.png" format="PNG" align="left"/></imageobject>
290              </inlinemediaobject>
291            </guiicon>
292            <interface>
293            Logged in user
294            </interface>
295          </term>
296          <listitem>
297            <para>
298            Displays the name of the currently logged in user and allows
299            you to quickly log out and switch to another user.
300            </para>
301          </listitem>
302        </varlistentry>
303       
304      </variablelist>
305       
306      </sect2>
307     
308      <sect2 id="webclient.intro.help">
309        <title>Getting help</title>
310        <para>
311          Besides reading this document there are more ways to get help:
312        </para>
313        <variablelist>
314          <varlistentry>
315            <term>
316              On-line context-sensitive help
317            </term>
318            <listitem>
319              <para>
320              Whenever you find a small help icon
321              (<guiicon>
322                <inlinemediaobject>
323                <imageobject><imagedata fileref="figures/help.gif" format="GIF" /></imageobject>
324                </inlinemediaobject>
325              </guiicon>)
326              or button you may
327              click it to get help about the part of the page
328              you are currently viewing. The icon is located in the title
329              bar in most pop-up dialog windows and in the toolbar in most
330              other pages.
331              </para>
332            </listitem>
333          </varlistentry>
334
335          <varlistentry>
336            <term>
337              Using the <menuchoice><guimenu>Help</guimenu></menuchoice> menu
338            </term>
339            <listitem>
340              <para>
341              The <menuchoice><guimenu>Help</guimenu></menuchoice> menu
342              contains links for getting on-line help. These links
343              may be configured by a server administrator, so they may be
344              different from server to server. By default links for reporting
345              a bug and accessing this document are installed.
346              </para>
347            </listitem>
348          </varlistentry>
349
350          <varlistentry>
351            <term>
352              Mailing lists and other resources
353            </term>
354            <listitem>
355              <para>
356              See <xref linkend="resources" />.
357              </para>
358            </listitem>
359          </varlistentry>
360
361        </variablelist>
362       
363      </sect2>
364   
365    </sect1>
366   
367    <sect1 id="webclient.configuration">
368      <?dbhtml filename="configuration.html" ?>
369      <title>Configuring your account</title>
370     
371      <sect2 id="webclient.configuration.contact">
372        <title>Contact information</title>
373       
374        <para>
375          Use the <menuchoice><guimenu>BASE</guimenu>
376          <guimenuitem>Contact information</guimenuitem></menuchoice>
377          menu to bring up the user information dialog.
378        </para>
379       
380        <helptext external_id="userpreferences.contact" title="Contact information">
381       
382          <para>
383          This dialog has three tabs, <guilabel>Contact information</guilabel>
384          (selected), <guilabel>Password</guilabel> and <guilabel>Other information</guilabel>.
385          The logged in user can update the following contact information
386          details.
387          </para>
388       
389          <note>
390            <title>Multi-user accounts</title>
391            <para>
392              If you are using a multi-user account, for example a demo-account, you
393              do not have permission to change the contact information.
394            </para>
395          </note>
396       
397          <variablelist>
398            <varlistentry>
399              <term>
400                <guilabel>Full name</guilabel>
401              </term>
402              <listitem>
403                <para>
404                Your full name. You are not allowed to change this. If
405                it is not correct, contact an administrator to do it for
406                you.
407                </para>
408              </listitem>
409            </varlistentry>
410            <varlistentry>
411              <term>
412                <guilabel>Email</guilabel>
413              </term>
414              <listitem>
415                <para>
416                Your email address (optional). If an email has been specified and if the
417                server administrator has enabled email notifications, you also have the
418                option to select if messages should be sent as emails. This can be useful
419                to keep track of jobs that take a long time to complete.
420                </para>
421              </listitem>
422            </varlistentry>
423            <varlistentry>
424              <term>
425                <guilabel>Organisation</guilabel>
426              </term>
427              <listitem>
428                <para>
429                The name of the organisation you work for or represent (optional).
430                </para>
431              </listitem>
432            </varlistentry>
433            <varlistentry>
434              <term>
435                <guilabel>Address</guilabel>
436              </term>
437              <listitem>
438                <para>
439                Your postal address as it should be printed on letters to you
440                (optional).
441                </para>
442              </listitem>
443            </varlistentry>
444            <varlistentry>
445              <term>
446                <guilabel>Phone</guilabel>
447              </term>
448              <listitem>
449                <para>
450                Your phone number (optional). You may enter multiple phone numbers,
451                for example your work phone number and a mobile number.
452                </para>
453              </listitem>
454            </varlistentry>
455            <varlistentry>
456              <term>
457                <guilabel>Fax</guilabel>
458              </term>
459              <listitem>
460                <para>
461                Your fax number (optional).
462                </para>
463              </listitem>
464            </varlistentry>
465            <varlistentry>
466              <term>
467                <guilabel>Url</guilabel>
468              </term>
469              <listitem>
470                <para>
471                An URL to your home page or your organisation's home page (optional).
472                </para>
473              </listitem>
474            </varlistentry>
475          </variablelist>
476         
477          <para>
478            Press &gbSave; to save the changes or
479            &gbCancel; to abort.
480          </para>
481         
482          <seeother>
483            <other external_id="userpreferences.password">Change password</other>
484            <other external_id="userpreferences.other">Other information</other>
485          </seeother>
486        </helptext>
487       
488      </sect2>
489     
490      <sect2 id="webclient.configuration.other">
491        <title>Other information</title>
492        <para>
493          Use the
494          <menuchoice>
495            <guimenu>BASE</guimenu>
496            <guimenuitem>Other information&hellip;</guimenuitem>
497          </menuchoice>
498          menu to bring up the other information dialog.
499        </para>
500        <helptext external_id="userpreferences.other" title="Other information">
501          <para>
502            This dialog has three tabs,
503            <guilabel>Contact information</guilabel>
504            ,
505            <guilabel>Password</guilabel>
506            and
507            <guilabel>Other information</guilabel>
508            (selected) .
509          </para>
510          <para>
511            The look of the
512            <guilabel>Other information</guilabel>
513            tab can differ a bit between different servers, depending on what settings
514            the server is installed with. There are three inputs in a fresh BASE
515            installation but it is only the
516            <guilabel>Description</guilabel>
517            text area that is static, the others can be removed or more fields can be
518            added (managed by the server administrator). The three fields, included in a
519            the BASE installation, are
520            <variablelist>
521              <varlistentry>
522                <term>
523                  <guilabel>Mobile</guilabel>
524                </term>
525                <listitem>
526                  <para>Your mobile number(Optional).</para>
527                </listitem>
528              </varlistentry>
529              <varlistentry>
530                <term>
531                  <guilabel>Skype</guilabel>
532                </term>
533                <listitem>
534                  <para>Your Skype contact information(Optional).</para>
535                </listitem>
536              </varlistentry>
537              <varlistentry>
538                <term>
539                  <guilabel>Description</guilabel>
540                </term>
541                <listitem>
542                  <para>
543                    Text area where you can put useful information that couldn't
544                    be stored anywhere else(Optional).
545                  </para>
546                </listitem>
547              </varlistentry>
548            </variablelist>
549          </para>
550          <para>Press &gbSave; to save the changes or &gbCancel; to abort.</para>
551          <seeother>
552            <other external_id="userpreferences.contact">Contact information</other>
553            <other external_id="userpreferences.password">Change password</other>
554          </seeother>
555        </helptext>
556      </sect2>
557
558      <sect2 id="webclient.configuration.password">
559        <title>Changing password</title>
560       
561        <para>
562          Use the <menuchoice><guimenu>BASE</guimenu>
563          <guimenuitem>Change password</guimenuitem></menuchoice>
564          menu to bring up the change password dialog.
565        </para>
566       
567        <helptext external_id="userpreferences.password" title="Change password">
568
569          <para>
570          This dialog has three tabs, <guilabel>Contact information</guilabel>,
571          <guilabel>Password</guilabel> (selected) and <guilabel>Other information</guilabel>.
572          </para>
573
574          <variablelist>
575            <varlistentry>
576              <term>
577                <guilabel>New password</guilabel>
578              </term>
579              <listitem>
580                <para>
581                Enter the new password.
582                </para>
583              </listitem>
584            </varlistentry>
585            <varlistentry>
586              <term>
587                <guilabel>Retype password</guilabel>
588              </term>
589              <listitem>
590                <para>
591                Retype the same password. You must do this to
592                avoid spelling mistakes.
593                </para>
594              </listitem>
595            </varlistentry>
596          </variablelist>
597
598          <note>
599            <title>Multi-user accounts</title>
600            <para>
601              If you are using a multi-user account, for example a demo-account, you
602              do not have permission to change the password.
603            </para>
604          </note>
605       
606          <note>
607            <title>Empty passwords</title>
608            <para>
609              If you leave both fields empty the password will not be changed. It
610              is not possible to have an empty password.
611            </para>
612          </note>
613         
614          <seeother>
615            <other external_id="userpreferences.contact">Contact information</other>
616            <other external_id="userpreferences.other">Other information</other>
617          </seeother>
618         
619        </helptext>
620      </sect2>
621
622      <sect2 id="webclient.configuration.preferences">
623        <title>Preferences</title>
624       
625        <para>
626          Use the <menuchoice><guimenu>BASE</guimenu>
627          <guimenuitem>Preferences</guimenuitem></menuchoice>
628          menu to bring up the preferences dialog.
629          This dialog has three tabs, <guilabel>Appearance</guilabel>,
630          <guilabel>Plugins</guilabel> and <guilabel>Recent items</guilabel>.
631        </para>
632       
633        <sect3 id="webclient.configuration.preferences.appearance">
634          <title>The Appearance tab</title>
635         
636          <helptext external_id="userpreferences.appearance" title="Preferences - Appearance">
637         
638          <para>
639          This tab contains settings that affect the appearance of the
640          web client.
641          </para>
642         
643          <variablelist>
644            <varlistentry>
645              <term>
646                <guilabel>Font size</guilabel>
647              </term>
648              <listitem>
649                <para>
650                Select a basic font size. You can choose between
651                five sizes: extra small (XS), small (S), medium (M),
652                large (L) and extra large (XL). The default font size is
653                medium.
654                </para>
655              </listitem>
656            </varlistentry>
657            <varlistentry>
658              <term>
659                <guilabel>Scale factor</guilabel>
660              </term>
661              <listitem>
662                <para>
663                The scale factor affects the size of pop-up windows.
664                This setting exists because different browsers render
665                pages differently. If you often find that pop-up windows
666                are too small you can change this setting to make them
667                bigger.
668                </para>
669                <note>
670                  <para>
671                    The scale factor is automatically changed if the
672                    font size is changed.
673                  </para>
674                </note>
675              </listitem>
676            </varlistentry>
677            <varlistentry>
678              <term>
679                <guilabel>Display long texts</guilabel>
680              </term>
681              <listitem>
682                <para>
683                This setting is used to control how long description texts
684                are displayed in tables and other places with limited space.
685                There are three settings:
686                </para>
687                <itemizedlist>
688                  <listitem>
689                    <simpara>
690                    <guilabel>Always</guilabel>: The full text is always displayed. This may
691                    cause tables, etc. to become hard to read since cells will automatically
692                    grow to be able to display the full text.
693                    </simpara>
694                  </listitem>
695                  <listitem>
696                    <simpara>
697                    <guilabel>On hover</guilabel>: A short version of the text is
698                    displayed and the full text is automatically displayed when
699                    the mouse is moved over the text. Texts that are not fully
700                    visible are indicated with a dotted line to the right.
701                    </simpara>
702                  </listitem>
703                  <listitem>
704                    <simpara>
705                    <guilabel>On click</guilabel>: A short version of the text is
706                    displayed and the full text is displayed when the mouse is clicked
707                    somewhere on the short text. Texts that are not fully visible
708                    are indicated with a grey line to the right.
709                    </simpara>
710                  </listitem>
711                </itemizedlist>
712               
713                <warning>
714                  The 'On click' mode may not perform so well if lots of items are
715                  displayed in a single list. This is particularly so with Internet
716                  Explorer (version 7) which is 5-10 times slower than Firefox to
717                  render the page. If you experience problems with this mode you should
718                  either use a different mode or display less items on a single page.
719                </warning>
720               
721              </listitem>
722            </varlistentry>
723            <varlistentry>
724              <term>
725                <guilabel>Toolbar</guilabel>
726              </term>
727              <listitem>
728                <para>
729                You may choose if the toolbar buttons should
730                have only images, only text or both images and text.
731                The default is that they have both images and text.
732                </para>
733              </listitem>
734            </varlistentry>
735            <varlistentry>
736              <term>
737                <guilabel>Ratio color range</guilabel>
738              </term>
739              <listitem>
740                <para>
741                Select three colors to use when displaying
742                data that is suitable for color coding, for
743                example the intensity ratio in two-color
744                experiments. The default setting is blue-white-yellow.
745                The list of presets contains other useful color combinations
746                (for example, the BASE version 1 red-yellow-green) and the most
747                recently used color combinations.
748                </para>
749              </listitem>
750            </varlistentry>
751            <varlistentry>
752              <term>
753                <guilabel>Date format</guilabel>
754              </term>
755              <listitem>
756                <para>
757                A format string describing how dates should be displayed.
758                We support all formatting options supported by the Java
759                language. For more information see:
760                <ulink url="http://download.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html">SimpleDateFormat documentation</ulink>
761                The most useful format patterns are:
762                </para>
763               
764                <itemizedlist>
765                  <listitem><simpara>yy: two-digit year</simpara></listitem>
766                  <listitem><simpara>yyyy: four-digit year</simpara></listitem>
767                  <listitem><simpara>MM: two-digit month</simpara></listitem>
768                  <listitem><simpara>MMM: month name (short)</simpara></listitem>
769                  <listitem><simpara>MMMM: month name (full)</simpara></listitem>
770                  <listitem><simpara>dd: two-digit day in month</simpara></listitem>
771                </itemizedlist>
772               
773                <para>
774                The list of presets contains the most commonly/recently
775                used date formats.
776                </para>
777               
778              </listitem>
779            </varlistentry>
780           
781            <varlistentry>
782              <term>
783                <guilabel>Date-time format</guilabel>
784              </term>
785              <listitem>
786                <para>
787                A format string describing how dates with times should be displayed.
788                We support all formatting options supported by the Java
789                language. For more information see:
790                <ulink url="http://download.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html">SimpleDateFormat documentations</ulink>
791                The most useful time-format patterns are:
792                </para>
793               
794                <itemizedlist>
795                  <listitem><simpara>HH: two-digit hour (0-23)</simpara></listitem>
796                  <listitem><simpara>hh: two-digit hour (1-12)</simpara></listitem>
797                  <listitem><simpara>a: AM/PM marker</simpara></listitem>
798                  <listitem><simpara>mm: two-digit minute</simpara></listitem>
799                  <listitem><simpara>ss: two-digit second</simpara></listitem>
800                </itemizedlist>
801               
802              </listitem>
803            </varlistentry>
804           
805            <varlistentry>
806              <term>
807                <guilabel>Decimals</guilabel>
808              </term>
809              <listitem>
810                <para>
811                The number of decimals to display for numerical floating point values.
812                The default is 2.
813                </para>
814              </listitem>
815            </varlistentry>
816           
817          </variablelist>
818       
819          </helptext>
820       
821        </sect3>
822       
823        <sect3 id="webclient.configuration.preferences.plugins">
824          <title>The Plugins tab</title>
825         
826          <helptext external_id="userpreferences.plugins" title="Preferences - Plugins">
827         
828          <para>
829            This tab contains settings that affect plug-in execution.
830          </para>
831         
832          <variablelist>
833            <varlistentry>
834              <term>
835                <guilabel>Messages</guilabel>
836              </term>
837              <listitem>
838                <para>
839                Mark the checkbox if you want to have a message sent
840                to you when a plug-in completes execution. This setting
841                can be overridden each time you start a plug-in. You'll
842                receive the message as a notification in BASE, but it may
843                also be possible to get the message as an email.
844                </para>
845              </listitem>
846            </varlistentry>
847            <varlistentry>
848              <term>
849                <guilabel>Remove jobs</guilabel>
850              </term>
851              <listitem>
852                <para>
853                  This checkbox should be marked if you want the jobs, done by
854                  import or export plug-ins, to be marked as removed if they
855                  finished successfully. This setting can be overridden each time
856                  you start a plug-in.
857                </para>
858              </listitem>
859            </varlistentry>
860            <varlistentry>
861              <term>
862                <guilabel>Show warnings</guilabel>
863              </term>
864              <listitem>
865                <para>
866                  This checkbox should be marked if you want to show warning
867                  messages from plug-ins in the <guilabel>Select plug-in</guilabel>
868                  dialog. Warning-level messages usually originates from plug-ins
869                  that are unrelated to the current task and are only of interest to
870                  plug-in developers. Error messages that are related to the
871                  current task are always shown.
872                </para>
873              </listitem>
874            </varlistentry>
875          </variablelist>
876          </helptext>
877         
878        </sect3>
879       
880        <sect3 id="webclient.configuration.preferences.mostrecent">
881          <title>The Recent items tab</title>
882         
883          <helptext external_id="userpreferences.mostrecent" 
884            title="Preferences - Recent items">
885         
886          <para>
887            This tab contains settings that affect the <guilabel>Recent
888            items</guilabel> menu and selection lists in many edit dialogs.
889          </para>
890         
891          <variablelist>
892          <varlistentry>
893            <term>
894              <guilabel>Recently viewed items</guilabel>
895            </term>
896            <listitem>
897              <para>
898              The number of recently <emphasis>viewed</emphasis> items to remember.
899              The default is to remember 6 items. The remembered items
900              will be displayed in the <guilabel>Recent items</guilabel>
901              menu in the menu bar.
902              </para>
903            </listitem>
904          </varlistentry>
905          <varlistentry>
906            <term>
907              <guilabel>Recently used items</guilabel>
908            </term>
909            <listitem>
910              <para>
911              The number of recently <emphasis>used</emphasis> items to remember.
912              The default is to remember 4 items. The remembered items will
913              be displayed in edit dialogs where they have been used before.
914              Each type of edit operation has it's own list of remembered items.
915              For example, there is one list that remembers the most recently used
916              protocols when creating a sample, and there is another list that
917              remembers the most recently used scanners when creating a scan.
918              </para>
919            </listitem>
920          </varlistentry>
921         
922          <varlistentry>
923            <term>
924              <guilabel>Load the names of all items</guilabel>
925            </term>
926            <listitem>
927              <para>
928              If checked, the names of the items will be loaded and
929              displayed in the menu, otherwise only the ID and type of item
930              is displayed.
931              </para>
932            </listitem>
933          </varlistentry>
934         
935          <varlistentry>
936            <term>
937              <guilabel>Sticky items</guilabel>
938            </term>
939            <listitem>
940              <para>
941              Always remember the last viewed item of the selected types.
942              For example, if you have selected <emphasis>Experiment</emphasis>
943              as a sticky item, the last viewed experiment will be remembered
944              even if you view hundreds of other items. Use the arrow buttons
945              to move item types between the lists and sort the sticky items list.
946              Sticky items will be displayed in the <guilabel>Recent items</guilabel>
947              menu in the menu bar.             
948              </para>
949            </listitem>
950          </varlistentry>
951          </variablelist>
952          </helptext>
953         
954        </sect3>
955      </sect2>
956 
957    </sect1>
958   
959    <sect1 id="webclient.items">
960      <?dbhtml filename="items.html" ?>
961      <title>Working with items</title>
962     
963      <para>
964        No matter what you are doing in BASE some things works more
965        or less in the same way. This section covers things that are
966        common for most parts of BASE.
967      </para>
968     
969      <para>
970        You mostly work with a single type of item at a time. This is
971        reflected in the menu system. For example, use
972        <menuchoice>
973          <guimenu>Biomaterial LIMS</guimenu>
974          <guimenuitem>Samples</guimenuitem>
975        </menuchoice>
976        to work with samples, and
977        <menuchoice>
978          <guimenu>View</guimenu>
979          <guimenuitem>Experiments</guimenuitem>
980        </menuchoice>
981        to work with experiments. In most cases the list view for that type
982        of item is displayed. The list view, as the name says,
983        is used to list all items. There are two more standard views, the
984        single-item view and the edit view.
985      </para>
986     
987      <variablelist>
988        <varlistentry>
989          <term>List view</term>
990          <listitem>
991            <para>
992            This view lists all items of a certain type. The view allows you to search
993            and it is possible to configure which information to show
994            for each item. It also contains functions that
995            can be used on multiple items at the same time, for example,
996            delete, share and export. See <xref linkend="webclient.itemlist"/> for more information.
997            </para>
998          </listitem>
999        </varlistentry>
1000     
1001        <varlistentry>
1002          <term>Single-item view</term>
1003          <listitem>
1004            <para>
1005            Displays information about a single item. Sometimes it is very little,
1006            sometimes it is very much and the information may be divided
1007            into multiple tabs.
1008            </para>
1009          </listitem>
1010        </varlistentry>
1011     
1012        <varlistentry>
1013          <term>Edit view</term>
1014          <listitem>
1015            <para>
1016            This view is used for editing the information
1017            about a single item. It is always displayed as a pop-up window.
1018            </para>
1019          </listitem>
1020        </varlistentry>
1021      </variablelist> 
1022             
1023      <sect2 id="webclient.items.new">
1024        <title>Create a new item</title>
1025       
1026        <para>
1027          New items are mostly created from the list view. For example,
1028          to create a new experiment go to the
1029          <menuchoice><guimenu>View</guimenu> <guimenuitem>Experiments</guimenuitem></menuchoice>
1030          page. Here you will find a &gbNew; button in the
1031          toolbar. The button is disabled if you do not have permission to create new experiments.
1032          Otherwise, click on it and enter any required information in the pop-up dialog.
1033          Sometimes there are multiple tabs in this dialog. In the case of experiments
1034          there are three tabs: <guilabel>Experiment</guilabel>, <guilabel>Publication</guilabel>
1035          and <guilabel>Experimental factors</guilabel>.
1036         
1037          As a general rule, only the first tab has information that is required.
1038          The information in all other tabs are optional.
1039        </para>
1040       
1041        <para>
1042          In some places you will also find actions that create items
1043          directly in the list. For example in the list of samples or on
1044          the single-item view for a sample you can create an extract using that
1045          sample as the parent. If you use such links the parent
1046          item will in most cases be selected automatically, which saves
1047          you a few clicks when creating new items.
1048        </para>
1049       
1050        <para>
1051          Click on the &gbSave; button to save the new
1052          item to the database or on the &gbCancel; button
1053          to abort.
1054        </para>
1055
1056        <note>
1057          <para>
1058          To speed up data entry when adding multiple new items there
1059          are a few tricks you can use to make the web client supply
1060          default values for most properties. To find a default value
1061          the following checklist is used in this order:
1062          </para>
1063       
1064        <orderedlist>         
1065          <listitem>
1066            <para>
1067            If the list have an active filter the filter values are
1068            used as default property values for the new item. For example,
1069            if you are listing experiments with <guilabel>Genepix</guilabel>
1070            raw data type the new experiment will automatically have
1071            <guilabel>Genepix</guilabel> selected. This trick should work
1072            for all properties except annotations, if it does not
1073            report it as a bug to the development team.
1074            </para>
1075          </listitem>
1076         
1077          <listitem>
1078            <para>
1079            When you link to other items the same item will be used the next time.
1080            For example, if you create an extract and selects an extraction protocol
1081            the same protocol is used the next time you create another extract.
1082            In fact, BASE will remember as many items as specified by
1083            the
1084            <guilabel>Recently used items</guilabel> setting (default is 4),
1085            allowing you to quickly select one of those protocols.
1086            <xref linkend="webclient.configuration.preferences.mostrecent" /> 
1087            contains more information about the setting.
1088            </para>
1089          </listitem>
1090         
1091          <listitem>
1092            <para>
1093            If you have a project active and that project has specified default
1094            values those values will be used for new items. A project can specify
1095            defaults for protocols, hardware and software and a few other settings.
1096            </para>
1097          </listitem>
1098         
1099        </orderedlist>
1100       
1101        </note>
1102       
1103      </sect2>
1104     
1105      <sect2 id="webclient.items.edit">
1106        <title>Edit an existing item</title>
1107       
1108        <para>
1109          On all single-item views there is an &gbEdit;
1110          button in the toolbar that opens a pop-up dialog for editing the properties
1111          of the item. This button is disabled if the logged in user does not have
1112          write permission for the item.
1113        </para>
1114       
1115        <para>
1116          You can also open the edit pop-up in most other places where
1117          the item appears, for example, in lists or the single-item view
1118          of a related item. Press and hold one of the <keycap>CTRL</keycap>,
1119          <keycap>ALT</keycap> or <keycap>SHIFT</keycap> keys while clicking
1120          on the link and the edit window will open in a pop-up.
1121          If you do not have write permission
1122          on the item there is no meaning to open the edit pop-up and you will
1123          be taken to the single-item view page instead.
1124        </para>
1125
1126        <para>
1127          Click on the &gbSave; button to save the changes
1128          to the database or on the &gbCancel; button
1129          to abort.
1130        </para>
1131     
1132      </sect2>
1133
1134      <sect2 id="webclient.items.delete">
1135        <title>Delete items</title>
1136
1137        <para>
1138          You can delete items either from the list view or from
1139          a single-item view. In both cases, deleted items are only moved to
1140          the trashcan. No information is removed from the database. This allows
1141          you to restore items if you later find out that you need them again.
1142          In fact, there is nothing special about a removed item. It can still be
1143          used for the same things as any non-removed item can.
1144        </para>
1145
1146        <important>
1147          <para>
1148          To really delete items from the database you have two options:
1149          <orderedlist>
1150          <listitem>
1151            <para>
1152            Go to the trashcan
1153            <menuchoice><guimenu>View</guimenu><guimenuitem>Trashcan</guimenuitem></menuchoice>
1154            and delete it from there. From the trashcan you can delete several items
1155            in one go. See <xref linkend="webclient.trashcan"/>.
1156            </para>
1157          </listitem>
1158          <listitem>
1159            <para>
1160            Click on the small trashcan icon in the list or single-item view.
1161            You can only delete one item at a time.
1162            </para>
1163          </listitem>
1164          </orderedlist>
1165          </para>
1166        </important>
1167       
1168        <para>
1169          To delete items from the list view you must first mark
1170          the checkbox for each item you want to delete. Then, click on
1171          the &gbDelete; button. The list should refresh itself
1172          automatically. If you want to confirm that the items have been removed
1173          use the <guilabel>view / presets</guilabel> dropdown and select
1174          the <guilabel>Removed</guilabel> option. The removed items should now
1175          be displayed in the list with a small trashcan icon to indicate that
1176          they are located in the trashcan.
1177        </para>
1178
1179        <para>
1180          To delete items from the single-item view, click on the
1181          &gbDelete; button in the toolbar. The page will refresh
1182          itself automatically and a small trashcan icon should be displayed.
1183          If you do not have permission to delete the item the delete button
1184          is disabled.
1185        </para>
1186
1187      </sect2>
1188     
1189      <sect2 id="webclient.items.restore">
1190        <title>Restore deleted items</title>
1191       
1192        <para>
1193          You can restore deleted items either from the trashcan, from
1194          the list view, or from the single-item view. This section
1195          only covers the last two cases. The trashcan is described in
1196          <xref linkend="webclient.trashcan"/>.
1197        </para>
1198
1199        <para>
1200          To delete items from the list view you must first make the deleted
1201          items appear in the list. This is easy, just use the <guilabel>view / presets</guilabel> 
1202          dropdown and select the <guilabel>Removed</guilabel> option. The list should
1203          refresh itself automatically. The removed items are
1204          displayed in the list with a small trashcan icon to indicate that
1205          they are located in the trashcan. Then, mark the checkbox for each item that you want
1206          to restore and click the &gbRestore; button. The list should
1207          refresh itself automatically and the trashcan icon should be gone from the
1208          restored items.
1209        </para>
1210       
1211        <para>
1212          To restore items from the single-item view, click on the
1213          &gbRestore; button in the toolbar. The page will refresh
1214          itself automatically and the small trashcan icon should be gone.
1215          If you do not have permission to restore the item the restore button
1216          is disabled.
1217        </para>
1218
1219      </sect2>
1220
1221      <sect2 id="webclient.items.share">
1222        <title>Share items to other users</title>
1223        <para>
1224          Sharing data with other users is an important feature
1225          of BASE, which allows you cooperate in teams. If you
1226          follow the instructions in <xref linkend="project_permission" />
1227          you will find that you almost never have to share items manually
1228          to other users. This is because whenever you work with an active
1229          project each new item you create will automatically be shared
1230          according to the settings of that project. In most cases, this
1231          is all you need.
1232        </para>
1233       
1234        <para>
1235          If you still need to manually share your data with other users,
1236          here is how to do it.
1237        </para>
1238       
1239        <para>
1240          From a list view, mark the checkbox for each item you want to share.
1241          Then, click on the &gbShare; button.
1242          If you are on a single-item page, click on the &gbShare; 
1243          button on that page. In both cases, this will open the
1244          <guilabel>Set access permissions</guilabel>
1245          dialog window.
1246        </para>
1247       
1248        <figure id="webclient.items.share.set_permissions">
1249          <title>Sharing items to other users</title>
1250          <screenshot>
1251          <mediaobject>
1252            <imageobject>
1253              <imagedata fileref="figures/set_permissions.png" format="PNG" />
1254            </imageobject>
1255          </mediaobject>
1256          </screenshot>
1257        </figure>
1258       
1259        <helptext external_id="share.setpermissions" title="Set access permissions">
1260          <variablelist>
1261            <varlistentry>
1262              <term><guilabel>Members</guilabel></term>
1263              <listitem>
1264                <para>
1265                The list displays the users, groups and projects
1266                that already has access to the items you selected.
1267                The list shows the name and the permission level.
1268                The permission level uses a one-letter code as follows:
1269                </para>
1270               
1271                <itemizedlist>
1272                <listitem><simpara><guilabel>R</guilabel> = Read</simpara></listitem>
1273                <listitem><simpara><guilabel>U</guilabel> = Use</simpara></listitem>
1274                <listitem><simpara><guilabel>W</guilabel> = Write</simpara></listitem>
1275                <listitem><simpara><guilabel>D</guilabel> = Delete</simpara></listitem>
1276                <listitem><simpara><guilabel>O</guilabel> = Set owner</simpara></listitem>
1277                <listitem><simpara><guilabel>P</guilabel> = Set permission</simpara></listitem>
1278                </itemizedlist>
1279               
1280                <para>
1281                  Instead of a permission code, the word <guilabel>varying</guilabel>
1282                  may be displayed. This happens if the items you selected have been
1283                  shared with different permission.
1284                </para>
1285               
1286                <para>
1287                  The <guilabel>Permission templates</guilabel> part of the list
1288                  is always empty to begin with.
1289                </para>
1290               
1291              </listitem>
1292            </varlistentry>
1293           
1294            <varlistentry>
1295              <term><guilabel>Permissions</guilabel></term>
1296              <listitem>
1297                <para>
1298                When you select a user, group or project in the
1299                list, the checkboxes will display the current permission.
1300                The exception is if the permissions are varying, in which
1301                case no checkboxes are checked.
1302                To change the permissions just check the permissions you want to
1303                grant or uncheck the permissions you want to revoke.
1304                You can select more than one user, group or project
1305                and change the permissions for all of them at once.
1306                </para>
1307                <para>
1308                The permission boxes are disabled if a permission template
1309                is selected. The permissions are already part of the template
1310                and can't be changed here.
1311                </para>
1312              </listitem>
1313            </varlistentry>           
1314
1315            <varlistentry>
1316              <term><guibutton>Add users</guibutton></term>
1317              <listitem>
1318                <para>
1319                Opens a pop-up window that allows you to select
1320                users to share the items to. In the pop-up window, mark
1321                one or more users and click on the &gbOk;
1322                button. The pop-up window will only list users that you have
1323                permission to read. Unless you are an administrator, this
1324                usually means that you can only see users that:
1325                </para>
1326                <itemizedlist>
1327                  <listitem>
1328                    <para>
1329                    you share group memberships with
1330                    (the <emphasis>Everyone</emphasis> group doesn't count)
1331                    </para>
1332                  </listitem>
1333                  <listitem>
1334                    <para>
1335                    are members of the currently active project, if any.
1336                    </para>
1337                  </listitem>
1338                </itemizedlist>
1339                <para>
1340                Users that already have access to the item are not included in the
1341                list. If you don't see a user that you want to share an item to,
1342                you'll need to talk to an administrator for setting up the proper
1343                group membership.
1344                </para>
1345              </listitem>
1346            </varlistentry>
1347
1348            <varlistentry>
1349              <term><guibutton>Add groups</guibutton></term>
1350              <listitem>
1351                <para>
1352                Opens a pop-up window that allows you to select
1353                groups to share the items to. In the pop-up window, mark
1354                one or more groups and click on the &gbOk;
1355                button. Unless you are an administrator, the pop-up window
1356                will only list groups where you are a member. It will not list
1357                groups that already have access to the items.
1358                </para>
1359              </listitem>
1360            </varlistentry>
1361           
1362            <varlistentry>
1363              <term><guibutton>Add projects</guibutton></term>
1364              <listitem>
1365                <para>
1366                Opens a pop-up window that allows you to select
1367                projects to share the items to. In the pop-up window, mark
1368                one or more projects and click on the &gbOk;
1369                button. Unless you are an administrator, the pop-up window
1370                will only list projects where you are a member. It will not list
1371                projects that already have access to the items.
1372                </para>
1373              </listitem>
1374            </varlistentry>
1375           
1376            <varlistentry>
1377              <term><guibutton>Templates</guibutton></term>
1378              <listitem>
1379                <para>
1380                Opens a pop-up window that allows you to select
1381                permission templates. In the pop-up window, mark
1382                one or more templates and click on the &gbOk;
1383                button. Unless you are an administrator, the pop-up window
1384                will only list templates that you are allowed to use. It will
1385                not list templates that have already been added.
1386                </para>
1387               
1388                <note>
1389                  <para>
1390                  The permissions from the selected templates are <emphasis>copied</emphasis>
1391                  to the items when the access permissions are saved. If you re-open the share dialog,
1392                  the actual permissions are shown and the permission templates
1393                  section is empty. Modifying the permission template later doesn't
1394                  affect the permissions on existing items. See <xref linkend="project_permission.templates" /> 
1395                  for more information about permission templates.
1396                  </para>
1397                </note>
1398               
1399              </listitem>
1400            </varlistentry>
1401
1402            <varlistentry>
1403              <term>&gbRemove;</term>
1404              <listitem>
1405                <para>
1406                Click on this button to revoke access permissions from
1407                the selected users, groups and projects.
1408                </para>
1409              </listitem>   
1410            </varlistentry>
1411           
1412            <varlistentry>
1413              <term><guilabel>Apply permissions to all sub-directories and their files</guilabel></term>
1414              <listitem>
1415                <para>
1416                This option shows up if at least one of the selected items
1417                is a directory. If this option is selected the permissions given
1418                to the directory will recursively be copied to all files and
1419                sub-directories. Existing permissions on those items will be
1420                overwritten with the new permissions.
1421                </para>
1422              </listitem>   
1423            </varlistentry>
1424          </variablelist>
1425       
1426          <para>
1427            Use the &gbSave; button to save your
1428            changes or the &gbCancel; button to
1429            close the pop-up without saving.
1430          </para>
1431        </helptext>
1432
1433      </sect2>
1434
1435      <sect2 id="webclient.items.changeowner">
1436        <title>Change owner of items</title>
1437        <para>
1438          Sometimes it may be necessary to change the owner of an item.
1439          This can be done by everyone with <emphasis>Set owner</emphasis>
1440          permission on the item.
1441          For a user to have the rights to change owner of an item, the item must
1442          either be owned by or shared with <emphasis>Set owner</emphasis> 
1443          permission to the user .
1444          See <xref linkend="webclient.items.share" />.
1445        </para>
1446       
1447        <para>
1448          An user with <emphasis>Set owner</emphasis> permission can go to a list view
1449          (or the single-item view), mark the checkboxes for the items to change owner of,
1450          and click on the <guibutton>Set owner</guibutton> button. 
1451          A dialog window, like the screen-shot below, will appear.
1452        </para>
1453        <helptext external_id="ownership.configure" title="Change owner">
1454        <variablelist>
1455        <varlistentry>
1456          <term><guilabel>New owner</guilabel></term>
1457          <listitem>
1458          <para>
1459            The user to be the new owner of selected item(s).
1460            By default the current user will be selected but other
1461            users can be picked from the <emphasis>currently used</emphasis> part of the drop-down
1462            list or by clicking on <guibutton>Select</guibutton>.
1463          </para>
1464          </listitem>
1465        </varlistentry>
1466        </variablelist>
1467        <para>
1468          Use the &gbSave; button to set the new owner
1469          or the &gbCancel; button to
1470          close the pop-up without saving.
1471        </para>
1472        </helptext> 
1473        <figure id="webclient.figures.selectowner">
1474          <title>Select a new owner</title>
1475          <screenshot>
1476            <mediaobject>
1477              <imageobject><imagedata fileref="figures/select_owner.png" format="PNG"
1478                scalefit="1" width="100%" /></imageobject>
1479            </mediaobject>
1480          </screenshot>
1481        </figure>
1482       
1483        <note>
1484          <para>
1485          The original owner may not have access permissions to the items
1486          any longer. If that is desired, the new owner must share the items
1487          to the original owner.
1488          </para>
1489        </note>
1490       
1491      </sect2>
1492     
1493    </sect1>
1494   
1495    <sect1 id="webclient.itemlist">
1496      <?dbhtml filename="lists.html" ?>
1497      <title>Listing items</title>
1498     
1499      <para>
1500        All pages that lists items are very similar in their appearance and
1501        functionality. In this section we will describe the things that are
1502        common for most (if not all) list pages.
1503      </para>
1504     
1505      <para>
1506        Use the menu to open a page listing items. Most list pages can only list one type of
1507        items. For example: use the
1508        <menuchoice>
1509          <guimenu>View</guimenu>
1510          <guimenuitem>Samples</guimenuitem>
1511        </menuchoice>
1512        menu to list samples and the
1513        <menuchoice>
1514          <guimenu>View</guimenu>
1515          <guimenuitem>Experiments</guimenuitem>
1516        </menuchoice>
1517        menu to list experiments.
1518      </para>
1519
1520      <tip>
1521        An example of a list page that can list
1522        items of several types is found by going to
1523        <menuchoice>
1524          <guimenu>View</guimenu>
1525          <guimenuitem>All items</guimenuitem>
1526        </menuchoice>.
1527        This page lists all items that you are the owner of. It has a few limitations:
1528       
1529        <itemizedlist>
1530          <listitem>
1531            <para>
1532              It support only a limited set of columns (id, item type, name and description)
1533              since these are the only properties that are common among all items. It is also
1534              possible to display sharing information.
1535            </para>
1536          </listitem>
1537         
1538          <listitem>
1539            <para>
1540              The list may have not have full support for filtering and
1541              sorting. This is due to a limitation in the
1542              query system used to generate the list.
1543            </para>
1544          </listitem>
1545        </itemizedlist>
1546       
1547        <para>
1548          There are also several similarities:
1549        </para>
1550       
1551        <itemizedlist>
1552          <listitem>
1553            <para>
1554              It supports all of the regular multi-item
1555              operations such as delete, restore, share
1556              and change owner.
1557            </para>
1558          </listitem>
1559         
1560          <listitem>
1561            <para>
1562              Clicking on the name of the item will take you to the
1563              single-item view of that item. Holding down <keycap>CTRL</keycap>,
1564              <keycap>ALT</keycap> or <keycap>SHIFT</keycap> while clicking,
1565              will open the edit pop-up.
1566            </para>
1567          </listitem>
1568        </itemizedlist>       
1569       
1570      </tip>
1571     
1572      <figure id="webclient.figures.listpage">
1573        <title>A typical list page</title>
1574        <screenshot>
1575          <mediaobject>
1576            <imageobject><imagedata fileref="figures/listpage.png" format="PNG"
1577              scalefit="1" width="100%" /></imageobject>
1578          </mediaobject>
1579        </screenshot>
1580      </figure>
1581     
1582      <para>
1583        The typical list page contains the following important
1584        elements:
1585      </para>
1586
1587      <variablelist>
1588        <varlistentry>
1589          <term><interface>1. Toolbar</interface></term>
1590          <listitem>
1591            <para>
1592            A toolbar with buttons for various actions such as
1593            &gbNew; for creating a new item,
1594            &gbDelete; for deleting items and
1595            <guibutton>Columns&hellip;</guibutton> for configuring columns.
1596            Depending on the permissions of the logged in user
1597            some buttons may be disabled (greyed out) or not shown at all.
1598            </para>
1599          </listitem>
1600        </varlistentry>
1601       
1602        <varlistentry>
1603          <term><interface>2. Navigation bar</interface></term>
1604          <listitem>
1605            <para>
1606            If there are many items the list will be divided into
1607            pages, each one showing a limited number of items.
1608            The navigation bar allows you to
1609            move to other pages and specify how many items each page
1610            should display. The navigation bar is repeated at the
1611            bottom of the list so you do not have to scroll back to the
1612            top of a long list just to get to another page.
1613            </para>
1614          </listitem>
1615        </varlistentry>
1616       
1617        <varlistentry>
1618          <term><interface>3. List of presets</interface></term>
1619          <listitem>
1620            <para>
1621            A list with preconfigured settings which allows you to
1622            quickly switch between different layouts (sort order, visible
1623            columns, filter settings, etc).
1624            </para>
1625          </listitem>
1626        </varlistentry>
1627       
1628        <varlistentry>
1629          <term><interface>4. Column headers</interface></term>
1630          <listitem>
1631            <para>
1632            The columns headers can be used for selecting sort order.
1633            </para>
1634          </listitem>
1635        </varlistentry>
1636       
1637        <varlistentry>
1638          <term><interface>5. Filter bar</interface></term>
1639          <listitem>
1640            <para>
1641            The filter bar allows you to search for items.
1642            </para>
1643          </listitem>
1644        </varlistentry>
1645       
1646      </variablelist>
1647     
1648     
1649      <sect2 id="webclient.itemlist.order">
1650        <title>Ordering the list</title>
1651       
1652        <para>
1653          Most lists are by default sorted by the name of the item. This can
1654          be changed by clicking on the column header of another column.
1655          If you click on the same column twice the sort order is reversed.
1656          A downwards or upwards pointing arrow is displayed next to the
1657          column header in the column that is currently used for sorting.
1658          Column headers that are black cannot be used for sorting.
1659        </para>
1660       
1661        <para>
1662          It is possible to use more than one column for sorting. Press
1663          and hold one of the <keycap>CTRL</keycap>,
1664          <keycap>ALT</keycap> or <keycap>SHIFT</keycap> keys while clicking
1665          on another column header. The original sorting is kept and the new
1666          column is used for sub-sorting the list. The procedure can be
1667          repeated with more columns if you need to sort on three or more
1668          columns. To revert to sort by only one column again click a
1669          column header without holding down any key.
1670        </para> 
1671      </sect2>
1672   
1673      <sect2 id="webclient.itemlist.filter">
1674        <title>Filtering the list</title>
1675       
1676        <para>
1677          If the list contains many items you may need to use a filter to be
1678          able to find the item you are looking for. The input boxes on the
1679          line below the column headers are used for filtering. Most columns
1680          are filtered using a free-text input box, but some columns that can
1681          only take a few distinct values use a selection list or radio buttons
1682          instead. The selection list and radio buttons are very simple to use.
1683          Just select the alternative that you want to filter on. The list
1684          will be automatically updated when the selection has been made.
1685        </para>
1686       
1687        <para>
1688          The free-text filter is a bit more complex. By default, an exact match is
1689          required, use % as a wildcard character that matches any character.
1690          For example, the filter <informalexample>Experiment A</informalexample> 
1691          only matches the same exact string, but the filter
1692          <informalexample>Exp%</informalexample> matches
1693          <informalexample>Experiment A, Experiment B, etc.</informalexample>
1694        </para>
1695        <para>
1696          If you want to filter on several values at the same time, separate the
1697          values in the filter input box with the <quote>|</quote> character.
1698          For example, a filter text like <informalexample>Experiment A|C%</informalexample>
1699          matches both <quote>Experiment A</quote> and values 
1700          that begin with <quote>C</quote>.
1701        </para>       
1702        <para>
1703          You can also use operators to find items which has a value that
1704          is greater than, less than or not equal to a specific value. This is
1705          mostly useful on numeric or date columns but also works on text
1706          columns. The operator must be entered first in the
1707          free-text box, for example
1708          <informalexample>&lt;=10</informalexample>
1709          to find items which has a value less than or equal to 10.   
1710          Here is a list of the supported operators:
1711        </para>
1712       
1713        <variablelist id="webclient.itemlist.filter.operators">
1714          <title>List of operators supported by the free-text filter</title>
1715          <varlistentry>
1716            <term><keycap>&lt;</keycap></term>
1717            <listitem><simpara>Less than</simpara></listitem>
1718          </varlistentry>
1719          <varlistentry>
1720            <term><keycap>&lt;=</keycap></term>
1721            <listitem><simpara>Less than or equal to</simpara></listitem>
1722          </varlistentry>
1723          <varlistentry>
1724            <term><keycap>&gt;</keycap></term>
1725            <listitem><simpara>Greater than</simpara></listitem>
1726          </varlistentry>
1727          <varlistentry>
1728            <term><keycap>&gt;=</keycap></term>
1729            <listitem><simpara>Greater than or equal to</simpara></listitem>
1730          </varlistentry>
1731          <varlistentry>
1732            <term><keycap>=</keycap></term>
1733            <listitem>
1734              <simpara>
1735                Equal to (useful to find items with a null value). Supports
1736                filtering on more then one value.
1737              </simpara>
1738            </listitem>
1739          </varlistentry>
1740          <varlistentry>
1741            <term><keycap>&lt;&gt;</keycap></term>
1742            <term><keycap>!=</keycap></term>
1743            <listitem>
1744              <simpara>
1745                Not equal to (useful to find items with a non-null value). Supports
1746                filtering on more then one value.
1747              </simpara>
1748            </listitem>
1749          </varlistentry>
1750          <varlistentry>
1751            <term><keycap>==</keycap></term>
1752            <listitem>
1753              <simpara>
1754                Same as <keycap>=</keycap> but interprets <quote>|</quote>, <quote>%</quote> 
1755                and other special characters literally. Use this when you need an exact
1756                string match.
1757              </simpara>
1758            </listitem>
1759          </varlistentry>
1760        </variablelist>
1761       
1762        <sect3 id="webclient.itemlist.filter.units">
1763          <title>Units</title>
1764          <para>
1765            Some (numeric) columns have values with units. There are, for example,
1766            the <emphasis>Original quantity</emphasis> and <emphasis>Remaining quantity</emphasis>
1767            columns for biomaterials, which have values in micrograms (µg), and
1768            annotations which may have any unit.
1769          </para>
1770          <para>
1771            When filtering on a column that has a unit, numeric values without units are
1772            interpreted as the default unit for that column. But it is also possible to
1773            add a unit to the filter value. The examples below are filtering on the
1774            original quantity column of a biomaterial:
1775          </para>
1776          <para>
1777            <informalexample>&gt;=0.5mg</informalexample> matches biomaterials with
1778            an original quantity &gt;=500µg.
1779          </para>
1780          <para>
1781            <informalexample>=100|200|300µg</informalexample> matches biomaterials with
1782            exactly 100, 200 or 300 micrograms.
1783          </para>
1784          <para>
1785            It is also possible to mix units in a single filter:
1786            <informalexample>=100|200|300µg|0.5|1mg</informalexample> which matches
1787            100, 200, 300, 500 and 1000 micrograms.
1788          </para>
1789         
1790          <warning>
1791            <title>Be aware of rounding errors</title>
1792            <para>
1793              All filter values with a unit that is different from the default
1794              unit are converted to the default unit before being applied. Since
1795              numeric conversions are never exact down to the last decimal, this may
1796              result in problems to filter with an exact match. The last example above
1797              could, for example, be converted to: 100, 200, 300, 500.000001 and
1798              999.99999998.
1799            </para>
1800          </warning>
1801         
1802          <tip>
1803            <title>Hard-to-type characters</title>
1804            <para>
1805              Some units contains hard-to-type characters. For example,
1806              the greek letter µ in µg, and m² and m³ for areas and volumes.
1807              In all those cases it is also possible to use ug, m2 and m3,
1808              respectively.
1809            </para>
1810          </tip>
1811         
1812          <note>
1813            <title>Units are case-sensitive</title>
1814            <para>
1815              All units are case sensitive. The main reason for this is that
1816              it must be possible to tell the difference between
1817              <emphasis>milli (m)</emphasis> and <emphasis>mega (M)</emphasis> 
1818              prefixes, for example, <emphasis>mJ</emphasis> and <emphasis>MJ</emphasis>.
1819            </para>
1820          </note>
1821         
1822        </sect3>
1823      </sect2>
1824     
1825      <sect2 id="webclient.itemlist.columns">
1826        <title>Configuring which columns to show</title>
1827       
1828        <para>
1829          Most lists show only a small subset of the columns it
1830          is capable of showing. Use the
1831          <guibutton>Columns&hellip;</guibutton> button to open
1832          a dialog that allows you to select which columns to show
1833          and the order in which they are shown.
1834        </para>
1835       
1836        <figure id="webclient.figures.configure_columns">
1837          <title>Configuring which columns to show</title>
1838          <screenshot>
1839          <mediaobject>
1840            <imageobject>
1841              <imagedata fileref="figures/configure_columns.png" format="PNG"/>
1842            </imageobject>
1843          </mediaobject>
1844          </screenshot>
1845        </figure>
1846       
1847        <helptext external_id="columns.configure" 
1848          title="Set column order and visiblity">
1849       
1850        <variablelist>
1851        <varlistentry>
1852          <term><guilabel>Visible columns</guilabel></term>
1853          <listitem>
1854            <para>
1855              Shows the columns that are currently visible.
1856              Use the up/down arrow buttons to arrange the order of the
1857              visible columns. The topmost column is shown to the left.
1858              Use the right arrow button to move columns from this list
1859              to the hidden columns list. Columns marked with an <guilabel>×</guilabel> 
1860              are required
1861              and cannot be hidden. In most lists the <guilabel>Name</guilabel> column
1862              is the only column that is required.
1863            </para>
1864          </listitem>
1865        </varlistentry>
1866         
1867        <varlistentry>
1868          <term><guilabel>Hidden columns</guilabel></term>
1869          <listitem>
1870            <para>
1871              Shows columns that are not currently visible in the
1872              list. Use the left arrow button to move columns from
1873              this list to the visible columns list.
1874            </para>
1875          </listitem>
1876        </varlistentry>
1877       
1878       
1879        <varlistentry>
1880          <term><guilabel>Presets</guilabel></term>
1881          <listitem>
1882            <para>
1883              A dropdown list that allows you to
1884              select a set of preconfigured columns. You may also create
1885              your own preset if you often need to switch between different
1886              configurations. The list of presets is the same as the one
1887              described <link linkend="webclient.itemlist.presets">below</link>,
1888              but if used from this dialog the presets only affects the visible columns
1889              and not filters or sort order.
1890            </para>
1891          </listitem>
1892        </varlistentry>
1893        </variablelist>
1894       
1895          <para>
1896            Use the &gbSave; button to apply your
1897            changes or the &gbCancel; button to
1898            close the pop-up without saving.
1899          </para>
1900
1901        </helptext>
1902
1903      </sect2>
1904     
1905      <sect2 id="webclient.itemlist.presets">
1906        <title>Presets</title>
1907       
1908        <para>
1909          The <guilabel>view / presets</guilabel> dropdown has three
1910          main functions:
1911        </para>
1912       
1913        <figure id="webclient.figures.viewpresets">
1914          <title>The view / presets dropdown</title>
1915          <screenshot>
1916            <mediaobject>
1917              <imageobject><imagedata fileref="figures/view_presets.png" format="PNG" 
1918                /></imageobject>
1919            </mediaobject>
1920          </screenshot>
1921        </figure>
1922        <orderedlist>
1923          <listitem>
1924            <para>
1925              Switch between different configuration presets.
1926              The top of the dropdown contains user-defined presets (<guilabel>Saved preset #1</guilabel> and
1927              <guilabel>#2</guilabel>) and a few preconfigured presets.
1928              The user-defined presets are used to store a complete table configuration,
1929              including:
1930            </para>
1931           
1932            <itemizedlist>
1933              <listitem><simpara>Which columns are visible and their order</simpara></listitem>
1934              <listitem><simpara>The column (or columns) used for sorting</simpara></listitem>
1935              <listitem><simpara>Filter settings</simpara></listitem>
1936              <listitem><simpara>The number of items per page and the current page</simpara></listitem>
1937            </itemizedlist>
1938           
1939            <para>             
1940              The preconfigured presets only affects
1941              the visible columns as follows:
1942            </para>
1943           
1944            <itemizedlist>
1945              <listitem>
1946                <para><guilabel>All columns</guilabel> - Show all columns.</para>
1947              </listitem>
1948              <listitem>
1949                <para><guilabel>Required columns</guilabel> - Show only the required columns.
1950                  Usually only the <guilabel>Name</guilabel> column is required.</para>
1951              </listitem>
1952              <listitem>
1953                <para><guilabel>Default columns</guilabel> - Show the default set of columns.</para>
1954              </listitem>
1955              <listitem>
1956                <para><guilabel>Other&hellip;</guilabel> -
1957                  Open the configure columns dialog box, described in
1958                  <xref linkend="webclient.itemlist.columns"/>.</para>
1959              </listitem>
1960            </itemizedlist>
1961           
1962          </listitem>
1963         
1964          <listitem>
1965            <para>
1966              Filter items by the removed status and the access
1967              permissions to an item.
1968            </para>
1969           
1970            <itemizedlist>
1971              <listitem>
1972                <para><guilabel>Removed</guilabel> - If checked, items that have been
1973                moved to the trashcan are shown, otherwise they are hidden.</para>
1974              </listitem>
1975              <listitem>
1976                <para><guilabel>Owned by me</guilabel> - If checked, items that the logged in user
1977                owns are displayed, otherwise they are hidden.</para>
1978              </listitem>
1979              <listitem>
1980                <para><guilabel>Shared to me</guilabel> - If checked, items that are owned
1981                by other users but shared to the logged in user are displayed, otherwise
1982                they are hidden.</para>
1983              </listitem>
1984              <listitem>
1985                <para><guilabel>In current project</guilabel> -
1986                  If checked, items that are linked with the current project are displayed,
1987                  otherwise they are hidden. It does not matter if the logged in user is the
1988                  owner or not. This option is only available if a project is active.
1989                </para>
1990              </listitem>
1991              <listitem>
1992                <para><guilabel>Owned by others</guilabel> -
1993                  This option is only available to administrators and will display
1994                  items that are owned by other users.
1995                </para>
1996              </listitem>
1997            </itemizedlist>
1998           
1999            <para>
2000              The default is to display item that the current user
2001              owns and, if a project is active, items in that project.
2002            </para>
2003           
2004          </listitem>
2005
2006          <listitem>
2007            <para>
2008              Administrate the presets
2009            </para>
2010            <itemizedlist>
2011              <listitem>
2012                <para><guilabel>Clear filter</guilabel> - Clears
2013                all filters.</para>
2014              </listitem>
2015             
2016              <listitem>
2017                <para><guilabel>Save as&hellip;</guilabel> - Save the
2018                current configuration as a preset.</para>
2019              </listitem>
2020
2021              <listitem>
2022                <para><guilabel>Manage&hellip;</guilabel> - Opens a dialog
2023                where you can remove saved presets. You can also load
2024                saved presets from the dialog, but it is quicker to just
2025                use the dropdown list for this.</para>
2026              </listitem>
2027            </itemizedlist>
2028          </listitem>
2029        </orderedlist>
2030       
2031        <sect3 id="webclient.itemlist.presets.saveas">
2032          <title>Save a preset</title>
2033         
2034          <para>
2035            If you select the <guilabel>Save as&hellip;</guilabel>
2036            option from the <guilabel>view / presets</guilabel> dropdown
2037            the <guilabel>Save preset as</guilabel> dialog is opened.
2038          </para>
2039         
2040          <figure id="webclient.figures.savepresetas">
2041            <title>Save preset as</title>
2042            <screenshot>
2043              <mediaobject>
2044                <imageobject><imagedata fileref="figures/save_preset.png" format="PNG" /></imageobject>
2045              </mediaobject>
2046            </screenshot>
2047          </figure>
2048         
2049          <helptext external_id="contexts.saveas" title="Save preset as">
2050         
2051          <variablelist>
2052          <varlistentry>
2053            <term><guilabel>For item</guilabel></term>
2054            <listitem>
2055              <para>
2056              The type of item the preset is saved for.
2057              </para>
2058            </listitem>
2059          </varlistentry>
2060          <varlistentry>
2061            <term><guilabel >Name</guilabel></term>
2062            <listitem>
2063              <para>
2064              The name of the preset. The name must be unique.
2065              </para>
2066            </listitem>
2067          </varlistentry>
2068          <varlistentry>
2069            <term><guilabel>Overwrite existing</guilabel></term>
2070            <listitem>
2071              <para>
2072              If a preset with the same name already exists, it is
2073              overwritten if this checkbox is checked.
2074              </para>
2075            </listitem>
2076          </varlistentry>
2077          <varlistentry>
2078            <term><guilabel>Public</guilabel></term>
2079            <listitem>
2080              <para>
2081              This options is only available for users
2082              which has the <emphasis>SHARE_TO_EVERYONE</emphasis>
2083              permission. If checked the preset is visible to
2084              all users.
2085              </para>
2086            </listitem>
2087          </varlistentry>
2088          </variablelist>
2089         
2090          <para>
2091            Use the &gbOk; button to save the preset
2092            or the &gbCancel; button to
2093            close the pop-up without saving.
2094          </para>
2095         
2096         
2097          </helptext>
2098         
2099        </sect3>
2100       
2101        <sect3 id="webclient.itemlist.presets.manage">
2102          <title>Manage presets</title>
2103         
2104          <para>
2105            If you select the <guilabel>Manage&hellip;</guilabel>
2106            option from the <guilabel>view / presets</guilabel> dropdown
2107            the <guilabel>Manage presets</guilabel> dialog is opened.
2108          </para>
2109         
2110          <figure id="webclient.figures.managepresets">
2111            <title>Manage presets</title>
2112            <screenshot>
2113              <mediaobject>
2114                <imageobject><imagedata fileref="figures/manage_presets.png" format="PNG" /></imageobject>
2115              </mediaobject>
2116            </screenshot>
2117          </figure>
2118         
2119          <helptext external_id="contexts.manage" title="Manage presets">
2120         
2121          <para>
2122            From this dialog you can delete or load presets.
2123          </para>
2124         
2125          <para>
2126            To delete presets, first mark the checkbox in front of
2127            each preset you want to delete. Then, click on the
2128            <guibutton>Delete&hellip;</guibutton> button. You will get
2129            a warning about that the action cannot be undone. Unlike other
2130            items, the presets are not moved to the trashcan. Click on
2131            &gbOk; to delete the preset.
2132          </para>
2133         
2134          <note>
2135            <title>Edit a preset</title>
2136            <para>
2137            It is not possible to edit a preset directly. To change an
2138            existing preset you must:
2139           
2140            <orderedlist>
2141            <listitem><simpara>Load the preset.</simpara></listitem>
2142            <listitem><simpara>Use the interface to change column settings, filter,
2143              sort order, etc.</simpara></listitem>
2144            <listitem><simpara>Save the preset with the same name.</simpara></listitem>
2145            </orderedlist>
2146            </para>
2147          </note>
2148         
2149          <para>
2150            Use the &gbClose; button to
2151            close the pop-up.
2152          </para>
2153         
2154         
2155          </helptext>
2156         
2157        </sect3>
2158       
2159      </sect2>
2160    </sect1>
2161
2162
2163    <sect1 id="webclient.trashcan">
2164      <?dbhtml filename="trashcan.html" ?>
2165      <title>Trashcan</title>
2166      <para>
2167        All items that have been deleted, and are owned by you, are
2168        listed in your trashcan. This list page is accessed with
2169        <menuchoice>
2170          <guimenu>View</guimenu>
2171          <guimenuitem>Trashcan</guimenuitem>
2172        </menuchoice>
2173        and it differs a bit from the other common list pages. The
2174        most significant difference is that the trashcan page can
2175        contain more then one item type, actually all removable item
2176        types in BASE can be listed in the trashcan. Items that neither
2177        can be removed or deleted, <emphasis>i.e.,</emphasis> items
2178        like sessions, nor clients' help texts since these are deleted
2179        from the database immediately in list/item view will be shown
2180        in the trashcan page.
2181      </para>
2182      <warning>
2183        <para>
2184          Some item types do not have any owner and these are listed
2185          in the trashcans for everyone with delete permission on that
2186          specific item type.
2187        </para>
2188      </warning>
2189
2190      <para>
2191        Things that the trashcan page have in common with other list
2192        pages are the possibility to restore and view/edit items, see
2193        <xref linkend="webclient.items.restore" /> and
2194        <xref linkend="webclient.items.edit" /> . If an item is
2195        restored, it will of course disappear from the trashcan.
2196      </para>
2197
2198      <sect2 id="webclient.trashcan.deleteitem">
2199        <title>Delete items permanently</title>
2200        <para>
2201          Items can be permanently deleted from BASE only if they are
2202          not used by other items.  Items that are used have the icon
2203          <inlinemediaobject>
2204            <imageobject>
2205              <imagedata fileref="figures/isused.gif" format="GIF" />
2206            </imageobject>
2207          </inlinemediaobject>
2208          in the first column and by clicking on it you can get more
2209          information about the dependencies, see
2210          <xref linkend="webclient.trashcan.viewdependencies" /> .
2211          <note>
2212            <simpara>
2213              This view is NOT the same view page as when clicking on
2214              the item's name, which brings you to the item's view
2215              page.
2216            </simpara>
2217          </note>
2218        </para>
2219        <para>
2220          To delete one or several items permanently from the trashcan
2221          you first have to select them and then to click on the
2222          &gbDelete; button. Press then on either &gbOk; (completes
2223          the deletion) or &gbCancel; (no items will be deleted) in
2224          the dialog window that appears.
2225        </para>
2226
2227        <sect3 id="webclient.trashcan.deleteitem.empty">
2228          <title>Empty trashcan</title>
2229          <para>
2230            If all items in the trashcan should be deleted permanently
2231            the <guibutton>Empty trash</guibutton> button can be
2232            used. This function will remove all items that are listed
2233            in your trashcan, except those items which other items,
2234            not marked for deletion or cannot be deleted, are
2235            dependent on.
2236          </para>
2237        </sect3>
2238      </sect2>
2239
2240      <sect2 id="webclient.trashcan.viewdependencies">
2241        <title>View dependencies of a trashed item</title>
2242        <helptext external_id="trash.view.properties" title="Properties for a trashed item">
2243          <para>
2244            This view can only be accessed from trashed items that are
2245            linked together with other items. Beside the item's
2246            <guilabel>item type</guilabel>, <guilabel>name</guilabel>,
2247            and <guilabel>description</guilabel> there is a list at
2248            the bottom of the view page with those items that are
2249            using the current item in some way.
2250          </para>
2251        </helptext>
2252        <para>
2253          <nohelp>
2254            <figure id="webclient.trashcan.figures.viewtrasheditem">
2255              <title>Item view of a trashed item.</title>
2256              <screenshot>
2257                <mediaobject>
2258                  <imageobject>
2259                    <imagedata fileref="figures/trashview.png" format="PNG" 
2260                               scalefit="1" width="100%" />
2261                  </imageobject>
2262                </mediaobject>
2263              </screenshot>
2264            </figure>
2265          </nohelp>
2266          <orderedlist>
2267            <listitem>
2268              <para>
2269                This icon indicates that the item cannot be deleted
2270                permanently cause of some dependencies, see
2271                #<xref linkend="webclient.trashcan.lists.dependentitem3" />.
2272              </para>
2273            </listitem>
2274            <listitem>
2275              <para>Common properties for all removable items.</para>
2276            </listitem>
2277            <listitem id="webclient.trashcan.lists.dependentitem3">
2278              <para>A list of other items that are using the current item.</para>
2279            </listitem>
2280          </orderedlist>
2281        </para>
2282      </sect2>
2283    </sect1>
2284   
2285  <sect1 id="webclient.itemoverview">
2286    <?dbhtml filename="itemoverview.html" ?>
2287    <title>Item overview</title>
2288
2289    <helptext external_id="item.overview" 
2290      title="Item overview">
2291   
2292    <para>
2293      With the <guilabel>Item overview</guilabel> 
2294      function you can get an overview of all bioassays,
2295      extracts, samples, annotations, raw data sets, etc. that are
2296      related to a given item. In the overview you can also validate
2297      the data to find possibly missing or incorrect information.
2298    </para>
2299   
2300    <nohelp>
2301    <para>
2302      You can access the overview for an item by navigating
2303      to the single-item view of the item you are interested in.
2304      Then, switch to the <guilabel>Overview</guilabel> tab that
2305      is present on that page. Here is an example of what is displayed:
2306    </para>
2307   
2308    <figure id="webclient.figures.itemoverview">
2309      <title>The item overview</title>
2310      <screenshot>
2311        <mediaobject>
2312          <imageobject><imagedata 
2313            scalefit="1" width="100%"
2314            fileref="figures/item_overview.png" format="PNG"
2315            /></imageobject>
2316        </mediaobject>
2317      </screenshot>
2318    </figure>
2319    </nohelp>
2320   
2321    <para>
2322      The page is divided into three sections:
2323    </para>
2324   
2325    <itemizedlist>
2326      <listitem>
2327        <para>
2328        To the left is a tree displaying items that are related
2329        to the current item. The tree is loaded gradually when
2330        you click your way through the sublevels.
2331        The only exception is after a validation has been done,
2332        in this case the whole tree is loaded through the validation-process.               
2333        </para>
2334      </listitem>
2335     
2336      <listitem>
2337        <para>
2338        The lower right shows a list of warnings and error
2339        messages that was found when validating the data.
2340        This section is empty if no validation has been done.
2341        Click on the <guibutton>Validate</guibutton> button
2342        to validate the data and load errors and warnings.       
2343        <nohelp>
2344          In the example you can see that we have failed to
2345          specify a value for the <guilabel>Temperature</guilabel> 
2346          protocol parameter for one of the samples.
2347        </nohelp> 
2348        </para>
2349      </listitem>
2350       
2351      <listitem>
2352        <para>
2353          The upper right shows information about the
2354          currently selected item in the tree. This part will also
2355          contain more information about errors or warnings for this
2356          item, but only if a validation has been done.
2357          It may also present you with one or more suggestions
2358          about how to fix the problem and with a link that
2359          takes you to the most probable location where you can fix
2360          the error or warning.
2361        </para>
2362       
2363        <note>
2364          <title>No links?</title>
2365          If you do not have permission to change things no links
2366          will be shown.
2367        </note>
2368       
2369      </listitem>
2370       
2371    </itemizedlist>
2372   
2373    <seeother>
2374      <other external_id="item.overview.validationoptions"
2375        >Validation options</other>
2376      <other external_id="item.overview.fixfailures"
2377        >How to fix validation failures</other>
2378    </seeother>
2379   
2380    </helptext>
2381   
2382    <sect2 id="webclient.itemoverview.validationoptions">
2383      <title>Validation options</title>
2384      <para>
2385        Click on the <guibutton>Validation options</guibutton>
2386        button in the toolbar to open the <guilabel>Validation
2387        options</guilabel> dialog.
2388      </para>
2389     
2390      <figure id="webclient.figures.validationoptions">
2391        <title>Validation options</title>
2392        <screenshot>
2393          <mediaobject>
2394            <imageobject><imagedata 
2395              fileref="figures/validation_options.png" format="PNG"
2396              /></imageobject>
2397          </mediaobject>
2398        </screenshot>
2399      </figure>         
2400     
2401      <helptext external_id="item.overview.validationoptions" 
2402        title="Validation options">
2403        <para>
2404          The validation procedure is highly
2405          configurable and you can select what you want to
2406          ignore, and what should be displayed as an error
2407          or warning.
2408        </para>
2409       
2410        <variablelist>
2411          <varlistentry>
2412            <term>
2413            <guilabel>Presets</guilabel></term>
2414            <listitem>
2415              <para>
2416              The list contains predefined and
2417              user defined validation options.
2418              Use the <guibutton>Save as&hellip;</guibutton>
2419              button to save the current options as a user defined
2420              preset. The <guibutton>Remove&hellip;</guibutton>
2421              button is used to remove the currently selected
2422              preset. Predefined presets cannot be deleted.
2423              </para>
2424            </listitem>
2425          </varlistentry>
2426         
2427          <varlistentry>
2428            <term><guilabel>Project defaults</guilabel></term>
2429            <listitem>
2430              <para>
2431              The options in this section are used to check
2432              if your experiment uses the same values as set
2433              by the project default values of the currently active
2434              project<nohelp>
2435              (see <xref linkend="project_permission.projects" />)</nohelp>.
2436              If no project is active or if the active project does not
2437              have default values these options are ignored.
2438              </para>
2439            </listitem>
2440           
2441          </varlistentry>
2442         
2443          <varlistentry>
2444            <term><guilabel>Missing items</guilabel></term>
2445            <listitem>
2446              <para>
2447              The options in this section are used to check if
2448              you have specified values for optional items.
2449              For example, there is an option that warns you if
2450              you have not specified a protocol.
2451              </para>
2452            </listitem>
2453          </varlistentry>
2454         
2455          <varlistentry>
2456            <term><guilabel>Subtypes</guilabel></term>
2457            <listitem>
2458              <para>
2459              The options in this section are used to check that related items
2460              have a subtype that matches the subtype of the main item. For example,
2461              if we have an <emphasis>extract</emphasis>
2462              which is a <emphasis>labeled extract</emphasis> subtype the subtype for
2463              the related tag should be <emphasis>label</emphasis>, but if the extract
2464              is a <emphasis>library</emphasis> the subtype of the tag should be
2465              <emphasis>barcode</emphasis>.
2466              </para>
2467            </listitem>
2468          </varlistentry>
2469
2470          <varlistentry>
2471            <term><guilabel>Annotations</guilabel></term>
2472            <listitem>
2473              <para>
2474              The options in this section are used to check
2475              problems related to annotations. The most
2476              important ones are listed here:
2477              </para>
2478             
2479              <itemizedlist>
2480              <listitem>
2481                <simpara>
2482                <emphasis>Missing MIAME annotation value</emphasis>:
2483                Checks that you have specified values
2484                for all annotations marked as
2485                <guilabel>Required for MIAME</guilabel>.
2486                </simpara>
2487              </listitem>
2488             
2489              <listitem>
2490                <simpara>
2491                <emphasis>Missing factor value</emphasis>:
2492                Checks that you have specified values for
2493                all annotations used as experimental factors in
2494                the experiment. This is only checked when an experiment
2495                is selected as the root item.
2496                </simpara>
2497              </listitem>
2498             
2499              <listitem>
2500                <simpara>
2501                <emphasis>Missing parameter value</emphasis>:
2502                Checks that you have specified values
2503                for all protocol parameters.
2504                </simpara>
2505              </listitem>
2506
2507              <listitem>
2508                <simpara>
2509                <emphasis>Annotation is protocol parameter</emphasis>:
2510                Checks if an item has been annotated with a
2511                an annotation that is actually a protocol parameter.
2512                </simpara>
2513              </listitem>
2514
2515              <listitem>
2516                <simpara>
2517                <emphasis>Annotation has invalid value</emphasis>:
2518                Checks if annotation values are correct with
2519                respect to the rules given by the annotation type.
2520                This might include numeric values that are outside
2521                the valid range, or values not in the list
2522                of allows values for an enumerated annotation type.
2523                </simpara>
2524              </listitem>
2525
2526              <listitem>
2527                <simpara>
2528                <emphasis>Inheriting annotation from non-parent</emphasis>:
2529                Checks if inherited annotations really comes from a
2530                parent item. This might happen if you rearrange
2531                parent-child relationship because you found that
2532                they were incorrectly linked.
2533                </simpara>
2534              </listitem>
2535              </itemizedlist>
2536             
2537           
2538            </listitem>
2539          </varlistentry>
2540         
2541          <varlistentry>
2542            <term><guilabel>Files</guilabel></term>
2543            <listitem>
2544              <para>
2545              The options in this section are related to the validity of
2546              data files that can be attached to some items, for example,
2547              raw bioassays and array designs. The data files are usually
2548              validated immediately when they are used and the result is saved
2549              to the database. The options in this dialog can be used to find
2550              (or ignore) problems with data files.
2551              </para>
2552            </listitem>
2553          </varlistentry>
2554
2555         
2556          <varlistentry>
2557            <term><guilabel>Denied access</guilabel></term>
2558            <listitem>
2559              <para>
2560              The options in this section are used to
2561              check if you do not have access (read permission)
2562              to an item in the experiment hierarchy. If this
2563              happens the validation cannot proceed in that branch.
2564              This might mask other validation problems.
2565              </para>
2566            </listitem>
2567          </varlistentry>
2568         
2569          <varlistentry>
2570            <term><guilabel>Other</guilabel></term>
2571            <listitem>
2572              <para>
2573              This section collects options that does not fit
2574              into any of the other sections. The most
2575              important options are:
2576              </para>
2577             
2578              <itemizedlist>
2579                <listitem>
2580                  <simpara>
2581                  <emphasis>Array design mismatch</emphasis>:
2582                  Checks if the array design specified for
2583                  a raw bioassay is the same array design
2584                  specified for the physical bioassay.
2585                  </simpara>
2586                </listitem>
2587               
2588                <listitem>
2589                  <simpara>
2590                  <emphasis>Multiple array designs</emphasis>:
2591                  Checks if all raw bioassays in an experiment
2592                  use the same array design or not. This is only
2593                  checked when the root item is an experiment.
2594                  </simpara>
2595                </listitem>
2596             
2597                <listitem>
2598                  <simpara>
2599                  <emphasis>(Incorrect number of labled extracts)</emphasis>:
2600                  Checks if the number of labeled extracts
2601                  match the number of channels for the experiment.
2602                  This is only checked when the root item is an experiment.
2603                  </simpara>
2604                </listitem>
2605
2606                <listitem>
2607                  <simpara>
2608                  <emphasis>Non-unique name</emphasis>:
2609                  Checks if two items of the same type
2610                  have the same name. It is usually a good idea to
2611                  have unique names within an experiment if the data is
2612                  going to be exported and in other circumstances.
2613                  </simpara>
2614                </listitem>
2615
2616                <listitem>
2617                  <simpara>
2618                  <emphasis>Circular reference to pooled item</emphasis>:
2619                  If you have used pooling, checks that no
2620                  circular references have been created.
2621                  </simpara>
2622                </listitem>
2623             
2624              </itemizedlist>
2625             
2626            </listitem>
2627          </varlistentry>
2628         
2629        </variablelist>
2630       
2631        <para>
2632          Click on the &gbSave; button
2633          to use the current settings. The display will
2634          automatically refresh itself.
2635        </para>
2636       
2637      </helptext>
2638     
2639      <helptext external_id="item.overview.validationoptions.savepreset" 
2640        title="Save preset" webonly="1">
2641       
2642        <para>
2643        Saves all validation options as a preset.
2644        </para>
2645       
2646        <variablelist>
2647          <varlistentry>
2648            <term><guilabel>Name</guilabel></term>
2649            <listitem>
2650              <para>
2651                The name of the preset. The name must be unique
2652                and if a preset with the same name already exists
2653                you will be asked if you want to overwrite it or not.
2654              </para>
2655            </listitem>
2656          </varlistentry>
2657        </variablelist>
2658       
2659        <para>
2660          Click on the &gbSave; button
2661          to save the preset or &gbCancel;
2662          to abort.
2663        </para>
2664      </helptext>
2665     
2666    </sect2>
2667   
2668    <sect2 id="webclient.itemoverview.fixfailures">
2669      <title>Fixing validation failures</title>
2670      <helptext external_id="item.overview.fixfailures" 
2671        title="How to fix validation failures">
2672       
2673        <para>       
2674        The overview includes a function that allows
2675        you to quickly fix most of the problems found during the
2676        validation. The easiest way to use the function is:
2677        </para>
2678       
2679        <orderedlist>
2680          <listitem>
2681            <simpara>
2682            Click on an error or warning in the list of failures in
2683            the lower right
2684            pane. The tree in the left pane and the item overview in the
2685            top right pane will automatically be updated to show the
2686            exact location of the faulty item.
2687            </simpara>
2688          </listitem>
2689          <listitem>
2690            <simpara>
2691            The upper right pane should contain a list labeled
2692            <guilabel>Failure details</guilabel> with more information
2693            about each failure and also one or more suggestions for fixing
2694            the problem. For example, a failure due to a missing item
2695            should suggest that you add or select an item.
2696            </simpara>
2697          </listitem>
2698         
2699          <listitem>
2700            <simpara>
2701            The suggestions should also have links that takes
2702            you to an edit view where you can do the changes.
2703            </simpara>
2704          </listitem>
2705         
2706          <listitem>
2707            <simpara>
2708            After saving the changes you must click on the
2709            <guibutton>Validate</guibutton> button to update the
2710            interface. If you want, you can fix more than one
2711            failure before clicking on the button.
2712            </simpara>
2713          </listitem>
2714           
2715        </orderedlist>
2716     
2717      </helptext>
2718    </sect2>
2719   
2720  </sect1>
2721
2722</chapter>
Note: See TracBrowser for help on using the repository browser.