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

Chapter 1
Plug-in Basics

A plug-in is a separate code module that behaves as though it is part of the Netscape Communicator browser. You can use the Plug-in API to create plug-ins that extend Communicator with a wide range of interactive and multimedia capabilities, and that handle one or more data (MIME) types. You can even use the Plug-in API to create plug-ins that work in browsers other than the Navigator component of Communicator.

 If you are working in a Navigator 3.0 context, you can still use the Plug-in SDK, version 4.0, because it includes all 3.0 functionality. Simply do not implement any 4.0 additions in your plug-in. All 4.0 additions are clearly marked in this guide.

 The Plug-in API was designed with these goals in mind:

Plug-ins can use the Netscape Java Runtime Interface (JRI) to access Java. Communication with Java, and through Java, with JavaScript, takes place through a LiveConnect connection. For details, see LiveConnecting Plug-ins with Java.

Plug-ins are part of Netscape ONE, the Open Network Environment, an application environment based on open Internet standards. Plug-ins allow you to bring existing code bases or operating system-specific code into the Netscape ONE environment, build on legacy code, and adapt existing applications for the web. For an introduction to Netscape ONE, see the Netscape ONE Overview on DevEdge.

 This chapter provides basic information you'll need as you develop C/C++ plug-ins.

[Top]

How You Can Use Plug-ins

Plug-ins offer a rich variety of features that can increase the flexibility of Netscape Communicator. Plug-ins like these are now available: The range of possibilities for using plug-in technology seems boundless, as shown by the growing the growing numbers of independent software vendors who are creating new and innovative plug-ins. To see what many other developers are doing, take a look at the Development page of the Netscape ONE directory. On this page, select Applications and Tools, and then search for Client Plug-ins.

With the Plug-in API, you can create dynamically loaded plug-ins that can:

You can see which plug-ins are already installed on your system by consulting the Installed Plug-ins page. Go to the Help menu, and click Help and then About Plug-ins. The Installed Plug-ins page lists each installed plug-in along with its MIME type or types, description, extensions, and the current state (enabled or disabled) of the plug-in for each MIME type assigned to it.

 [Top]

When to Use Plug-ins

Plug-ins offer solutions to development needs like these: Because plug-ins are platform-specific, you must port them to every operating system and processor platform upon which you want to deploy your plug-in. Plug-ins are supported in both Netscape clients and servers.

[Top]

Plug-ins and LiveConnect

Starting with Navigator 3.0, Netscape's LiveConnect offered a way for developers to take advantage of Java and JavaScript for ways to interact with the web page, for example, through plug-in controls or user interfaces. One of the sample plug-ins of the Plug-in SDK (NPAvi, which displays AVI movies) can be controlled with JavaScript using LiveConnect.

Although plug-ins and Java can talk to each other, and Java and JavaScript can talk to each other, plug-ins and JavaScript do not communicate directly. LiveConnect provides the interface for communication between plug-ins, Java, and JavaScript.
 

To write plug-ins that use LiveConnect, start by writing the C code for your plug-in. Implement the Plug-in API methods that allow the plug-in to interact with the Java object model. For more information, see "Communicating with Java." Then, go on to Netscape's official LiveConnect guide, LiveConnecting Plug-ins with Java.

To get a good picture of the way that the Plug-in API and LiveConnect fit together in a plug-in, read the View Source article, "Netscape Client Plug-Ins." This article describes a plug-in created with Microsoft Visual C++.

For information about the capabilities of JavaScript, see the JavaScript Reference.

[Top]

Plug-ins and Helper Applications

Before Netscape first presented plug-ins in Navigator 2.0, in the first quarter of 1996, users could extend the Navigator with helper applications. A helper application is a separate, free-standing application that can be started from the Navigator browser.

Like a plug-in, the browser starts a helper application when the browser encounters a MIME type that is mapped to it. Unlike a plug-in, a helper application runs separately from the browser in its own application space and does not interact with the browser or the web.

