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

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

References #1590: Documentation cleanup

New screenshots for chapter 4 and 5 in User documentation (except for "Item overview" since it is not yet fully working). Minor changes in the texts.

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