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

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

References #1655: GUI improvements

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