When Navigator encounters a MIME type, it always searches for a registered plug-in first. If there are no matches for the MIME type, it looks for a helper application.

Plug-ins and helper applications fill different application needs. For more information about helper applications, refer to NetHelp, Communicator's online help.

 [Top]

How Plug-ins Work

The life cycle of a plug-in, unlike that of an application, is completely controlled by the web page that calls it. This page gives you an overview of the way that plug-ins operate in Communicator.

 When Communicator starts, it checks for plug-in modules in the plugins directory (Windows) or Plug-ins folder (Mac OS) in the same folder or directory as the Communicator application. On Unix, Communicator checks the path set in the environment variable NPX_PLUGIN_PATH. For more information, see "How Communicator Finds Plug-ins."

 When the user opens a page that contains embedded data of a media type that invokes a plug-in, Communicator responds with the following sequence of actions:

Communicator can load multiple instances of the same plug-in on a single page, or in several open windows at the same time.

When the user leaves the page or closes the window, the plug-in instance is deleted. When the last instance of a plug-in is deleted, the plug-in code is unloaded from memory. A plug-in consumes no resources other than disk space when it is not loaded. The next section, "Understanding the Runtime Model," describes these stages in more detail.

 [Top]

Understanding the Runtime Model

Plug-ins are dynamic code modules that are associated with one or more MIME types. When Netscape Communicator starts, it enumerates the available plug-ins (this step varies according to platform), reads resources from each plug-in file to determine the MIME types for that plug-in, and registers each plug-in library for its MIME types.

The following stages outline the life of a plug-in from loading to deletion:

For information about using these methods, see Chapter 3, "Initialization and Destruction." For a reference entry that describes each function, see "Initialization and Destruction Methods" in the API reference.
 
NOTE: Plug-in API calls and callbacks use the main Navigator thread. In general, if you want a plug-in to generate additional threads to handle processing at any stage in its lifespan, you should be careful to isolate these from Plug-in API calls. §
[Top] [Understanding the Runtime Model]

How Communicator Finds Plug-ins

When Communicator starts up, it checks for plug-in modules in the plug-ins directory for the platform: On all platforms, the plug-ins subdirectory or folder must be in the same directory as the Communicator application. Users can install plug-ins in this directory manually, by using either an installation program or Communicator's JAR Manager facility. For more information, see "Installing Plug-ins."

 To find out which plug-ins are currently installed, choose About Plug-ins from the Help menu (MS Windows and Unix) or "?" (Help) menu (Mac OS). Communicator displays a page listing all installed plug-ins and the MIME types they handle, as well as optional descriptive information supplied by the plug-in.

 On Windows, installed plug-ins are automatically configured to handle the MIME types that they support. If multiple plug-ins handle the same MIME type, the last plug-in loaded handles the MIME type. For information about the way MIME type is assigned, see "Registering Plug-ins."

 On Mac OS and Unix, starting with Navigator 3.0, users can configure which plug-ins or helper applications handle which MIME types by using the Helpers tab of the General Preferences window. The Helpers tab displays a list of all handled MIME types and specifies whether the type is simply saved to disk or is handled by Communicator, a plug-in, or a helper application. The user can select any MIME type in the list and click the Edit button to change the way the MIME type is handled. For instance, the user can select, from a pop-up menu of all plug-ins that support that type, a different plug-in to handle it.

[Top] [How Communicator Finds Plug-ins]

 

Overview of Plug-in Structure

This section is an overview of basic information you will need as you develop plug-ins. [Top]

Understanding the Plug-in API

The Plug-in Application Programming Interface (API) is made up of two groups of functions and a set of shared data structures. For a listing of methods by API group, see "API Organization: Netscape and Plug-in Methods."

In general, the operation of all API functions is the same on all platforms. Where this varies, the reference entry for the function in the reference section describes the difference.

 [Top] [Overview of Plug-in Structure]

Syntax and Usage

A plug-in is a native code library whose source conforms to standard C syntax. All plug-in names must start with NP.

