Visual JavaScript Plug-In Interfaces Specification

Preliminary Draft - Preview Release 3

The Visual JavaScript Plug-In interfaces are not available in VJS PR3. This information is provided so that developers can prepare to support the Plug-in Architecture.

  1. Overview
  2. Page Oriented Plug-Ins
  3. Component Level - Customizers
  4. 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:
  1. Page-oriented plug-ins which edit a page.
  2. Customizers that edit a component or bean.
  3. 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:

  1. 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.
  2. 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.
  3. 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: 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: 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:

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:

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.