Introduction to Spoon Plugins
Spoon plugins provide developers the ability to add new or modify existing functionality of the Spoon UI. A Spoon plugin can modify any area that's been written in Pentaho XUL Xul Developer's Guide (http://wiki.pentaho.com/display/ServerDoc2x/The+Pentaho+XUL+Framework+Developer's+Guide). Below is a current list of areas written in XUL that can be modified:
- Main Layout
- Agile BI
- Database Explorer Dialog
Common Use Cases
The most common use case is to add new functionality to Spoon. However, user interface elements can be hidden, rearranged or have their behaviors changed by Spoon Plugins.
Spoon Plugin Structure
Spoon Plugins are packaged as a folder under the $SPOON_HOME/plugins/spoon folder. They contain a plugin.xml file which contains a list of Spoon Plugin class names, and a lib directory where the plugin jar and all needed dependent jars are located.
Currently based on Spring, but soon to be configurable by annotations
<?xml version='1.0' encoding='UTF-8'?>
<bean id="YOUR_BEAN_ID" class="org.sample.YourSpoonPluginClass"></bean>
Multiple Spoon plugin classes can be registered within the same plugin.xml by adding more beans.
A SpoonPlugin must respond to four calls though each one is optional and all can return nothing and still be valid.
Overlays are a XUL concept with allow you to modify the UI. Each Spoon plugin can return a Map containing XulOverlay objects keyed by the area which they should be applied. Sample Below:
XulOverlay overlay = new DefaultXulOverlay("org/pentaho/agilebi/pdi/spoon/overlays.xul");
Map<String, List<XulOverlay>> overlays = new HashMap<String, List<XulOverlay>>();
Returning an overlay keyed as "spoon" causes the overlay to be applied to the main Spoon UI. Other locations can be modified by returning overlays associated with the key for those areas:
Main Spoon UI & Menus
Database Explorer Dialog
While Overlays add new UI elements to Spoon, they need code to make them useful. In XUL this is done with XulEventHandlers, which you may see referred to as "Controllers". The method for providing these is very similar to the way Overlays are supplied. Each event handler must be keyed to a certain area where it should be registered. Note that the same event handler can be registered in multiple locations at the same time, though this can be problematic as an event handler can only interact with one XUL document at a time.
Map<String, XulEventHandler> handlers = new HashMap<String, List<XulEventHandler>>();
A plugin can register a SpoonLifecycleListener to receive notification when Spoon has been initialized as well as when a shutdown has occurred.
Spoon Perspectives are specialized classes that can add a new super-set of functionality to Spoon that change the entire look of the application when enabled. Spoon Perspectives are covered in detail here.