gecko-dev/cmd/xfe/plugins/textplugin

 -*- Mode: Text; tab-width: 4; indent-tabs-mode: nil -*-

 The contents of this file are subject to the Netscape Public
 License Version 1.1 (the "License"); you may not use this file
 except in compliance with the License. You may obtain a copy of
 the License at http://www.mozilla.org/NPL/

 Software distributed under the License is distributed on an "AS
 IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
 implied. See the License for the specific language governing
 rights and limitations under the License.

 The Original Code is mozilla.org code.

 The Initial Developer of the Original Code is Netscape
 Communications Corporation.  Portions created by Netscape are
 Copyright (C) 1998 Netscape Communications Corporation. All
 Rights Reserved.

 Contributor(s): 


-----------------------------------------------------------------------
        Netscape Navigator Unix Plugin Architecture V 0.9
-----------------------------------------------------------------------
Wed May 15 23:28:24 PDT 1996				dp@netscape.com


This document describes the architecture of the unix plugins.
This would help developers write their own plugins and interface them
with netscape.



Intended Audience
----------------------------------------------------------------------
        - Plugin developers on unix platforms

This assumes that the developer is aware of when and why a plugin is
required.



Platforms currently supported
----------------------------------------------------------------------
        - SunOS 4.1.3 and above
        - Solaris 5.3
        - Solaris 5.4
        - IRIX 5.2 and above
        - OSF1 V2.0 alpha and above
	- HPUX 09.* 10.*
	- Linux 1.2 (ELF)

Plugins require one of the following versions of the a unix navigator
	- Atlas Release
	- 3.0 browser



Contents
----------------------------------------------------------------------
        - General architecture of Netscape Unix Plugins SDK
        - How to write a plugin
        - Sample Text plugin
	- How to run the sample text plugin
	- Trouble Shooting the sample text plugin
        - Do's and Dont's
	- Resources


General architecture of Netscape Unix Plugins SDK
----------------------------------------------------------------------

----------------------------------------------------------------------
               |                         |
               |                         |
Netscape       |         Wrapper         |             Plugin Developer
Navigator      |         npunix.c        |             npshell.c
               |                         |
Talks with the | Implements function     |  Can ignore the existence of
the plugin via | tables as required      |  functions tables and call NPN_*()
wrapper code   | by the navigator's      |  functions to call the navigator
in npunix.c    | plugin interface and    |  and implement NPP_* functions
               | provides plugin         |  to hookup to the navigator.
               | developers with a       |
               | std. set of functions   |
               |                         |
               | WONT NEED TO EDIT THIS. | FILL UP functions in npshell.c
               | NEED TO COMPILE WITH    | and write many more...
               | THIS.                   |
----------------------------------------------------------------------

The plugin in the unix platform is implemented as a dynamically loadable
module (.so) The navigator searches for these dynamically loadable modules
in the list of directories as specified by the environment variable
NPX_PLUGIN_PATH. This variable can be set to a ':' separated list of
directories. The default path if this environment variable is not set
is "/usr/local/lib/netscape/plugins/:$HOME/.netscape/plugins/"

        NOTE: On SunOS4.1.3, if there are any non-loadable modules in
              any of the directories specified by NPX_PLUGIN_PATH, then
              the dlopen() library call exits rather than giving an error.
              thus causing the navigator to terminate.

The navigator detect which MIME types are recognized by a plugin by calling
NPP_GetMIMEDescription() in npshell.c (via NP_GetMIMEDescription() in
npunix.c). From then on, whenever it detect data of the
particular MIME type, it loads the plugin and creates instances of the
corresponding plugin object. Before creating the first plugin instance
the navigator will call NPP_Initialize() in npshell.c (via NP_Initialize()
in npunix.c). Also after the last plugin instance has been destroyed,
the navigator will call NPP_Shutdown() in npshell.c (via NP_Shutdown()
in npunix.c)


How to write a plugin
----------------------------------------------------------------------
        1. Fill up all the necessary functions in npshell.c
           To hook up and talk with the navigator. Refer to
           "The plugin API" for more information on these
           functions.

        2. Add new functions/files as required by your plugin.
           Use npapi.h for a description of data structures passed
           between the navigator and the plugin code.

        3. Compile the plugin code with npunix.c, npshell.c into
           a platform specific dynamically loadable module.

        4. Install the dynamically loadable module in NPX_PLUGIN_PATH,
	   "/usr/local/lib/netscape/plugins/:$HOME/.netscape/plugins/"
	   by default.

        5. Start the navigator. From now on, whenever the MIME type
           of interest to the plugin is encountered, the navigator
           will call the appropriate functions in the plugin.


