source: trunk/doc/src/docbook/admindoc/extensions.xml @ 4477

Last change on this file since 4477 was 4477, checked in by Jari Häkkinen, 14 years ago

Addresses #1106. Moving to GPLv3 in chunked commits.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Date Id
File size: 8.8 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: extensions.xml 4477 2008-09-05 15:15:25Z jari $
7
8  Copyright (C) 2007 Johan Enell, Jari Hakkinen, 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 this program; if not, write to the Free Software
25  Foundation, Inc., 59 Temple Place - Suite 330,
26  Boston, MA  02111-1307, USA.
27-->
28
29<chapter id="admin.extensions" chunked="0">
30  <?dbhtml dir="extensions"?>
31  <title>Extensions</title>
32
33  <para>
34    The BASE web client has an extension system that can be used to
35    add functionality to BASE. The extension system should not be confused
36    with plug-ins (<xref linkend="plugins"/>). Extensions are additions
37    to the user interface, for example, additional menus, toolbar buttons,
38    etc. Extensions are for the web interface only, they can not be used on
39    job agents, or by plug-ins. Plug-ins, on the other hand, are used to perform
40    some kind of work, for example, importing, exporing or analysing data,
41    and are not restricted to be used from the web client.
42  </para>
43 
44  <itemizedlist>
45    <title>More reading</title>
46    <listitem>
47      <para>
48      <xref linkend="extensions_developer" />.
49      </para>
50    </listitem>
51   
52    <listitem>
53      <para>
54      <xref linkend="api_overview.extensions" />.
55      </para>
56    </listitem>
57  </itemizedlist>
58
59  <sect1 id="admin.extensions.install">
60    <title>Installing extensions</title>
61   
62    <para>
63      The first step is to install the actual extension code on the
64      web server. Extensions are always packaged as XML or JAR
65      files. To install an extension put the XML or JAR file in
66      the <filename>&lt;base-dir&gt;/www/WEB-INF/extensions</filename>
67      folder. This is the only place were extensions can be installed.
68    </para>
69   
70    <para>
71      If you have enabled automatic installation you just have to wait
72      and the extensions will be installed and registered automatically.
73      Otherwise, you have to do a manual scan, using the following
74      instructions.
75    </para>
76   
77    <para>
78      Go to <menuchoice>
79        <guimenu>Extensions</guimenu>
80        <guimenuitem>Manual scan...</guimenuitem>
81      </menuchoice>
82    </para>
83   
84    <figure id="extensions.figures.manualscan">
85      <title>Manual scan</title>
86      <screenshot>
87        <mediaobject>
88          <imageobject>
89            <imagedata fileref="figures/manual_scan.png" format="PNG" />
90          </imageobject>
91        </mediaobject>
92      </screenshot>
93    </figure> 
94     
95    <helptext external_id="extensions.manualscan"
96      title="Perform manual scan">
97      <para>
98        Performs a manual scan for new, updated or
99        deleted extensions. If <guilabel>Force update</guilabel>
100        is checked, extensions that have not been modified
101        will also be re-registered. Leave this option unchecked unless
102        there is any problem with the extension system.
103      </para>
104     
105      <para>
106        Click on <guibutton>Start</guibutton> to start the scan.
107      </para>
108     
109      <seeother>
110        <other external_id="extensions.settings">Extension settings</other>
111      </seeother>
112    </helptext>
113   
114    <para>
115      If  everything goes well you should get a report of what happend.
116      The new XML or JAR file is hopefully listed as <guilabel>Installed</guilabel>.
117      Click on the <guilabel>+</guilabel> icons to show more details.
118    </para>
119   
120    <figure id="extensions.figures.scanresults">
121      <title>Scan results</title>
122      <screenshot>
123        <mediaobject>
124          <imageobject>
125            <imagedata fileref="figures/scan_results.png" format="PNG" />
126          </imageobject>
127        </mediaobject>
128      </screenshot>
129    </figure> 
130  </sect1>
131 
132  <sect1 id="admin.extensions.xjspcompiler">
133    <title>Installing the X-JSP compiler</title>
134    <para>
135      Some extensions may want to use custom JSP files that also uses
136      classes that are stored in the extension's JAR file. The problem
137      with this is that Tomcat usually doesn't know to look for classes
138      in the <filename>WEB-INF/extensions</filename> directory. To solve
139      this problem BASE ships with a X-JSP compiler that can do this.
140      This compiler has been mapped to files with a <code>.xjsp</code>
141      extension, which are just regular JSP files with a different extension.
142    </para>
143   
144    <para>
145      The X-JSP compiler must be installed into Tomcat's internal
146      library folder (<filename>$CATALINA_HOME/lib</filename>)
147      since this is the only place where Tomcat look for compilers. The installation
148      is easy. Simply copy <filename>&lt;base-dir&gt;/bin/jar/base2-xjsp-compiler.jar</filename>
149      to <filename>$CATALINA_HOME/lib</filename> and restart Tomcat.
150    </para>
151   
152    <note>
153      <title>X-JSP is experimental</title>
154      <para>
155        This is an experimental feature that depends on functionality
156        in Tomcat. It may or may not work with future versions of Tomcat.
157        The compiler will most likely not work with other servlet
158        containers.
159      </para>
160    </note>
161   
162  </sect1>
163 
164  <sect1 id="admin.extensions.configure">
165    <title>Configuring the extensions system</title>
166   
167    <para>
168      Go to <menuchoice>
169        <guimenu>Extensions</guimenu>
170        <guimenuitem>Installed extensions</guimenuitem>
171      </menuchoice> to display an overview of all installed extensions.
172    </para>
173   
174    <figure id="extensions.figures.installedextensions">
175      <title>Installed extensions</title>
176      <screenshot>
177        <mediaobject>
178          <imageobject>
179            <imagedata fileref="figures/installed_extensions.png" format="PNG" />
180          </imageobject>
181        </mediaobject>
182      </screenshot>
183    </figure> 
184   
185   
186    <helptext 
187      external_id="extensions.details.main" 
188      title="Installed extensions">
189     
190      <para>
191        The left-hand side of the screen shows you a tree with all installed
192        extensions, sorted by extension point and by file. Use the + and -
193        icons to expand and collapse parts of the tree. Click on an item
194        in the tree to display detailed information about it
195        on the right-hand side of the screen.
196      </para>
197     
198      <seeother>
199        <other external_id="extensions.settings">Settings</other>
200        <other external_id="extensions.manualscan">Manual scan</other>
201      </seeother>
202    </helptext>
203   
204    <sect2 id="admin.extensions.configure.settings">
205      <title>Settings</title>
206   
207      <para>
208        Click on the <guibutton>Settings...</guibutton> button to
209        display a popup dialog that allows you to changes some global
210        settings.
211      </para>
212   
213      <figure id="extensions.figures.settings">
214        <title>Extension settings</title>
215        <screenshot>
216          <mediaobject>
217            <imageobject>
218              <imagedata fileref="figures/extension_settings.png" format="PNG" />
219            </imageobject>
220          </mediaobject>
221        </screenshot>
222      </figure>
223     
224      <helptext external_id="extensions.settings"
225        title="Extension settings">
226       
227        <variablelist>
228        <varlistentry>
229          <term><guilabel>Auto-installation interval</guilabel></term>
230          <listitem>
231            <para>
232            The number of seconds between each check by the automatic
233            installer. Enter 0 to disable automatic installation.
234            The automatic installation performs the same steps as
235            a manual scan with the <guilabel>Force update</guilabel>
236            option unchecked. The default setting is to have the
237            automatic installation disabled and we don't recommend enabling
238            it in a production environment.
239            </para>
240          </listitem>
241        </varlistentry>
242        </variablelist>
243 
244        <para>
245          Click on &gbSave; to save the settings.
246        </para>
247       
248        <seeother>
249          <other external_id="extensions.manualscan">Manual scan</other>
250        </seeother>
251      </helptext>
252    </sect2>
253   
254    <sect2 id="admin.extensions.disable">
255      <title>Disable/enable extensions</title>
256     
257      <para>
258        It is possible to disable specific extensions and/or entire
259        extension points without uninstalling the XML or JAR file.
260        When you click on an extension or extension point in the
261        tree on the left-hand side of the screen a lot of detailed
262        information about it will show up on the right-hand side.
263      </para>
264     
265      <para>
266        The right-hand side will also have a <guibutton>Disable</guibutton>
267        button. Click on that button to disable the extension or all extensions
268        for an extension point. The button will change to <guibutton>Enable</guibutton>
269        which lets you enable the extension (point) again.
270      </para>
271    </sect2>
272   
273  </sect1>
274 
275</chapter>
Note: See TracBrowser for help on using the repository browser.