Visual JavaScript Plug-In Interfaces Specification
Preliminary Draft - Preview Release 2
The Visual JavaScript Plug-In interfaces are not available in
VJS PR2. This information is provided so that developers can prepare to support
the Plug-in Architecture.
-
Overview
-
Page Oriented Plug-Ins
-
Component Level - Customizers
-
Property Editors
1.0 Overview
Component developers can extend the Visual JavaScript development environment
through Visual JavaScript Plug-ins. There are three basic types
of plug-ins:
-
Page-oriented plug-ins which edit a page.
-
Customizers that edit a component or
bean.
-
Property Editors for editing component
properties.
2.0 Page-Oriented Plug-Ins
Page-oriented plug-ins use the same interfaces as those provided by Netscape
Composer, as described in the Composer
Plug-in SDK.
The key points of the Composer plug-in architecture are:
-
The plug-in interface is written in Java. Developers must write the interface
part of their plug-in as a Java class. They can, however, use the full
power of the Netscape Java environment. This means that they can use JRI
to call into another language, such as C or JavaScript.
-
The composer passes the whole HTML document to the plug-in. The plug-in
edits the document, and then returns. The composer then reflects the changes
that the plug-in made.
-
Plug-ins store their UI strings in a properties file. This allows internationalization
by editing the text file.
The Composer plug-in API is UI-toolkit neutral. Plug-ins can be written
to use any UI toolkit, including AWT, Netscape IFC, or the platform native
UI. The Composer plug-in API is simple. Here are the main public classes:
Class
|
Description
|
netscape.plugin.composer.Plugin |
The base class for all composer plug-ins. |
netscape.plugin.composer.Document |
An HTML document. Includes images, plug-ins, etc.. |
netscape.plugin.composer.io.LexicalStream |
Converts a String or a Unicode stream into HTML tokens. |
netscape.plugin.composer.io.Token |
The base class for all Tokens. |
netscape.plugin.composer.io.Text |
The HTML text Token. |
netscape.plugin.composer.io.Tag |
The HTML tag Token. |
netscape.plugin.composer.io.Comment |
The HTML comment Token. |
Plug-in Interface
The plug-in must support the Plugin interface. It consists of:
-
The default constructor for a Plugin. If you have a default constructor,
it must be public so that your plugin can be instantiated by name. (Also,
your plugin class must be a public class so that it can be instantiated
by name.) default constructor
-
getName - This text will show up as the text of a menu item.
-
getCategory - This text will show up as the title of a menu that
contains the plugin. If several plugins use the same category, they will
all show up in the same menu.
-
getHint - This is a one-sentence description of what the plugin does.
-
perform - Execute the plugin. Override this method to perform the bulk
of your work. This is where your plugin gets the text out of the document,
analyzes it, interacts with the user, and modifies the text of the document.
The rest of the Visual JavaScript user interface is held in a modal state
while your plugin is executing. So either finish quickly, or display a
progress dialog, or otherwise let the user know what's going on.
Plugins allow arbitrary transformations of the current document. When the
user invokes a plugin, the plugin's perform method is called with the current
document. The plugin can then examine the existing document and modify
it. Plugins are like Applet or Application, in that they are the main class
of your mini application. This is where the flow of control transfers from
the editor to you. The document can change arbitrarily between calls to
perform. You may even be given two different documents on two successive
calls to perform.
Categories are used in the user interface to collect plugins into groups
that are meaningful to users. You can use your own category to put all
of your product's plugins into one category. Or, you can place your plugins
into several categories. It's up to you.
Packaging Plugins
To package your plugin, create a JAR file with the file name cpXXX.zip,
where XXX can be anything you want (it must be unique, so use your company
name or the plugin name.) Put all your classes into that .zip file. At
the top level of the .zip archive, add a file called "netscape_plugin_composer.ini".
Format of the "netscape_plugin_composer.ini" file.
It is in standard java "Properties" file format. The following properties
are 'well known', and are used by
the composer plugin framework:
-
netscape.plugin.composer.factory - a single classname of a Factory class.
-
netscape.plugin.composer.classes - a colon-seperated list of the classnames
of the plugins in this archive.
Your plugin's class name should be listed as the value of the netscape.plugin.composer.classes
property. You can place several plugins in the same plugin file. All the
plugin names should be listed in the netscape.plugin.composer.classes property.
Alternatively, you can use a factory class to create your plugins at
runtime.
Installing the Plugin
TBD
3.0 Component Oriented Plug-Ins
Individual component objects (beans) may be edited with a Java Beans "Customizer".
This is aimed at components that are more for which Visual JavaScript's
inspector interface is not adequate. The definition of a customizer follows
that of Java Beans with a few small modifications.
All customizers must implement the java.beans.Customizer interface,
which consists of three methods:
-
setObject call to give the object to the customizer
-
addPropertyChangeListener
-
removePropertyChangeListener
These last two methods are used to add and remove PropertyChange listeners.
The customizer must send propertyChange events when a property of the object
is modified. Otherwise the customizer has full control of the embedded
java bean. The customizer class for a bean is specified in the BeanInfo
class.
Difference from Java Beans Spec
The specification states that customizers "should" inherit from the java.awt.Component
class. Visual JavaScript uses the Netscape IFC, so Visual JavaScript
customizers will extend an IFC class instead. The specification states
that customizers "should" run in an AWT Dialog window, but it does not
state whether the customizer creates that Dialog window, or whether the
controlling application does. Visual JavaScript will try to support these
as specified.
Additionally, a customizer will be allowed to be an IFC InternalWindow.
Visual JavaScript will test first for this case, and run the customizer
this way, before it tests for java.awt.Component.
4.0 Property Editors.
A value-oriented editor is known as a PropertyEditor, and conforms to the
Java Beans standard way to extend the capability of the inspector (property
sheet) to handle new data types. All property editors must implement
the java.beans.PropertyEditor interface. This includes the following
methods:
-
addPropertyChangeListener - so that the inspector and the rest of Visual
JavaScript can be notified of a property value change.
-
removePropertyChangeListener
-
getAsText - this is how the inspector will retrieve the edited value.
Visual JavaScript attribute values are Unicode and can use any character
at this level. The conversion to an HTML representation is done automatically
at a lower level.
-
setAtText - inspector will give the text value to the property editor with
this method.
-
getValue - probably not used
-
setValue - probably not used
-
supportsCustomEditor - whether the call below will work.
-
getCustomEditor - this is the editor that is invoked when the button to
the right of the value is pressed at editing time. This call returns
an awt.Component. Visual JavaScript might support this.
-
getIFCEditor - returns an IFC View class that supports a pop-up dialog
for custom editing of the property value.
-
isPaintable - tells whether it has code to draw itself. If so, the
paintValue method will be called as necessary.
-
paintValue - the method that is called so the value can be painted to the
graphics context.
-
getJavaInitializationString - this string value may not be used
-
getTags - probably not used.
Difference from Beans Spec
The getIFCEditor command is an extension to the JavaSoft spec designed
to allow people to provide IFC oriented pop-up customizers.