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

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC 
    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN" 
    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
<!--
  $Id: extensions.xml 4504 2008-09-11 06:22:51Z nicklas $

  Copyright (C) 2007 Johan Enell, Jari Hakkinen, Peter Johansson, Nicklas Nordborg, Martin Svensson

  This file is part of BASE - BioArray Software Environment.
  Available at http://base.thep.lu.se/

  BASE is free software; you can redistribute it and/or
  modify it under the terms of the GNU General Public License
  as published by the Free Software Foundation; either version 3
  of the License, or (at your option) any later version.

  BASE is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place - Suite 330,
  Boston, MA  02111-1307, USA.
-->

<chapter id="admin.extensions" chunked="0">
  <?dbhtml dir="extensions"?>
  <title>Extensions</title>

  <para>
    The BASE web client has an extension system that can be used to
    add functionality to BASE. The extension system should not be confused
    with plug-ins (<xref linkend="plugins"/>). Extensions are additions
    to the user interface, for example, additional menus, toolbar buttons, 
    etc. Extensions are for the web interface only, they can not be used on
    job agents, or by plug-ins. Plug-ins, on the other hand, are used to perform 
    some kind of work, for example, importing, exporing or analysing data, 
    and are not restricted to be used from the web client.
  </para>
  
  <itemizedlist>
    <title>More reading</title>
    <listitem>
      <para>
      <xref linkend="extensions_developer" />.
      </para>
    </listitem>
    
    <listitem>
      <para>
      <xref linkend="api_overview.extensions" />.
      </para>
    </listitem>
  </itemizedlist>

  <sect1 id="admin.extensions.install">
    <title>Installing extensions</title>
    
    <para>
      The first step is to install the actual extension code on the
      web server. Extensions are always packaged as XML or JAR
      files. To install an extension put the XML or JAR file in
      the <filename>&lt;base-dir&gt;/www/WEB-INF/extensions</filename>
      folder. This is the only place were extensions can be installed.
    </para>
    
    <note>
      <title>Make sure the extensions folder is writable by Tomcat</title>
      <para>
        The extension you are installing may include resources such as HTML
        files, JSP scripts, images, etc. that needs to be extracted to the 
        web application path before they can be used. This extraction is
        automatically done by the extensions system, but you have to make
        sure that the user account Tomcat is running as has permission
        to create (and delete) new files in the 
        <filename class="directory">&lt;base-dir&gt;/www/extensions</filename>
        directory.
      </para>
    </note>
    
    <para>
      If you have enabled automatic installation you just have to wait
      and the extensions will be installed and registered automatically.
      Otherwise, you have to do a manual scan, using the following 
      instructions.
    </para>
    
    <para>
      Go to <menuchoice>
        <guimenu>Extensions</guimenu>
        <guimenuitem>Manual scan...</guimenuitem>
      </menuchoice>
    </para>
    
    <figure id="extensions.figures.manualscan">
      <title>Manual scan</title>
      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/manual_scan.png" format="PNG" />
          </imageobject>
        </mediaobject>
      </screenshot>
    </figure> 
      
    <helptext external_id="extensions.manualscan"
      title="Perform manual scan">
      <para>
        Performs a manual scan for new, updated or
        deleted extensions. If <guilabel>Force update</guilabel>
        is checked, extensions that have not been modified 
        will also be re-registered. Leave this option unchecked unless
        there is any problem with the extension system. 
      </para>
      
      <para>
        Click on <guibutton>Start</guibutton> to start the scan.
      </para>
      
      <seeother>
        <other external_id="extensions.settings">Extension settings</other>
      </seeother>
    </helptext>
    
    <para>
      If  everything goes well you should get a report of what happend. 
      The new XML or JAR file is hopefully listed as <guilabel>Installed</guilabel>.
      Click on the <guilabel>+</guilabel> icons to show more details.
    </para>
    
    <figure id="extensions.figures.scanresults">
      <title>Scan results</title>
      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/scan_results.png" format="PNG" />
          </imageobject>
        </mediaobject>
      </screenshot>
    </figure> 
  </sect1>
  
  <sect1 id="admin.extensions.xjspcompiler">
    <title>Installing the X-JSP compiler</title>
    <para>
      Some extensions may want to use custom JSP files that also uses
      classes that are stored in the extension's JAR file. The problem
      with this is that Tomcat usually doesn't know to look for classes
      in the <filename>WEB-INF/extensions</filename> directory. To solve
      this problem BASE ships with a X-JSP compiler that can do this.
      This compiler has been mapped to files with a <code>.xjsp</code>
      extension, which are just regular JSP files with a different extension.
    </para>
    
    <para>
      The X-JSP compiler must be installed into Tomcat's internal
      library folder (<filename>$CATALINA_HOME/lib</filename>)
      since this is the only place where Tomcat look for compilers. The installation 
      is easy. Simply copy <filename>&lt;base-dir&gt;/bin/jar/base2-xjsp-compiler.jar</filename>
      to <filename>$CATALINA_HOME/lib</filename> and restart Tomcat.
    </para>
    
    <note>
      <title>X-JSP is experimental</title>
      <para>
        This is an experimental feature that depends on functionality
        in Tomcat. It may or may not work with future versions of Tomcat.
        The compiler will most likely not work with other servlet 
        containers. 
      </para>
    </note>
    
  </sect1>
  
  <sect1 id="admin.extensions.configure">
    <title>Configuring the extensions system</title>
    
    <para>
      Go to <menuchoice>
        <guimenu>Extensions</guimenu>
        <guimenuitem>Installed extensions</guimenuitem>
      </menuchoice> to display an overview of all installed extensions.
    </para>
    
    <figure id="extensions.figures.installedextensions">
      <title>Installed extensions</title>
      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/installed_extensions.png" format="PNG" />
          </imageobject>
        </mediaobject>
      </screenshot>
    </figure> 
    
    
    <helptext 
      external_id="extensions.details.main" 
      title="Installed extensions">
      
      <para>
        The left-hand side of the screen shows you a tree with all installed 
        extensions, sorted by extension point and by file. Use the + and - 
        icons to expand and collapse parts of the tree. Click on an item
        in the tree to display detailed information about it
        on the right-hand side of the screen.
      </para>
      
      <seeother>
        <other external_id="extensions.settings">Settings</other>
        <other external_id="extensions.manualscan">Manual scan</other>
      </seeother>
    </helptext>
    
    <sect2 id="admin.extensions.configure.settings">
      <title>Settings</title>
    
      <para>
        Click on the <guibutton>Settings...</guibutton> button to
        display a popup dialog that allows you to changes some global
        settings.
      </para>
    
      <figure id="extensions.figures.settings">
        <title>Extension settings</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/extension_settings.png" format="PNG" />
            </imageobject>
          </mediaobject>
        </screenshot>
      </figure>
      
      <helptext external_id="extensions.settings"
        title="Extension settings">
        
        <variablelist>
        <varlistentry>
          <term><guilabel>Auto-installation interval</guilabel></term>
          <listitem>
            <para>
            The number of seconds between each check by the automatic
            installer. Enter 0 to disable automatic installation. 
            The automatic installation performs the same steps as
            a manual scan with the <guilabel>Force update</guilabel>
            option unchecked. The default setting is to have the
            automatic installation disabled and we don't recommend enabling
            it in a production environment.
            </para>
          </listitem>
        </varlistentry>
        </variablelist>
  
        <para>
          Click on &gbSave; to save the settings.
        </para>
        
        <seeother>
          <other external_id="extensions.manualscan">Manual scan</other>
        </seeother>
      </helptext>
    </sect2>
    
    <sect2 id="admin.extensions.disable">
      <title>Disable/enable extensions</title>
      
      <para>
        It is possible to disable specific extensions and/or entire
        extension points without uninstalling the XML or JAR file.
        When you click on an extension or extension point in the 
        tree on the left-hand side of the screen a lot of detailed
        information about it will show up on the right-hand side.
      </para>
      
      <para>
        The right-hand side will also have a <guibutton>Disable</guibutton>
        button. Click on that button to disable the extension or all extensions
        for an extension point. The button will change to <guibutton>Enable</guibutton>
        which lets you enable the extension (point) again. 
      </para>
    </sect2>
    
  </sect1>
  
</chapter>