[Contents] [Previous] [Next] [Index]

Chapter 2
Development Overview

This chapter is an introduction to the issues and processes that you will need to know about as you write plug-ins. It outlines the steps in writing and implementing a plug-in code module for Communicator.

For more information about particular processes described in this chapter, refer to Chapters 3 through 8.

[Top]


Writing Plug-ins

Once you decide what you want your plug-in to do, creating it is a simple process.

Plan your plug-in. Decide on the services you want the plug-in to provide.

  1. Decide on a MIME type and file extension for the plug-in. See "Registering Plug-ins."

  2. Download and decompress the SDK. See "The Plug-in Software Development Kit."

  3. Create the plug-in project. You can either start from the template provided for your operating system in the source directory, or construct a plug-in project in your development environment using SDK-provided files. You can use a variety of environments to create plug-ins.

  4. Make the necessary changes and additions to the SDK files to provide plug-in functionality and implement Plug-in API methods for basic plug-in operation. You'll find an overview of using Plug-in API methods in this chapter. More information about each function is provided in Chapters 3 though 8 of this guide.

  5. Build the plug-in for your operating system. See "Building Plug-ins."

  6. Install the plug-in in the plug-in directory for your operating system. See "Installing Plug-ins."

  7. Test your plug-in and debug as necessary.

  8. Create an HTML page and embed the plug-in object. For information about the HTML tags to use, see "Using HTML to Display Plug-ins." To see your plug-in in action, simply display the HTML page that calls it in Communicator.

  9. If you decide to use LiveConnect capabilities in your plug-in, your next step is to read LiveConnecting Plug-ins with Java. Look at the View Source article, "Netscape Client Plug-Ins," to see how the Plug-in API and LiveConnect fit together in a plug-in created with Microsoft Visual C++.
You can avoid many development problems by working in stages and testing at each stage. In the first stage, you create a plug-in project, edit the plug-in files as necessary, build the plug-in, and install it. In the second stage, you add the special functionality that makes the plug-in unique. The issues you will encounter are introduced in this chapter, and examined in more detail in Chapters 3 through 8.

[Top] [Writing Plug-ins]


Registering Plug-ins

Netscape Communicator identifies a plug-in by the MIME type it supports. When it needs to display data of a particular MIME type, Communicator finds and invokes the plug-in that supports that type. The data can come from either an EMBED tag in an HTML file (where the EMBED tag either specifies the MIME type directly or references a file of that type), from a separate non-HTML file of that MIME type, or from the server.

The server looks for the MIME type registered by a plug-in, based on the file extension, and starts sending the file to the browser. Communicator looks up the media type, and if it finds a plug-in registered to that type, loads the plug-in.

When it starts up, Communicator checks for plug-in modules in the plug-in directory for the platform and registers them. It determines which plug-ins are installed and which types they support through a combination of user preferences that are private to Communicator and the contents of the plug-ins directory. You can see this information by choosing About Plug-ins from the Help menu (Window and Unix) or "?" (Help) menu (Mac OS).

A MIME type is made up of a major type (such as application or image) and a minor type, for example, image/jpeg. If you define a new MIME type for a plug-in, you must register it with IETF (Internet Engineering Task Force). Until your new MIME type is registered, preface its name with "x-", for example, image/x-nwim. For more information about MIME types, see these MIME RFCs: RFC 1521: "MIME: Mechanisms for Specifying and Describing the Forms of Internet Message Bodies" and RFC 1590: "Media Type Registration Procedure."

[Top] [Registering Plug-ins]


Mac OS

On the Mac OS platform, the Plug-ins folder is located in the same folder as the Communicator application. Plug-ins are identified by file type NSPL. When Communicator starts up, it searches subfolders of the Plug-ins folder for plug-ins and follows aliases to folders and NSPL files. Plug-in filenames must begin with NP.

The MIME types supported by a plug-in are determined by its resources. 'STR#' 128 should contain a list of MIME types and file extensions in alternating strings. For example:

