[Contents] [Previous] [Next] [Last]

Chapter 1
Composer Plug-in Basics

With Communicator 4.0, Netscape introduces the Composer Plug-in API. For the first time, you can write plug-ins that blend seamlessly into the Netscape Composer interface, whether the end user is creating a web page or an email message. This API gives you a chance to extend or customize the Netscape Composer window in a simple, cross-platform way. You can write plug-ins that operate as menu options or automatically execute in response to program events.

A Composer Plug-in is a separate code module, written in Java, that can act as though it is part of Netscape Composer, the Communicator 4.0 WYSIWYG (what you see is what you get) HTML editor. Once the plug-in is installed, its features are available in the Netscape Composer and Message Composition windows, on any operating system platform that supports Java.

Netscape Communicator offers an impressive set of capabilities for accessing and displaying information from the World Wide Web or company intranets. To this set, Netscape Composer adds the ability to create rich HTML documents and messages for the web, email, and groupware.

By writing Composer Plug-ins, you can add new features that reach a wide user audience or customize your company's Composer window. In addition, the Composer Plug-in API Java interface means that your plug-ins work on all platforms. The Composer Plug-ins you write are compatible with the Composer window of Communicator 4.0, and will be compatible with all future versions of the Composer.

Note:
To get acquainted with the Composer window, choose Help Contents from the Composer Help menu and select Using Composer.

This chapter provides basic information you'll need as you develop Composer plug-ins. It describes Composer plug-ins from both the user's and programmer's points of view, tells how Composer plug-ins work in the Composer interface, introduces the Composer Plug-in API, and describes the sample plug-ins included in the Composer Plug-in Kit.

• How You Can Use Composer Plug-ins
• How Composer Plug-ins Work
• Using the Composer Plug-in API
• Using the Sample Plug-ins

Note:
Composer Plug-ins are distinct from Netscape Plug-ins, which run in the Navigator component of Communicator. For more information, see the Plug-in Guide.

Visual Javascript: For information on using Composer plug-ins with Visual Javascript, see the documentation for the Component Developers Kit (CDK).

[Top]

How You Can Use Composer Plug-ins

The Composer Plug-in API makes it possible for you to add capabilities to the Netscape Composer by writing Java classes. You can create plug-ins that are similar in spirit to add-ons such as Adobe Photoshop Plug-ins, Apple HyperCard XCMDs, and Microsoft Visual Basic VBXs.

Composer Plug-ins act on the content of an HTML document. They edit or add features to the text in the web page. You can write Composer Plug-ins that add services like these:

• search and replace
• image import/export
• word-processor file import/export
• editing parameters for applets, objects
• frame designers
• form designers
• fancy text effects
• color pickers
• font pickers
• publishing assistants
• document wizards or templates
• automatic save or update operations that are activated by window events

The Composer Plug-in API offers several advantages to the developer:

• Written in Java. You write the interface of the plug-in as a Java class. For most plug-ins, you write the whole plug-in in Java. For special needs, you can use the Java Runtime Interface (JRI) to use another language, such as C.
  
  
• UI-toolkit neutral. You can use the Composer Plug-in API to write plug-ins that use any UI toolkit, including JavaSoft AWT, Netscape IFC, or your platform's native UI APIs.
  
  
• Easy-to-use API.
• You need to subclass only one class and derive one method from that class to write a plug-in.
• You are always given legal HTML; the Composer API corrects HTML code.
• The Composer API LexicalStream class makes it easy to parse HTML.

[Top]

How Composer Plug-ins Work

The Composer Plug-in API offers two powerful ways for your plug-in to operate in the Composer interface. You can register a plug-in to act as a menu option, an event handler, or both.

• Menu option. The name of your plug-in appears as a menu item in the Tools menu. The user invokes the plug-in like any menu option.
  
  
• Event handler. Your plug-in executes in response to a window event rather than a user action. For example, a plug-in could update a Table of Contents when a page that contains one of its chapters is closed. To find out how to set up a plug-in this way, see "Registering a Plug-in as an Event Handler."

When Communicator starts up, it checks for plug-in modules in the plug-ins directory, which is usually in the same directory as the Communicator application. The location of the plug-ins directory varies by platform.

Plug-ins are installed in this directory through manual installation, an installation program, or with the Communicator JAR Installation Manager (JIM) feature. All installed plug-ins become part of the Composer module.