The plug-in file type depends on the platform:

This guide describes developing plug-ins. For information about the C or C++ languages or their syntax and usage, see your language documentation.

 [Top] [Overview of Plug-in Structure]

Plug-ins and Platform Independence

A plug-in is a dynamic code module that is native to the specific platform on which the Netscape Communicator runs. It is a code library, rather than an application or an applet, and runs only from Communicator. Although plug-ins are platform-specific, the Plug-in API is designed to provide the maximum degree of flexibility and to be functionally consistent across all platforms. This guide notes platform-specific differences in coding for the MS Windows, Mac OS, and Unix platforms.

 You can use the Plug-in API to write plug-ins that are media type driven and provide high performance by taking advantage of native code. Plug-ins give you an opportunity to seamlessly integrate platform-dependent code and enhance Communicator's core functionality by providing support for new data types.

 Plug-ins can take their place beside platform-native interapplication architectures such as OLE and OpenDoc, and platform-independent programming languages such as Java and JavaScript.

[Top] [Overview of Plug-in Structure]

 

Windowed and Windowless Plug-ins

You can write plug-ins that are drawn in their own native windows or frames on a web page. Alternatively, you can write plug-ins that do not require a window to draw into. Using windowless plug-ins extends the possibilities for web page design and functionality. Whether a plug-in is windowed or windowless depends on how you define it. For more information, see "Drawing and Event Handling."

The way plug-ins are displayed on the web page is determined by the HTML tag that invokes them. This is up to the content developer or web page author. Depending on the tag and its attributes, a plug-in can be visible or hidden, or can appear as part of a page or as a full page in its own window. A web page can display a windowed or windowless plug-in in any HTML display mode; however, the plug-in must be visible for its window type to be meaningful. For information about the way HTML determines plug-in display mode, see "Using HTML to Display Plug-ins."

NOTE: The windowed plug-in was the only plug-in type in Navigator 2.0 and Navigator 3.0. Windowless plug-ins are currently not supported on the X Windows platform. §
[Top] [Windowed and Windowless Plug-ins]

Using HTML to Display Plug-ins

When a user browses to a web page that invokes a plug-in, how the plug-in appears (or does not appear) depends on two factors: This page discusses using HTML tags and display modes. For information about windowed and windowless operation, see "Windowed and Windowless Plug-ins."

 For a description of each plug-in display mode, and which HTML tag to use to achieve it, go on to "Plug-in Display Modes." For details about the HTML tags and their attributes, go on to "HTML Tags for Plug-in Display."

[Top]

Plug-in Display Modes

Whether you are writing an HTML page to display a plug-in or developing a plug-in for an HTML author to include in a page, you need to understand how display mode affects the way plug-ins appear.

A plug-in, whether it is windowed or windowless, can have one of these display modes:

An embedded plug-in is part of a larger HTML document and is loaded at the time the document is displayed. The plug-in is visible as a rectangular subpart of the page (unless it is hidden). Embedded plug-ins are commonly used for multimedia images relating to text in the page, such as the Macromedia Shockwave plug-in. When Communicator encounters the EMBED Tag in a document, it attempts to find and display the file represented by the SRC attribute. The HEIGHT and WIDTH attributes of the EMBED tag determine the size of the embedded plug-in in the HTML page. For example, this EMBED tag calls a plug-in that displays video:
  
<EMBED SRC="newave.avi" WIDTH=320 HEIGHT=200
            AUTOSTART=true LOOP=true>
A hidden plug-in is a type of embedded plug-in. It is created by using the HIDDEN attribute of the EMBED tag. A hidden plug-in is not drawn on the screen when it is invoked. HIDDEN overrides the HEIGHT and WIDTH parameters if they are included. Here's an example:
  
