# 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:

- 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.