When the user first opens the Composer window, the Composer searches the platform-specific plug-in directory for any plug-in JAR or zip archives and uses these files. When the user selects a plug-in, the Composer passes the entire HTML document to the plug-in. The plug-in edits the document and then returns. After this, the document in the Composer window reflects the changes made by the plug-in.

In the Communicator interface, the user has access to the Composer module in two places: in the Composer window itself and in the Mail Compose window. This means that a Composer Plug-in can enhance both the web pages that the user writes and the email messages that the user sends.

To get to the Netscape Composer window, you have several options:

• From the Communicator menu on the Communicator browser window, choose Page Composer.
• Click the Pen icon at the lower right corner of any Communicator window.

• From the File menu of any Communicator window, choose New, then any Page option.

To get to a Message Composition window, you have several options:

• From the File menu of any Communicator window, choose New, then Message.
  
  
• Click the Mailbox icon at the lower right corner of any Communicator window. Then, from the Inbox window, choose Message, followed by New Message.

• Click the New Msg icon on any Communicator window where it appears.

The Tools Menu

An installed menu option plug-in appears in the Composer window Tools menu. An installed event handler plug-in is not visible to the user, but executes when an event occurs.

This is the Tools menu.

Above the line are tools that come with the Composer; below the line are category names for menu option plug-ins, in alphabetical order. When you write a plug-in, you choose your own category names. The plug-ins under each category also appear in alphabetical order.

[Top]

Using the Composer Plug-in API

• Understanding the Composer Plug-in API
• How Composer Plug-ins Handle URLs
• Composer Plug-ins and the Netscape Java Environment
• Your Java Version

[Top]

Understanding the Composer Plug-in API

The Composer Plug-in API is a set of Java classes that extends the Java class hierarchy and conforms to standard Java structure. Like all Java classes, Composer Plug-in classes are organized into packages. All Composer Plug-ins extend the netscape.plugin.composer.Plugin class, which, in turn, extends java.lang.Object. The Composer Plug-ins you write can reside in any package.

• Syntax and Usage
• How Composer Plug-ins Differ from Applications and Applets

[Top] [Using the Composer Plug-in API]

Syntax and Usage

A Composer Plug-in class conforms to standard Java syntax and behavior and follows Java conventions for handling events.

This guide describes developing Composer Plug-ins. For information about the Java language or its syntax and usage, see your Java documentation. For information about handling events, see your Java AWT or Netscape IFC documentation.

[Top] [Using the Composer Plug-in API]

How Composer Plug-ins Differ from Applications and Applets

If you have used Java to write applets or applications, you may wonder how these differ from Composer Plug-ins. The Composer Plug-in is a Java class rather than an application or a Java applet. You do not run the Composer Plug-in separately from the Composer window, as you would an application. It contains no main method, although you can add this method to allow it to run in the Testbed during development.

An applet cannot make changes to a document on the user's local system, whereas a Composer Plug-in is designed to edit and add features to a document. An applet is automatically loaded when a web page opens; in contrast, a Composer Plug-in is either selected from the Composer Tools menu by the user or triggered by an event in the Composer window.

[Top] [Using the Composer Plug-in API]

How Composer Plug-ins Handle URLs

Each Composer HTML document has its own URL (uniform resource locator), which a plug-in must know in order to perform some operations, such as adding images to the document. Plug-ins can use the Document.getBase method to get the URL of the current document. As with any HTML document, a Composer page can contain URLs that are either absolute or relative to its own URL.

For more information, see "Working with URLs in a Document."

[Top] [Using the Composer Plug-in API]

Composer Plug-ins and the Netscape Java Environment

Since Composer Plug-ins are Java classes, your plug-in can tap into the full power of the Netscape Java environment by using the Java Runtime Interface (JRI) to communicate with other languages, such as C.

The Composer Plug-in Java API enables a single Composer Plug-in to work on all platforms, including any future versions of the Netscape Composer.

[Top] [Using the Composer Plug-in API]

Your Java Version

This guide assumes that you are developing Composer Plug-ins using the Java Development Kit (JDK) 1.1 or a JDK 1.1-compatible IDE, such as Symantec Cafe 1.5.1 with the 1.1 Preview. The guide assumes that you are deploying your Composer Plug-ins in the Communicator 4.0 environment. In general, if your plug-in works correctly when run under JDK 1.1 with the Composer Plug-in Kit, it will also work with Communicator 4.0 and later.

