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

Chapter 9
Event Handler Plug-ins

You can increase the versatility of your user interface with plug-ins that respond to program events. If you register your Composer Plug-in as an event handler, it is automatically called when an event occurs. This gives you the freedom to extend Composer in interesting ways. For example, your plug-in could update a table of contents when you save a file.

This chapter describes event handler plug-ins and the events that can trigger plug-in execution.

A Composer Plug-in class can be registered as either a menu option plug-in, as an event handler, or as both. If registered as both, one instance is called when the user chooses the plug-in from the menu. The other is called when its event occurs. The two instances can communicate using static variables or using ad hoc information encoded in the document.

You can attach a plug-in to a variety of program events, including edit, open, close, publish, publishComplete, save, and send. For a description of each, see "Composer Plug-in Events."

To link plug-in execution to an event, set the netscape.plugin.composer.eventHandler property in the netscape_plugin_composer.ini configuration file. For directions, see "Registering a Plug-in as an Image Encoder." For more information about this file, see "Registering a Plug-in as a Menu Option or Event Handler."

• How Composer Plug-ins Handle Events
• Composer Plug-in Events
• Order for Calling Event Handlers
• Canceling an Operation
• Finding the Trigger Event
• Redirecting the Edit Event

[Top]

How Composer Plug-ins Handle Events

Once your Composer plug-in is registered as an event handler, its perform method is called whenever an event occurs. The plug-in's perform method should call the document's getEventName method to identify the event. For example, when any event occurs, the perform method of the DocInfo plug-in sample calls dialog.getStats, which in turn calls document.getEventName.

  public boolean perform(Document document) throws IOException{
          DocInfoDialog dialog = new DocInfoDialog(getResource("title"));
          dialog.setText(getStats(document));
          ...
      }

      String getStats(Document document) throws IOException{
          ...
          String eventName = document.getEventName();
          ...
      }

Usually, a plug-in is interested only in certain events, so it must check for those specific events. It should immediately return true, which means "don't cancel the operation," for any event that it does not understand. For more information, see "Finding the Trigger Event."

Note:
To enable DocInfo to operate as an event handler, follow these steps:

1. In Communicator Plugins directory, find and unzip the JAR file.
2. In the directory for the samples, open the netscape_plugin_composer.ini file.
3. Find DocInfo's eventHandler interface property definition and remove the comment code from it, then save and close the file.
4. Rezip the JAR file, specifying No Compression.
5. Check that the JAR file is in the Plugins directory, and restart Communicator.

[Top]

Composer Plug-in Events

The table in this section describes each event and tells which programmatic action triggers it. The "Special Rules" column alerts you to special behavior you'll have to consider when designing your plug-in. For example, if your plug-in handles the close event, which is triggered when the user closes a document, it could automatically update a file, such as an index or table of contents, whenever the document is saved.

[Top]

Order for Calling Event Handlers

When an event occurs, registered event handlers are called in alphabetical order, first by category, then by name within category. For example, the hypothetical plug-ins in the following table execute in top-to-bottom order, because the list is sorted alphabetically by category and then by name. If two plug-ins have exactly the same name and category, the one that executes first is undefined.

Try to write your event handler so that it does not matter when it is executed relative to other event handlers. If it must be executed relatively early or late during a given event, give it a name that sorts correspondingly early or late. You cannot guarantee the execution order of a set of separately written plug-ins. Composer Plug-ins work like Apple Macintosh Extensions in this respect.

If the plug-in must be called early for one event but late for another, you must write two event handlers, with two different category names, each of which handles one of the events.

The user never sees the name and category you use for an event handler. The Composer uses these values only to establish the relative execution order with respect to other event handlers.

[Top]

Canceling an Operation

You can stop some plug-in operations from completing. This can be useful some external event prevents the operation from succeeding. The event table in this chapter shows that you can cancel edit, send, save, and publish events.

For example, a plug-in that handles the edit event starts by checking whether the file that is to be edited is locked. This plug-in could follow this sequence:

• If the file is locked, the plug-in displays a dialog box that asks the user whether to unlock the file.
• If the user says yes, the plug-in unlocks the file, and returns true. This allows the edit operation to continue.
• If the user says no, the plug-in returns false, which cancels the edit operation.

[Top]

Finding the Trigger Event

An event handler plug-in that responds to a particular event must check to find out whether this event has occurred. To allow the plug-in to do this, use the document.getEventName method.

  public String getEventName()

The method returns the event that triggered the plug-in invocation, or null if the plug-in was invoked from a Tools menu item. For a list of possible events, see the event table or getEventName.

The RedirectTest sample must identify the edit event, since it redirects this event to a new URL. When the user clicks Edit on a web page, the plug-in substitutes the address specified in this method for that of the current document. Its perform method must first find out whether the event is edit, which opens an existing document for editing. If the event is not edit, it cannot redirect the event.

 public boolean perform(Document document){

     /* Find the event. */
     /* Plug-in only proceeds if this is an edit event. */
     String event = document.getEventName();

For the full text of this sample plug-in, see RedirectTest.java, in the source directory of the Composer Plug-in Kit.

[Top]

Redirecting the Edit Event

You can change a request to edit pages from one document URL to another by redirecting its edit event. This is useful when the publishing URL is different from the editing URL, for example, when you use an FTP server to access the backing store of an HTTP server. The redirectDocumentOpen method redirects a document edit event to the specified document URL. This means that it opens the specified URL for editing, rather than the browsing or publishing URL.

  public void redirectDocumentOpen(String newURL)

As a parameter, this method takes the URL of the document to edit and returns an output stream for the document. This method only redirects edit events.

The RedirectTest sample shows a possible use of the redirectDocumentOpen method. It changes a request to edit pages from a web site into a request to edit pages from an FTP site. In order to use the sample, you must change the URLs to ones that are meaningful on your system.

For the full text of this sample plug-in, see RedirectTest.java, in the source directory of the Composer Plug-in Kit.

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