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

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

References #1641: Use bcrypt for storing passwords instead of MD5

This is now implemented in the core and web client and seems to be working good. The update script has not yet been fixed so upgrading will not work.

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