source: branches/2.8-stable/doc/src/docbook/admindoc/extensions.xml @ 4504

Last change on this file since 4504 was 4504, checked in by Nicklas Nordborg, 14 years ago

Fixes #1080: Extensions: Manual scan fails.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Date Id
File size: 9.3 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE chapter PUBLIC
3    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
4    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
5<!--
6  $Id: extensions.xml 4504 2008-09-11 06:22:51Z nicklas $
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    <note>
71      <title>Make sure the extensions folder is writable by Tomcat</title>
72      <para>
73        The extension you are installing may include resources such as HTML
74        files, JSP scripts, images, etc. that needs to be extracted to the
75        web application path before they can be used. This extraction is
76        automatically done by the extensions system, but you have to make
77        sure that the user account Tomcat is running as has permission
78        to create (and delete) new files in the
79        <filename class="directory">&lt;base-dir&gt;/www/extensions</filename>
80        directory.
81      </para>
82    </note>
83   
84    <para>
85      If you have enabled automatic installation you just have to wait
86      and the extensions will be installed and registered automatically.
87      Otherwise, you have to do a manual scan, using the following
88      instructions.
89    </para>
90   
91    <para>
92      Go to <menuchoice>
93        <guimenu>Extensions</guimenu>
94        <guimenuitem>Manual scan...</guimenuitem>
95      </menuchoice>
96    </para>
97   
98    <figure id="extensions.figures.manualscan">
99      <title>Manual scan</title>
100      <screenshot>
101        <mediaobject>
102          <imageobject>
103            <imagedata fileref="figures/manual_scan.png" format="PNG" />
104          </imageobject>
105        </mediaobject>
106      </screenshot>
107    </figure> 
108     
109    <helptext external_id="extensions.manualscan"
110      title="Perform manual scan">
111      <para>
112        Performs a manual scan for new, updated or
113        deleted extensions. If <guilabel>Force update</guilabel>
114        is checked, extensions that have not been modified
115        will also be re-registered. Leave this option unchecked unless
116        there is any problem with the extension system.
117      </para>
118     
119      <para>
120        Click on <guibutton>Start</guibutton> to start the scan.
121      </para>
122     
123      <seeother>
124        <other external_id="extensions.settings">Extension settings</other>
125      </seeother>
126    </helptext>
127   
128    <para>
129      If  everything goes well you should get a report of what happend.
130      The new XML or JAR file is hopefully listed as <guilabel>Installed</guilabel>.
131      Click on the <guilabel>+</guilabel> icons to show more details.
132    </para>
133   
134    <figure id="extensions.figures.scanresults">
135      <title>Scan results</title>
136      <screenshot>
137        <mediaobject>
138          <imageobject>
139            <imagedata fileref="figures/scan_results.png" format="PNG" />
140          </imageobject>
141        </mediaobject>
142      </screenshot>
143    </figure> 
144  </sect1>
145 
146  <sect1 id="admin.extensions.xjspcompiler">
147    <title>Installing the X-JSP compiler</title>
148    <para>
149      Some extensions may want to use custom JSP files that also uses
150      classes that are stored in the extension's JAR file. The problem
151      with this is that Tomcat usually doesn't know to look for classes
152      in the <filename>WEB-INF/extensions</filename> directory. To solve
153      this problem BASE ships with a X-JSP compiler that can do this.
154      This compiler has been mapped to files with a <code>.xjsp</code>
155      extension, which are just regular JSP files with a different extension.
156    </para>
157   
158    <para>
159      The X-JSP compiler must be installed into Tomcat's internal
160      library folder (<filename>$CATALINA_HOME/lib</filename>)
161      since this is the only place where Tomcat look for compilers. The installation
162      is easy. Simply copy <filename>&lt;base-dir&gt;/bin/jar/base2-xjsp-compiler.jar</filename>
163      to <filename>$CATALINA_HOME/lib</filename> and restart Tomcat.
164    </para>
165   
166    <note>
167      <title>X-JSP is experimental</title>
168      <para>
169        This is an experimental feature that depends on functionality
170        in Tomcat. It may or may not work with future versions of Tomcat.
171        The compiler will most likely not work with other servlet
172        containers.
173      </para>
174    </note>
175   
176  </sect1>
177 
178  <sect1 id="admin.extensions.configure">
179    <title>Configuring the extensions system</title>
180   
181    <para>
182      Go to <menuchoice>
183        <guimenu>Extensions</guimenu>
184        <guimenuitem>Installed extensions</guimenuitem>
185      </menuchoice> to display an overview of all installed extensions.
186    </para>
187   
188    <figure id="extensions.figures.installedextensions">
189      <title>Installed extensions</title>
190      <screenshot>
191        <mediaobject>
192          <imageobject>
193            <imagedata fileref="figures/installed_extensions.png" format="PNG" />
194          </imageobject>
195        </mediaobject>
196      </screenshot>
197    </figure> 
198   
199   
200    <helptext 
201      external_id="extensions.details.main" 
202      title="Installed extensions">
203     
204      <para>
205        The left-hand side of the screen shows you a tree with all installed
206        extensions, sorted by extension point and by file. Use the + and -
207        icons to expand and collapse parts of the tree. Click on an item
208        in the tree to display detailed information about it
209        on the right-hand side of the screen.
210      </para>
211     
212      <seeother>
213        <other external_id="extensions.settings">Settings</other>
214        <other external_id="extensions.manualscan">Manual scan</other>
215      </seeother>
216    </helptext>
217   
218    <sect2 id="admin.extensions.configure.settings">
219      <title>Settings</title>
220   
221      <para>
222        Click on the <guibutton>Settings...</guibutton> button to
223        display a popup dialog that allows you to changes some global
224        settings.
225      </para>
226   
227      <figure id="extensions.figures.settings">
228        <title>Extension settings</title>
229        <screenshot>
230          <mediaobject>
231            <imageobject>
232              <imagedata fileref="figures/extension_settings.png" format="PNG" />
233            </imageobject>
234          </mediaobject>
235        </screenshot>
236      </figure>
237     
238      <helptext external_id="extensions.settings"
239        title="Extension settings">
240       
241        <variablelist>
242        <varlistentry>
243          <term><guilabel>Auto-installation interval</guilabel></term>
244          <listitem>
245            <para>
246            The number of seconds between each check by the automatic
247            installer. Enter 0 to disable automatic installation.
248            The automatic installation performs the same steps as
249            a manual scan with the <guilabel>Force update</guilabel>
250            option unchecked. The default setting is to have the
251            automatic installation disabled and we don't recommend enabling
252            it in a production environment.
253            </para>
254          </listitem>
255        </varlistentry>
256        </variablelist>
257 
258        <para>
259          Click on &gbSave; to save the settings.
260        </para>
261       
262        <seeother>
263          <other external_id="extensions.manualscan">Manual scan</other>
264        </seeother>
265      </helptext>
266    </sect2>
267   
268    <sect2 id="admin.extensions.disable">
269      <title>Disable/enable extensions</title>
270     
271      <para>
272        It is possible to disable specific extensions and/or entire
273        extension points without uninstalling the XML or JAR file.
274        When you click on an extension or extension point in the
275        tree on the left-hand side of the screen a lot of detailed
276        information about it will show up on the right-hand side.
277      </para>
278     
279      <para>
280        The right-hand side will also have a <guibutton>Disable</guibutton>
281        button. Click on that button to disable the extension or all extensions
282        for an extension point. The button will change to <guibutton>Enable</guibutton>
283        which lets you enable the extension (point) again.
284      </para>
285    </sect2>
286   
287  </sect1>
288 
289</chapter>
Note: See TracBrowser for help on using the repository browser.