- multimedia viewers such as Macromedia Shockwave and Adobe Acrobat
- utilities that provide object embedding and compression/decompression services
- applications that range from personal information managers to games
- register one or more MIME types
- draw into a part of a browser window
- receive keyboard and mouse events
- obtain data from the network using URLs
- post data to URLs
- add hyperlinks or hotspots that link to new URLs
- draw into sections on an HTML page
You can see which plug-ins are installed on your system and have been properly associated with the browser 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. Notice in view-source that this information is simply gathered from the DOM.
Before plug-ins, there were helper applications. A helper application is a separate, free-standing application that can be started from the 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 Netscape Gecko starts, it checks for plug-in modules in the plugins directory or Plug-ins folder (Mac OS) located in the same folder or directory as the browser application. For more information, see "How Netscape Gecko Finds Plug-ins"
- check for a plug-in with a matching MIME type
- load the plug-in code into memory
- initialize the plug-in
- create a new instance of the plug-in
Netscape Gecko can load multiple instances of the same plug-in on a single page, or in several open windows at the same time. If you are browsing a page that has several embedded real audio clips, for example, the browser will create as many instances of the RealPlayer plug-in as are needed (though of course playing several real audio files at the same time would seldom be a good idea). 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.
Plug-ins are dynamic code modules that are associated with one or more MIME types. When the browser 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.
- When Netscape Gecko encounters data of a MIME type registered for a plug-in (either embedded in an HTML page or in a separate file), it dynamically loads the plug-in code into memory, if it hasn't been loaded already, and it creates a new instance of the plug-in.
Netscape Gecko calls the plug-in API function NP_Initialize1 when the plug-in code is first loaded. By convention, all of the plug-in specific functions have the prefix "NPP", and all of the browser-specific functions have the prefix "NPN"
- The browser calls the plug-in API function NPP_New when the instance is created. Multiple instances of the same plug-in can exist (a) if there are multiple embedded objects on a single page, or (b) if several browser windows are open and each displays the same data type.
- A plug-in instance is deleted when a user leaves the instance's page or closes its window; Netscape Gecko calls the function NPP_Destroy to inform the plug-in that the instance is being deleted.
- When the last instance of a plug-in is deleted, the plug-in code is unloaded from memory. Netscape Gecko calls the function NP_Shutdown. Plug-ins consume no resources (other than disk space) when not loaded.
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.
See "Initialization and Destruction" for more information about using these methods.
When a Netscape Gecko-based browser starts up on Windows or Unix systems, it checks for plug-in modules in the path pointed to by MOZ_PLUGIN_PATH. After that, it checks in the plug-ins directory for the platform:
- MS Windows: plugins subdirectory, in the same directory as the browser application.
- Mac OS: Plug-ins folder. A Mac OS plug-in can reside in a different directory if you install a Macintosh alias that links to the plug-in in the Plug-ins folder.
- Unix: usr/local/lib/netscape/plugins or $HOME/.mozilla/plugins. If you want to use a different directory, set the MOZ_PLUGIN_PATH environment variable to its filepath, for example,
Netscape Gecko searches any directory that this variable specifies. The local user location, if it exists, overrides the network location.
- Finally, on the Mac, the browser scans the ~/Library/Internet Plugins then /Library/Internet Plugins. Within these directories, the plug-ins are ordered by date.
On all platforms, the plug-ins subdirectory or folder must be in the same directory as the browser application. Users can install plug-ins in this directory manually, by using a binary installer program, or by using the XPInstall API to write an installation script, which the browser then uses to perform the installation. For more information about these options, 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). Netscape Gecko 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 first plug-in registered handles the MIME type. For information about the way MIME types are assigned, see Registering Plug-ins.
A plug-in is a native code library whose source conforms to standard C syntax. The Plug-in Application Programming Interface (API) is made up of two groups of functions and a set of shared data structures.
- Plug-in methods are functions that you implement in the plug-in; Netscape
Gecko calls these functions. The names of all the plug-in functions in the API begin with NPP_, for example, NPP_New. There are also a couple of functions (i.e., NP_Initialize and NP_Shutdown), that are direct library entry points and not related to any particular plug-in instance.
- Browser methods are functions implemented by Netscape Gecko; the plug-in calls these functions. The names of all the browser functions in the API begin with NPN_, for example, NPN_Write.
- Data structures are plug-in-specific types defined for use in the Plug-in API. The names of structures begin with NP, for example, NPWindow.
All plug-in names in the API start with NP. 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.
A plug-in is a dynamic code module that is native to the specific platform on which the browser is running. It is a code library, rather than an application or an applet, and runs only from the browser. 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 the Netscape Gecko core functionality by providing support for new data types.
- MS Windows: .DLL (Dynamic Link Library) files
- Unix: .SO or .DSO (Shared Objects) files
- Mac OS: PowerPC Shared Library files.
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. Note, however, that plug-ins are windowed by default, as windowed plug-ins are in general easier to develop and more stable to use.
- A windowed plug-in is drawn into its own native window on a web page. Windowed plug-ins are opaque and always come to the top HTML section of a web page.
- A windowless plug-in need not be drawn in a native window; it is drawn in its own drawing target. Windowless plug-ins can be opaque or transparent, and can be invoked in HTML sections.
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."
The blue puzzle piece that appears in the HTML page's plug-in window when the default plug-in loads is meant to signify that the browser is missing a piece that it needs to display or play the requested media.
How the plug-in HTML tag was coded determines what action is taken when the user clicks the plug-in piece. If the browser cannot handle the given MIME type, then the default plug-in checks to see if there is a plug-in referenced in the OBJECT tag that defines the media. If there is, then thedefault plug-in prompts the user to download that plug-in from the specified location. If a plug-in is not specified in the OBJECT tag, then the default plug-in looks for child elements, such as other OBJECT tag, which will provide more specific information about how to handle the specified media type.
- The way the developer writes the plug-in determines whether it is displayed in its own window or is windowless.
- The way the content provider uses HTML tags to invoke the plug-in determines its display mode: whether it is embedded in a page, is part of a section, appears on its own separate page, or is hidden.
This section 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:
- embedded in a web page and visible
- embedded in a web page and hidden
- displayed as a full page in its own window
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 Netscape Gecko encounters the OBJECT or EMBED tag in a document, it attempts to find and display the file represented by the DATA and SRC attributes, respectively. The HEIGHT and WIDTH attributes of the OBJECT tag determine the size of the embedded plug-in in the HTML page. For example, this OBJECT tag calls a plug-in that displays video:
In this case, the OBJECT tag that picks up these special style definitions would have a class of hidden. Using the class attribute and the CSS block above, you can simulate the behavior of the hidden plug-in in the EMBED tag:
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. Netscape Gecko looks up the MIME type and loads the appropriate plug-in if it finds a plug-in registered to that type. This type of plug-in completely fills the web page. Full-page plug-ins are commonly used for document viewers, such as Adobe Acrobat.
The browser 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 the browser, such as navigation, history, and opening files, apply to all pages, regardless of the plug-ins in use.
The OBJECT tag is part of the HTML specification for generic inclusion of special media in a web page. It embeds a variety of object types in an HTML page, including 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.
Plug-ins were originally designed to work with the EMBED tag rather than the OBJECT tag (see "Using the EMBED Tag for Plug-in Display"), but the OBJECT tag itself provides some flexibility here. In particular, 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.
Also, unlike the APPLET tag, OBJECT can contain other HTML attributes, including other OBJECT tags, nested between its opening and closing angle brackets. So, for example, though Netscape Gecko does not support the CLASSID attribute of the OBJECT tag-which was used for Java classes and ActiveX plug-ins embedded in pages-OBJECT tags can be nested to support different plug-in implementations.
See the Mozilla ActiveX project page in the "Plug-in References" section below for more information about embedding ActiveX controls in plug-ins or embedding plug-ins in ActiveX applications.
The outermost OBJECT tag defines the CLASSID; the first nested OBJECT uses the TYPE value "application/x-shockwave-flash" to load the shockwave plug-in, and the innermost OBJECT exposes a download page for users that do not already have the necessary plug-in. This nesting is quite common in the use of OBJECT tags, and lets you avoid code forking for different browser.
- The browser looks at the MIME type of the top element. If it knows how to deal with that MIME type (i.e., by loading a plug-in that's been registered for it), then it does so.
- If the browser cannot handle the MIME type, it looks in the element for a pointer to a plug-in that can be used to handle that MIME type. The browser downloads the requested plug-in.
- If the MIME type is unknown and there is no reference to a plug-in that can be used, the browser descends into the child element, where these rules for handling MIME types are repeated.
- CLASSID is the URL of the specific object implementation. This attribute is similar to the CODE attribute of the APPLET tag. Though Netscape Gecko does not support this OBJECT attribute, you can nest OBJECT tags with different attributes to use the OBJECT tag for embedding plug-ins on any browser platform (see the example above).
- DATA represents the URL of the object's data; this is equivalent to the SRC attribute of EMBED.
- CODEBASE represents the URL of the plug-in; this is the same as the CODEBASE attribute of the APPLET tag. For plug-ins, CODEBASE is the same as PLUGINSPAGE.
- 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.
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.
Netscape Gecko interprets the attributes as follows: When the browser 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 the browser can handle the type.
- If the browser can handle the type-that is, if a plug-in exists for that type-then all tags and attributes up to the closing </OBJECT> tag, except PARAM tags and other OBJECT tags, are filtered.
- If the browser cannot handle the type, or cannot determine the type, it cannot embed the object. Subsequent HTML is parsed as normal.
A plug-in runs in an HTML page in a browser window. The HTML author uses the HTML EMBED tag to invoke the plug-in and control its display. Though the OBJECT tag is the preferred way to invoke plug-ins (see "Using the OBJECT Tag for Plug-in Display"), the EMBED tag can be used for backward compatibility with Netscape 4.x browsers, and in cases where you specifically want to prompt the user to install a plug-in, because the default plug-in is only automatically invoked when you use the EMBED tag.
Netscape Gecko 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.
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 to specify the media type or MIME type necessary to display the plug-in. It is good practice to include the MIME type in all the plug-in HTML tags. You can 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.
The PLUGINURL attribute is the URL of the plug-in or of the XPI in which the plug-in is stored (see "Installing Plug-ins" for more information on the XPI file format).
- The BORDER and FRAMEBORDER attributes specify the size of a border for the plug-in or draw a borderless plug-in
- HEIGHT, WIDTH, and UNITS determine the size of the plug-in in the HTML page. If the plug-in is not hidden, the HEIGHT and WIDTH attributes are required.
- HSPACE and VSPACE create a margin of the specified width, in pixels, around the plug-in.
- ALIGN specifies the alignment for the plug-in relative to the web page.
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.
- SRC: Load the data file and determine the MIME type of the data.
- WIDTH and HEIGHT: Set the area of the page handled by the plug-in to 320 by 200 pixels. In general, use CSS to control the size and location of elements within an HTML page.
- BORDER: Draw a border 25 pixels wide around the plug-in.
- ALIGN: Align the plug-in at the right side of the web page.
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. The browser ignores these nonstandard attributes when parsing the HTML, but 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:
- SRC: Load the data file and determine the MIME type of the data.
- WIDTH and HEIGHT: Set the area of the page handled by the plug-in to 100 by 125 pixels.
- AUTOSTART and LOOP: Ignore these private attributes and pass them along to the plug-in with the rest of the attributes.
The plug-in must scan its list of attributes to determine whether it should automatically start the video and loop it on playback. Note that with an OBJECT tag, PARAM values are also sent in this array after the attributes, separated by a PARAM entry.
Note that NP_Initialize and NP_Shutdown are not technically a part of the function table that the plug-in hands to the browser. The browser calls them when the plug-in software is loaded and unloaded. These functions are exported from the plug-in DLL and accessed with a system table lookup, which means that they are not related to any particular plug-in instance. Again, see "Initialization and Destruction" for more information about initializing and destroying plug-ins.