<EMBED SRC="audiplay.aiff" TYPE="audio/x-aiff" HIDDEN>
NOTE: Whether a plug-in is windowed or windowless is not meaningful if it is invoked with the HIDDEN attribute. §
A full-page plug-in is a visible plug-in that is not part of an HTML page. The server looks for the media (MIME) type registered by a plug-in, based on the file extension, and starts sending the file to the browser. Communicator looks up the MIME type and loads the plug-in if it finds a plug-in registered to that type. This type of plug-in completely fills the Communicator page. Full-page plug-ins are commonly used for document viewers, such as Adobe Acrobat.
NOTE: Communicator does not display scroll bars automatically for a full-page plug-in. The plug-in must draw its own scroll bars if it requires them. §
The Communicator user interface remains relatively constant regardless of which type of plug-in is displayed. The part of the application window that does not display plug-in data does not change. The basic operations of Communicator, such as navigation, history, and opening files, apply to all pages, regardless of the plug-ins in use.

 For more information about the way HTML tags determine plug-in display mode, see "HTML Tags for Plug-in Display."

 [Top] [Using HTML to Display Plug-ins]

HTML Tags for Plug-in Display

A plug-in runs in an HTML page in a Communicator window. The HTML author uses the HTML EMBED and OBJECT tags to invoke the plug-in and control its display. You can use either of these tags to place a plug-in in an HTML layer or section. Sections are part of Netscape Dynamic HTML, and are created with the HTML LAYER tag. The HTML author can make the contents of a section overlay or be covered by other elements included on a page, or manipulate the section independently of the rest of the page. For information about the LAYER tag, see the Dynamic HTML in Netscape Communicator.

 This chapter describes only the use of these tags to display plug-ins and support automatic download with Jar Installation Manager (JIM). For other uses, see the Netscape HTML Tag Reference.

 [Top]

EMBED Tag

The EMBED tag displays the plug-in as part of an HTML document in a rectangular area of the page.

 Communicator loads an embedded plug-in when the user displays an HTML page that contains an embedded object whose MIME type is registered by a plug-in. Plug-ins are embedded in much the same way as GIF or JPEG images are, except that a plug-in can be live and respond to user events, such as mouse clicks.

This section is a brief introduction to this HTML tag. For a detailed description, see the entry for the EMBED tag in the HTML Tag Reference.

 The EMBED tag has the following syntax and attributes:
  

 <EMBED 
  SRC="location"
  TYPE="MIMEtype"
  PLUGINSPAGE="instrURL"
  PLUGINURL="pluginURL"
  ALIGN="LEFT"|"RIGHT"|"TOP"|"BOTTOM"
  BORDER="borderWidth" 
  FRAMEBORDER="NO"
  HEIGHT="height" 
  WIDTH="width"
  UNITS="units"
  HIDDEN="TRUE|FALSE
  HSPACE="horizMargin" 
  VSPACE="vertMargin" 
  NAME="pluginName"
  PALETTE="FOREGROUND"|"BACKGROUND"
>
...
</EMBED>
You must include either the SRC attribute or the TYPE attribute in an EMBED tag. The SRC attribute is the URL of the file to run. The TYPE attribute specifies the MIME type of the plug-in needed to run the file. Navigator uses either the value of the TYPE attribute or the suffix of the filename given as the source to determine which plug-in to use.

Use TYPE for a plug-in that requires no data, for example, a plug-in that draws an analog clock or fetches all of its data dynamically. For a visible plug-in, you must include WIDTH and HEIGHT if you use TYPE; no default value is used.

 New in Netscape Communicator 4.0. The PLUGINURL attribute is the URL of a JAR file. The default plug-in invokes JIM with this JAR file URL, rather than loading the URL into a window or displaying the default plug-in dialog box. It is recommended that you use this attribute rather than PLUGINSPAGE.

 The PLUGINSPAGE attribute is the URL for instructions for installing the plug-in. The JAR Installation Manager uses this URL if a plug-in is registered on the user's machine. Starting with Communicator 4.0, PLUGINSPAGE points to the Plug-in Finder, which determines which plug-in is required and may invoke JIM with JavaScript.

 The EMBED tag has a number of attributes that determine the appearance and size of the plug-in instance, including these:

