| Published by: | Ontopia |
|---|---|
| Date: | $Date: 2007/08/24 14:29:53 $ |
| Version: | 3.4 ($Revision: 1.24 $) |
|
|
This document is describes how to configure and develop plug-ins for the Omnigator. Plug-ins are a general concept that allow extra functionality to be dropped into the Omnigator by simply adding files to a directory. Plug-ins are very loosely coupled to the Omnigator, and can thus be added very easily without modifying the Omnigator itself, by Ontopia and also by third parties.
The concept of plug-ins was introduced into the Navigator Framework because there is a need to be able to develop certain pieces of functionality separately from the rest of the application. These pieces may provide features like searching, reporting, validation, export, and so on, which are largely independent of the other functions provided by a web application. In practice, we have only used plug-ins in the Omnigator, but they can be used in any web application.
The Omnigator plug-ins allow you to develop an Omnigator extension separately and to deploy it simply by copying some files into a directory. The Omnigator will then discover it automatically and create links to it from all topic map and topic pages in the toplinks area.
In this section we develop a trivial plug-in and show how to deploy and configure it. The plug-in will be linked to from every topic map and topic page, and will display a greeting to the user.
Each plug-in must have its own directory under the plug-ins directory (by default $TOMCAT_HOME/webapps/omnigator/plugins). This directory must contain a file called plugin.xml with the configuration of the plug-in. So to get started, create a directory called hello and create a file called plugin.xml with the following information in it:
A trivial plugin.xml file
<plugin id="hello" groups="topic,topicmap">
<title>Hello</title>
<descr>Receive a greeting.</descr>
<uri>${plugins_rootdir}/hello/hello.jsp</uri>
</plugin>
This file gives the plug-in a link text (the title) and a help text (the description) which will be shown by the Omnigator. The URI is the URI of the plug-in page. This URI can be relative or absolute, and there are no constraints on where the plug-in page can be located. This means that pages external to the Omnigator can be turned into plug-in by making configuration files for them.
The string ${plugins_rootdir} in the URI will be replaced by the correct absolute path to the root directory if the plug-ins, as set in the navigator configuration. This makes it possible to ensure that links to the plug-in will be correct regardless of where the pages linking to it are located in the web application.
One of the most important parts of this file is the groups attribute. This tells the Omnigator what groups the plug-in belongs to, which affects where it is displayed. The value given here means that this plug-in should be displayed on the topic map and topic pages. (More about groups below.)
Note that you can update the list of plug-ins and change their configurations while the server is running by reloading the application configuration.
In this case we refer to a JSP page called hello.jsp in the plug-in directory. The source code to that file is given below.
The hello.jsp page
Hello, world!
Once these two files are installed the topic map page of the Omnigator automatically changes to include a link to the plug-in, as shown in the screenshot below. The 'Hello' link goes to the plug-in's hello.jsp page.
By clicking on the 'Hello' link we go to the page displayed below.
This page is of course not very interesting, nor does it look like the other pages in the Omnigator. The last problem can be solved by using the Navigator template system. The page below has the same content as the first hello.jsp but uses the template system of the Navigator.
A more advanced hello.jsp page
<%@ page contentType="text/html; charset=utf-8" %>
<%@ taglib uri='http://psi.ontopia.net/jsp/taglib/template' prefix='template' %>
<template:insert template='/views/template_%view%.jsp'>
<template:put name='title' body='true'>[Omnigator] Hello!</template:put>
<template:put name='heading' body='true'>
<h1 class="boxed">Hello!</h1>
</template:put>
<template:put name='skin' body='true'>skins/<jsp:getProperty name="ontopiaUser" property="skin"/>.css</template:put>
<template:put name='toplinks' body='true'>
<a href="../../models/index.jsp">Welcome</a>
</template:put>
<template:put name='navigation' body='true'>
<p>
Hello, world!
</p>
</template:put>
<%-- ============== Outsourced application-wide standards ============== --%>
<template:put name='application' content='/fragments/application.jsp'/>
<template:put name='header-tagline' content='/fragments/tagline-header.jsp'/>
<template:put name='footer-tagline' content='/fragments/tagline-footer.jsp'/>
</template:insert>
This page looks as shown below.
You can find this plug-in in the hello directory of the plugins directory.
Plug-ins can of course do more than this, and they can also be configured to a greater extent than what has been shown so far. This section gives a complete overview of the plug-in concept and what can be done with it.
Note that there are also options in the application.xml file which are relevant for plug-ins. See The Navigator Framework — Configuration Guide for more details. Please also note that the Omnigator has a page for administrating plug-ins, which is described in The Ontopia Omnigator — User's Guide.
In the plugin.xml file the following elements are understood by the plug-in framework:
This element can be used to give the plug-in simple name/value string pairs as part of its configuration. Ontopia has no defined meanings for any of these pairs, but plug-in writers can define their own. The name attribute contains the name of the parameter, and the value attribute contains the parameter value. These pairs are made available to plug-in code. (Not required.)
Note value attribute is not required; the value can be given as element content instead.
In addition to these elements, the following attributes can be set on the plugin element:
If this attribute is set, the plug-in framework will interpret it to be the name of a Java class that implements the net.ontopia.topicmaps.nav.plugins.PluginIF interface. This class will be instantiated and used to represent the plug-in. The interface of this class is documented in the navigator javadoc.
If this attribute is not given the DefaultPlugin class will be used.
One of the most powerful aspects of the plug-in concept is that every plug-in belongs to a set of named groups. This allows you to control what plug-ins are shown where. For example, in the Omnigator, there are the following groups of plug-ins:
Using this concept you can control where the plug-in administration plug-in is to appear, for example, by including it in the groups you want it to be part of. Note that you are free to define whatever groups you like in your own applications.
The net.ontopia.topicmaps.nav2.plugins.TextPlugin plug-in can be used to insert any HTML in the form of a plug-in. This plug-in class requires the title and description elements, and the text parameter.
The text parameter is used to give the plug-in the HTML that will be inserted into the topic and topic map pages. This makes it very easy to add plug-ins that are forms, images, or other interesting things. Note that the parameter element need not have a value attribute, but that the value can be given as element content instead.
The samples directory in the plugins directory contains some interesting examples of this.
Implementing a plug-in class is mainly useful when you want to produce other HTML from your plug-in than a simple link. You may for example want to make a little form with a search field or something similar. Another thing that plug-in classes may be useful for is to control which pages link to the plug-in. The full-text search plug-in, available as part of the full-text search engine product, uses this to only create links from topic maps it has indexed.
The core of the PluginIF interface is the generateHTML method, which is called by the web application in order to have the plug-in produce its HTML output. To this method is passed enough information that the plug-in can tell what the current topic and topic map are, and it can also get request and application information.
To see an example of a real plug-in that does real work you can look in $TOMCAT_HOME/webapps/omnigator/plugins/merge, where you'll find the merge plug-in. This consists only of JSP pages and is quite simple to understand.
The source code of the JSP pages for the merge plug-in are only available with the OKS; the freely downloadable Omnigator does not contain these source files.