Sample Text plugin
----------------------------------------------------------------------
As an example, here is a text plugin. This plugin is intended only to
demonstrate how plugin developers can write plugins. The text plugin
operates on MIME type and extension "text/plain;.txt"
So whenever the navigator gets data with mime type "text/plain"
(or) needs to display a file with the extension ".txt", it passes the
data over to the plugin code as discussed by the Plugin API. The text
plugin creates a scrolled window using motif and displays the data
it received in the window. All code that is specific to the text
plugin is ifdeffed TEXT_PLUGIN in npshell.c


How to run the sample text plugin
----------------------------------------------------------------------
        1. Compile the text plugin code to get a libtextplugin.so
        2. Make a directory say, $HOME/.netscape/plugins

                mkdir $HOME/.netscape/plugins

        3. Copy the libtextplugin.so to that directory

                cp libtextplugin.so $HOME/.netscape/plugins

        4. Set NPX_PLUGIN_PATH to that directory

            for csh:
                setenv NPX_PLUGIN_PATH $HOME/.netscape/plugins
            for ksh/sh:
                NPX_PLUGIN_PATH=$HOME/.netscape/plugins; export NPX_PLUGIN_PATH

        5. Invoke the netscape that is plugin enabled. In the location
           field type in the file URL address of Test1.html
            e.g if Test1.html was found in /home/dp/plugins/SDK/Test.html
                the URL to use would be
                file:/home/dp/plugins/SDK/Test1.html

	Result:
		You will see a page with a motif Multiline Text Widget
		that shows the contents of file Test.txt

		You might get some debug prints in stderr. To turn them
		off, compile your plugin without defining PLUGIN_TRACE.
		This change can be made in the makefile.

Trouble Shooting the sample text plugin
----------------------------------------------------------------------
If you dont see the text plugin,

        (a) See if the file Test1.txt is accessible using a http address

        (b) Check if the server returns "text/plain" as the mime type for
            http access to Test1.txt

	(c) Select Options->General Preferences->Helpers (if available)
	    in the browser and ensure that for the mime-type text/plain,
	    the Sample Text Plugin is enabled.

	(d) LINUX ELF: if you are writing a plugin for Linux that uses
	    the Motif library, that plugin will need to be linked statically
	    against Motif.  The reason for this is that the Mozilla executable
	    is itself compiled statically against Motif (since most Linux users
	    don't have libXm.so at all); and therefore, the Motif symbols are
	    not accessible to plugins.

	The test/ directory has a few plugin tests that you could run
	to verify if things are ok. Each test is a html file and explains
	how to run the test and verify the result.

            

Do's and Dont's
----------------------------------------------------------------------
        - INSTALL YOUR OWN EVENT HANDLERS FOR THE PLUGIN WINDOW TO
          GET EVENTS.
          Netscape Navigator uses Xt/Motif for its display. Plugins
          can use them and install their own event handlers for their
          window.

        - DONT USE WorkProcs IN Xt.
          WorkProcs will not be called.

        - USE THE X RESOURCE NAME SPACE WITH CARE.
          plugins and netscape share the same X resources space.
          So be sure your plugin gets it resources separately.
          The navigator resources do not follow a pattern although
          we eventually will. Until then, chose unique names that
          are not used by the navigator for its X resources for
          X resources and names of widgets used by plugins.

        - TAKE CARE WHEN INSTALLING TIMERS TO GET IDLE CYCLES.
          Plugins installing TIMERS to get idle cycles (e.g for doing
          some animation as long as the plugin is in view) by using the
          XtAppAddTimeOut() should take care to not install 0 interval
          timer callbacks. If they do, then the network events will never
          happen.



Resources
----------------------------------------------------------------------
A collection of resources that will be helpful in plugin development.
This collection is as of 15 May 1996.

http://home.netscape.com/comprod/development_partners/plugin_api/index.html
ftp://ftp.netscape.com/pub/navigator/sdk/
	- SDK is available here.

http://home.netscape.com/eng/mozilla/2.0/handbook/plugins/index.html
	- Plugin development handbook.

http://cgi.netscape.com/eng/mozilla/2.0/extensions/info.cgi
	- Default plugin will take you here.

snews://secnews.netscape.com/netscape.devs-plugins
	- Secure news group for netscape developement partners. All plugin
	  related discussion happens here. To enroll into this contact
	  developer relations at http://developer.netscape.com