Use the HIDDEN attribute if you do not want the plug-in to be visible. In this case, you do not need the attributes that describe plug-in appearance. In fact, HIDDEN overrides those attributes if they are present.

New in Netscape Communicator 4.0. Use the NAME attribute, which specifies the name of the plug-in, if the plug-in is communicating with JavaScript.

MS Windows only: The PALETTE attribute indicates whether the plug-in should use the FOREGROUND or BACKGROUND (default) color palette.

 For example, this EMBED tag loads a picture with the imaginary data type dgs. 

<EMBED SRC="mypic.dgs" WIDTH=320 HEIGHT=200 BORDER=25 ALIGN=right>
Communicator interprets the attributes as follows:

Using Custom EMBED Attributes

In addition to these standard attributes, you can create private, plug-in-specific attributes and use them in the EMBED attribute to pass extra information between the HTML page and the plug-in code. Communicator ignores these nonstandard attributes when parsing the HTML. It passes all attributes to the plug-in, allowing the plug-in to examine the list for any private attributes that could modify its behavior.

 For example, a plug-in that displays video could have private attributes that determine whether to start the plug-in automatically or loop the video automatically on playback, as in the following EMBED tag:
  

<EMBED SRC="myavi.avi" WIDTH=100 HEIGHT=125 AUTOSTART=true LOOP=true>
With this EMBED tag, Communicator passes the values to the plug-in, using the arg parameters of the NPP_New call that creates the plug-in instance.
  
 argc = 5
argn = {"SRC", "WIDTH", "HEIGHT", "AUTOSTART", "LOOP"}
argv = {"movie.avi", "100", "125", "TRUE", "TRUE"}
Communicator interprets the attributes as follows: The plug-in must scan its list of attributes to determine whether it should automatically start the video and loop it on playback.

 [Top]

OBJECT Tag

The OBJECT tag embeds a variety of object types in an HTML page. Among these are plug-ins, Java components, ActiveX controls, applets, and images. OBJECT tag attributes determine the type of object to embed, the type and location of the object's implementation (code), and the type and implementation of the object's data.

The OBJECT tag allows you to invoke another object if the browser cannot support the object invoked by the tag. The EMBED tag, which is also used for plug-ins, does not.

Unlike the APPLET tag, OBJECT can contain other HTML attributes, including other OBJECT tags, nested between its opening and closing angle brackets.

This section is a brief introduction to this HTML tag. For a detailed description, see the entry for the OBJECT tag in the HTML Tag Reference.

To embed a variety of object types in an HTML page, use the OBJECT tag. 

<OBJECT
  CLASSID="classFile"
  DATA="dataLocation"
  CODEBASE="classFileDir"
  TYPE="MIMEtype"
  ALIGN="alignment" 
  HEIGHT="pixHeight" 
  WIDTH="pixWidth"
  ID="name"
>
The first set of OBJECT tag attributes are URLs. TYPE represents the MIME type of the plug-in; this is the same as the TYPE attribute of EMBED.

HEIGHT, WIDTH, ALIGN are basic IMG/EMBED/APPLET attributes supported by OBJECT. HEIGHT and WIDTH are required for OBJECT tags that resolve to EMBED tags.

Use the ID attribute, which specifies the name of the plug-in, if the plug-in is communicating with JavaScript. This is equivalent to the NAME attribute of APPLET and EMBED.

 It's up to you to provide enough attributes and to make sure that they do not conflict; for example, the values of WIDTH and HEIGHT may be wrong for the plug-in. Otherwise, the plug-in cannot be embedded. When Communicator encounters an OBJECT tag, it goes through the tag attributes, ignoring or parsing as appropriate. It analyzes the attributes to determine the object type, then determines whether Communicator can handle the type.

[Top] 
[Contents] [Previous] [Next] [Index]
Last Updated: 01/15/97 17:35:54  
Copyright © 1997 Netscape Communications Corporation