str 128
MIME Type
String 1
video/quicktime
String 2
mov, moov
String 3
audio/aiff
String 4
aiff
String 5
image/jpeg
String 6
jpg

Several other optional strings may contain useful information about the plug-in. Plug-ins must support 'STR#' 128 but are not required to support any of these others:

[Top] [Registering Plug-ins]


MS Windows

On Windows, the plugins directory is located in the same directory as the Communicator application. You can also find this directory through the Registry. Communicator does not search subdirectories. Plug-ins must have a 8.3 filename beginning with NP and ending with .DLL.

The Windows version information for the plug-in DLL determines the MIME types, file extensions, file open template, plug-in name, and description. In the MIME types and file extensions strings, multiple types and extensions are separated by the "|" character, for example:

video/quicktime|audio/aiff|image/jpeg
For Communicator to recognize the plug-in, the version stamp of the plug-in DLL must contain the following lines:

In your development environment, set the language to "US English" and the character set to "Windows Multilingual." The resource code for this language and character set combination is 040904E4.

[Top] [Registering Plug-ins]


Unix

On Unix, the plugins directory is set by the environment variable NPX_PLUGIN_PATH, which defaults to /usr/local/netscape/plugins, ~/.netscape/plugins. Plug-in filenames must begin with NP.

To determine the MIME types of the plug-ins, Communicator loads each plug-in library and calls its required NPP_GetMIMEDescription entry point. NPP_GetMIMEDescription should return a string containing the type, extension list, and type description separated by semicolons; for example, image/xbm;xbm;X Bitmap.

Communicator also calls the plug-in's optional NPP_GetValue entry point to determine the plug-in name and description.

The calls to NPP_GetMIMEDescription and NPP_GetValue are made for registration purposes only. During registration, Communicator does not call any other plug-in entry points, and the plug-in cannot call any Communicator entry points at all.

[Top] [Registering Plug-ins]


Drawing Plug-ins

Before drawing itself on the page, the plug-in must provide information about itself, set the window or other target in which it draws, arrange for redrawing, and handle events.

A windowless plug-in can call the following Netscape methods to draw itself:

Communicator calls these Plug-in methods:

The plug-in can call these Netscape methods to query and set information:

For information about these processes, see Chapter 4, "Drawing and Event Handling." For a reference entry that describes each function, see "Drawing Methods" in the API reference.

[Top] [Drawing Plug-ins]


Handling Memory

Plug-in developers can take advantage of the memory features provided in the Plug-in API to allocate and free memory.

For information about using these methods, see Chapter 7, "Memory." For a reference entry that describes each function, see "Memory Methods" in the API reference.

[Top] [Handling Memory]


Sending and Receiving Streams

Streams are objects that represent URLs and the data they contain. A stream is associated with a specific instance of a plug-in, but a plug-in can have more than one stream per instance. Streams can be produced by Communicator and consumed by a plug-in instance, or produced by an instance and consumed by Communicator. Each stream has an associated MIME type identifying the format of the data in the stream.

Streams produced by Communicator can be automatically sent to the plug-in instance or requested by the plug-in. The plug-in can select one of these transmission modes:

Streams produced by the plug-in to send to Communicator are like normal-mode streams produced by Communicator, but in reverse. In Communicator's normal-mode streams, Communicator calls the plug-in to inform it that the stream was created and to push more data. In contrast, in streams produced by the plug-in, the plug-in calls Netscape functions to create a stream, push data into it, and delete it.

For information about using these methods, see Chapter 5, "Streams." For a reference entry that describes each function, see "Stream Methods" in the API reference.

[Top] [Sending and Receiving Streams]


Working with URLs

The Plug-in API provides methods that plug-ins can use to retrieve data from or post data to a URL anywhere on the network, provide hyperlinks to other documents, post form data to CGI scripts using HTTP, or upload files to a remote server using FTP.