Note:
To download Java, see the main Java site.

The Composer Plug-in class directory includes all of the JDK 1.1 internationalization and character Reader and Writer classes required to create plug-ins. You can use standard Java internationalization methods to internationalize your plug-ins. 

Be sure to include classes.zip, in the classes directory of the Composer Plug-in Kit, in your CLASSPATH.

[Top] [Using the Composer Plug-in API]

Using the Sample Plug-ins

• Composer Plug-in Samples
• Running the Samples Outside the Composer

[Top]

Composer Plug-in Samples

To get you started developing Composer Plug-ins as quickly as possible, the Composer Plug-in API includes a set of sample plug-ins that you can use in a variety of ways. Each sample demonstrates how to implement a different type of capability in a Composer Plug-in. Examples range from changing the capitalization style of selected text to incorporating dialog boxes and opening other pages. The Composer Plug-in samples provide the code examples used throughout this guide.

You can use the samples to speed your development process or to understand Composer Plug-ins from the user's point of view.

From the developer's point of view: Look under the hood--examine the sample plug-in code and see how each performs its task. Test-run the samples for yourself in the Composer Testbed. Compare the code to the way the sample operates in the Composer window. Cut your development time by cutting and pasting if you find some code that exactly meets your needs, or start with the sample that is closest to your plug-in idea and pattern your plug-in on it.

From your future user's point of view: Install the samples and try them in your Composer window to get an idea of the user's experience. You also get to use the plug-ins in your own documents.

Sample plug-ins are included in the Test package, along with Testbed classes. You will find the source code for all of the samples in the source\netscape\test\plugin\composer directory. The samples are intended to work with JDK 1.1 or an IDE that is compatible with JDK 1.1.

• AddApplet. Shows how to use the LOCALDATA property to add local data files to a Composer document.
• AddButton. Shows how to add images to the document.
• AddLayer. Turns the selected text into a layer.
• Colorize. Colorizes the selected text in an HTML document. Shows low-level HTML parsing.
• EditHomePage. Shows how to open the Netscape Home Page for editing.
• EditRaw. Views and edits the raw HTML of the document. Shows how to call AWT.
• DocInfo. Shows how to access document information. Prints out the base URL, the working directory and its URL, and the current event, if any.
• DocInfoResources. Resource bundle object used in DocInfo sample.
• IFCTest. Views and edits the raw HTML of the document. Shows how to call IFC.
• IFCTestBundle. Resource bundle object used in IFCTest sample.
• RedirectTest. Shows how to redirect the open event to a new document URL.
• SmallCaps. Implements Netscape-style small caps. Shows low-level HTML parsing.
• Tableize. Places selected text in a table.
• TagStrip. Removes all HTML tags from the selected text in the document. Shows low-level HTML parsing.
• TextImageEncoder. Sample image encoder.

Note:
It is recommended that you use AWT 1.0 features for developing Composer Plug-ins because some JDK 1.1 methods (especially features of AWT 1.1) are not supported by Communicator 4.0. Using the older AWT 1.0 features may result in JDK 1.1 deprecated interface warnings when you compile some of the samples; you can safely ignore these warnings.

[Top] [Using the Sample Plug-ins]

Running the Samples Outside the Composer

Running the samples inside the Composer is easy. Just install the sample in the plug-ins directory, and choose the plug-in from Composer Tools menu. You can also run a sample outside of the Composer. Each sample includes run code that you can use to test it from the command line in the Composer Testbed. This is described in Preparing for Running in the Testbed.

To run a plug-in from the command line, leave it in the work directory where you are writing it, and use this run script:

java -classpath yourClassPath samplePlugin

For yourClassPath, give the full class path of your Java runtime classes and the Composer Plug-in Kit. For samplePlugin, use the full name of the sample plug-in, as shown in this table.

If your Java class file is in directory C:\java\lib, your Composer Plug-in Kit is in D:\cpkit, your IFC library is in D:\ifc11, and you are using JDK 1.1, yourClassPath is:

D:\cpkit\source:  /* source to Samples */
D:\cpkit\classes\classes.zip:  /* Composer Plug-in classes */
D:\ifc11\classes:  /* IFC classes */
C:\java\lib\classes.zip  /* Java 1.1 run-time */

[Top] [Contents] [Previous] [Next] [Last]