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

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

References #1590: Documentation cleanup

Re-orgarnized file/directory structure of documentation to make the paths a little bit shorter.

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