For information about using these methods, see Chapter 6, "URLs." For a reference entry that describes each function, see "URL Methods" in the API reference.

[Top] [Working with URLs]


Getting Version and UI Information

The Netscape group of Plug-in API methods provides some basic services to the plug-in. You can use these Netscape methods:

For information about using these methods, see Chapter 8, "Version, UI, and Status Information." For a reference entry that describes each function, see "Utility Methods" in the API reference.

[Top] [Getting Version and UI Information]


Displaying Messages on the Status Line

Functionally, your plug-in is seamlessly integrated into Communicator and operates like an additional Communicator capability. To make the user feel that the plug-in is part of the Communicator user interface, your plug-in can emulate Communicator behavior by providing status line messages. Use the NPN_Status method to display a message on the status line.

For information about using this method, see Chapter 8, "Version, UI, and Status Information." For a reference entry, see "Utility Methods" in the API reference.

[Top] [Displaying Messages on the Status Line]


Communicating with Java

By using Netscape's LiveConnect, you can write plug-ins that (1) call on Java and JavaScript to enhance their delivery of sound, graphics and video, (2) use Java or JavaScript controls, or (3) provide part of their functionality. Plug-ins can communicate directly with Java and with JavaScript through Java by using a Netscape LiveConnect connection.

To take advantage of Java and JavaScript, a plug-in must interact with the Java object model. The plug-in must have an associated Java class and implement methods of that class in native code. For example, the sample plug-in Simple, which is included in the Plug-in SDK, has an associated Java class that is defined in the simple.java file (in Simple's source directory).

Methods of the plug-in's associated Java class can be called from other Java code or JavaScript. For example, a form letter on an HTML page could control plug-in operation by using JavaScript to call a native method of the plug-in's class.

To prepare your plug-in for LiveConnect communication with Java, you need three Plug-in API methods:

Communicating with Java and JavaScript and using LiveConnect are topics beyond the scope of this guide. To find out about setting up a Java class for a plug-in and the issues you need to consider, see LiveConnecting Plug-ins with Java. See "Methods for Communicating with Java" for a reference entry that describes each of these methods.

NOTE: LiveConnect is enabled by default in Netscape 3.0 and later versions. You can manually enable (or disable) LiveConnect by setting the preferences for enabling Java and JavaScript. To enable or disable LiveConnect, see the "Java" or "JavaScript" topic in Communicator NetHelp. §
[Top] [Communicating with Java]


Building Plug-ins

After you write a plug-in, the next step is to build it. This section takes you step by step through building a plug-in on the Windows or Mac OS platform. Each uses the Simple Plug-in included in the Plug-in SDK as an example. On Unix, the SDK provides makefiles.

[Top] [Building Plug-ins]


Building a Win32 Plug-in

Follow these steps to build the Simple Plug-in that is included in the Netscape Plug-in SDK for Win32 (Windows 95 and Windows NT), using Microsoft Visual C++ 4.2.

Download the MS Windows Plug-in SDK (WinNPSDK.zip) from the Netscape FTP download page.

  1. Unzip WinNPSDK.zip using your favorite zip utility. If you would like to use the MSVC++ project files without modification, unzip this file directly into your C:\ directory. If you are using pkunzip, use the -d flag to maintain the directory structure of the zip file.
    After unzipping the file, you will have a directory called C:\PluginSDK.

  2. Open the file C:\PluginSDK\Examples\Simple\Windows\NPSimple32.mdp.

  3. From the Build menu, choose Build NPSimple32.dll.

  4. Copy the resulting file NPSimple32.dll to the plugins directory in the same directory as netscape.exe. Usually this is C:\Program Files\Netscape\Navigator\Program\plugins.

  5. Copy the Java class file C:\PluginSDK\Examples\Simple\Simple.class to the same plugins directory. This file specifies the JavaScript interface to the plug-in.

  6. If Communicator is running, be sure to exit.

  7. Launch Communicator, and browse the file C:\PluginsSDK\Examples\Simple\Testing\
    SimpleExample.html
    .
[Top] [Building Plug-ins]


Building a Mac OS Plug-in

To build a Mac OS plug-in, you need a C++ compiler, the application Stuffit Expander (automatically installed on your system when you install Communicator), and a resource editor, such as ResEdit or Resourcer. These steps assume that you are using CodeWarrior 9, 10, or 11 on a PowerPC.

NOTE: The Plug-in SDK comes in CodeWarrior 9/10 and CodeWarrior 11 versions. Be sure to download the SDK for the version you are using. §
Follow these steps to build a Mac OS plug-in:

Download the Mac OS Plug-in SDK (MacNPSDK.sit) from the Netscape FTP download page.

  1. Unstuff the file with Stuffit Expander, or another unstuffing utility.

  2. In the Examples/Simple/Macintosh folder, open the SimplePPC.&micro project file.

  3. From the Project menu, choose Make.

  4. Copy the Java class file Examples/Simple/Simple.class
    to the Communicator Plug-ins folder.

  5. Copy the plug-in (or an alias) Examples/Simple/SimplePPC to the Communicator Plug-ins folder.

  6. If Communicator is running, type javascript:navigator.plugins.refresh(true);
    at the Netsite box and press Return. This reloads all plug-ins in the Plug-ins folder without your needing to restart Communicator.

  7. Browse to Examples/Simple/Testing/SimpleExample.html.
NOTE: The Simple example does not work with the 68K Mac OS. §
[Top] [Building Plug-ins]


Installing Plug-ins

If you make your plug-in easy to install, you increase the chances that it will be used. You can arrange to for users to install your plug-ins in several ways:

Communicator's JAR Installation Manager. Set up your plug-in so that this feature is triggered when the user displays an HTML page whose embedded data requires a plug-in that is not installed.

Manual installation. The user copies the plug-in to the appropriate directory by hand. Plug-ins can reside in the following directories:

Automatic installation. You provide an installation script with the plug-in.

[Top] [Installing Plug-ins]


Starting to Use the Plug-in

In Communicator 4.0, you do not need to quit and restart to make the newly installed plug-in available. With Navigator 3.x, you can start using a newly installed plug-in without restarting Navigator. To do this, call the JavaScript method navigator.plugins.refresh. This method causes Navigator to "notice" any new plug-ins in the plug-ins directory.

For more information about using JavaScript, see the JavaScript Reference.

[Top] [Installing Plug-ins]


JAR Installation Manager

The fastest way to install your plug-in on your potential user's hard drive, and the most convenient way for the user, is to take advantage of the Communicator 4.0 JAR Installation Manager (JIM). JAR Installation Manager automatically starts when the user opens an HTML page whose embedded data, in an EMBED or OBJECT tag, requires a plug-in that is not currently installed.

This section is a brief overview of how the JAR Installation Manager works and how you can prepare your plug-ins to use it. For a thorough discussion of the issues and detailed steps to follow, see Using JAR Installation Manager for SmartUpdate.

[Top] [Installing Plug-ins]


installation from the User's Point of View

This is what the user sees when JAR Installation Manager starts up:

NOTE: In Communicator 4.0, you do not need to quit and restart to make the newly installed plug-in available. §
[Top] [Installing Plug-ins]


Preparing Your Plug-in to Use JAR Installation Manager

To give your users the easy access to your plug-ins that JAR Installation Manager provides, you add only a few steps to your development process.

NOTE: If you use an existing installer, you must write a JavaScript script that starts the installer. §
For detailed steps to follow, including a sample installation script and an example that demonstrates installing a plug-in from JavaScript, see Using JAR Installation Manager for SmartUpdate.

[Top] [Installing Plug-ins]


[Contents] [Previous] [Next] [Index]

Last Updated: 01/15/97 16:36:44


Copyright 1997 Netscape Communications Corporation