home *** CD-ROM | disk | FTP | other *** search
/ Tools / WinSN5.0Ver.iso / NETSCAP.50 / WIN1998.ZIP / ns / cmd / xfe / plugins / textplugin / README < prev    next >
Encoding:
Text File  |  1998-04-08  |  10.4 KB  |  253 lines
  1.  -*- Mode: Text; tab-width: 4; indent-tabs-mode: nil -*-
  2.  
  3.  The contents of this file are subject to the Netscape Public License
  4.  Version 1.0 (the "NPL"); you may not use this file except in
  5.  compliance with the NPL.  You may obtain a copy of the NPL at
  6.  http://www.mozilla.org/NPL/
  7.  
  8.  Software distributed under the NPL is distributed on an "AS IS" basis,
  9.  WITHOUT WARRANTY OF ANY KIND, either express or implied. See the NPL
  10.  for the specific language governing rights and limitations under the
  11.  NPL.
  12.  
  13.  The Initial Developer of this code under the NPL is Netscape
  14.  Communications Corporation.  Portions created by Netscape are
  15.  Copyright (C) 1998 Netscape Communications Corporation.  All Rights
  16.  Reserved.
  17.  
  18.  
  19. -----------------------------------------------------------------------
  20.         Netscape Navigator Unix Plugin Architecture V 0.9
  21. -----------------------------------------------------------------------
  22. Wed May 15 23:28:24 PDT 1996                dp@netscape.com
  23.  
  24.  
  25. This document describes the architecture of the unix plugins.
  26. This would help developers write their own plugins and interface them
  27. with netscape.
  28.  
  29.  
  30.  
  31. Intended Audience
  32. ----------------------------------------------------------------------
  33.         - Plugin developers on unix platforms
  34.  
  35. This assumes that the developer is aware of when and why a plugin is
  36. required.
  37.  
  38.  
  39.  
  40. Platforms currently supported
  41. ----------------------------------------------------------------------
  42.         - SunOS 4.1.3 and above
  43.         - Solaris 5.3
  44.         - Solaris 5.4
  45.         - IRIX 5.2 and above
  46.         - OSF1 V2.0 alpha and above
  47.     - HPUX 09.* 10.*
  48.     - Linux 1.2 (ELF)
  49.  
  50. Plugins require one of the following versions of the a unix navigator
  51.     - Atlas Release
  52.     - 3.0 browser
  53.  
  54.  
  55.  
  56. Contents
  57. ----------------------------------------------------------------------
  58.         - General architecture of Netscape Unix Plugins SDK
  59.         - How to write a plugin
  60.         - Sample Text plugin
  61.     - How to run the sample text plugin
  62.     - Trouble Shooting the sample text plugin
  63.         - Do's and Dont's
  64.     - Resources
  65.  
  66.  
  67. General architecture of Netscape Unix Plugins SDK
  68. ----------------------------------------------------------------------
  69.  
  70. ----------------------------------------------------------------------
  71.                |                         |
  72.                |                         |
  73. Netscape       |         Wrapper         |             Plugin Developer
  74. Navigator      |         npunix.c        |             npshell.c
  75.                |                         |
  76. Talks with the | Implements function     |  Can ignore the existence of
  77. the plugin via | tables as required      |  functions tables and call NPN_*()
  78. wrapper code   | by the navigator's      |  functions to call the navigator
  79. in npunix.c    | plugin interface and    |  and implement NPP_* functions
  80.                | provides plugin         |  to hookup to the navigator.
  81.                | developers with a       |
  82.                | std. set of functions   |
  83.                |                         |
  84.                | WONT NEED TO EDIT THIS. | FILL UP functions in npshell.c
  85.                | NEED TO COMPILE WITH    | and write many more...
  86.                | THIS.                   |
  87. ----------------------------------------------------------------------
  88.  
  89. The plugin in the unix platform is implemented as a dynamically loadable
  90. module (.so) The navigator searches for these dynamically loadable modules
  91. in the list of directories as specified by the environment variable
  92. NPX_PLUGIN_PATH. This variable can be set to a ':' separated list of
  93. directories. The default path if this environment variable is not set
  94. is "/usr/local/lib/netscape/plugins/:$HOME/.netscape/plugins/"
  95.  
  96.         NOTE: On SunOS4.1.3, if there are any non-loadable modules in
  97.               any of the directories specified by NPX_PLUGIN_PATH, then
  98.               the dlopen() library call exits rather than giving an error.
  99.               thus causing the navigator to terminate.
  100.  
  101. The navigator detect which MIME types are recognized by a plugin by calling
  102. NPP_GetMIMEDescription() in npshell.c (via NP_GetMIMEDescription() in
  103. npunix.c). From then on, whenever it detect data of the
  104. particular MIME type, it loads the plugin and creates instances of the
  105. corresponding plugin object. Before creating the first plugin instance
  106. the navigator will call NPP_Initialize() in npshell.c (via NP_Initialize()
  107. in npunix.c). Also after the last plugin instance has been destroyed,
  108. the navigator will call NPP_Shutdown() in npshell.c (via NP_Shutdown()
  109. in npunix.c)
  110.  
  111.  
  112. How to write a plugin
  113. ----------------------------------------------------------------------
  114.         1. Fill up all the necessary functions in npshell.c
  115.            To hook up and talk with the navigator. Refer to
  116.            "The plugin API" for more information on these
  117.            functions.
  118.  
  119.         2. Add new functions/files as required by your plugin.
  120.            Use npapi.h for a description of data structures passed
  121.            between the navigator and the plugin code.
  122.  
  123.         3. Compile the plugin code with npunix.c, npshell.c into
  124.            a platform specific dynamically loadable module.
  125.  
  126.         4. Install the dynamically loadable module in NPX_PLUGIN_PATH,
  127.        "/usr/local/lib/netscape/plugins/:$HOME/.netscape/plugins/"
  128.        by default.
  129.  
  130.         5. Start the navigator. From now on, whenever the MIME type
  131.            of interest to the plugin is encountered, the navigator
  132.            will call the appropriate functions in the plugin.
  133.  
  134.  
  135. Sample Text plugin
  136. ----------------------------------------------------------------------
  137. As an example, here is a text plugin. This plugin is intended only to
  138. demonstrate how plugin developers can write plugins. The text plugin
  139. operates on MIME type and extension "text/plain;.txt"
  140. So whenever the navigator gets data with mime type "text/plain"
  141. (or) needs to display a file with the extension ".txt", it passes the
  142. data over to the plugin code as discussed by the Plugin API. The text
  143. plugin creates a scrolled window using motif and displays the data
  144. it received in the window. All code that is specific to the text
  145. plugin is ifdeffed TEXT_PLUGIN in npshell.c
  146.  
  147.  
  148. How to run the sample text plugin
  149. ----------------------------------------------------------------------
  150.         1. Compile the text plugin code to get a libtextplugin.so
  151.         2. Make a directory say, $HOME/.netscape/plugins
  152.  
  153.                 mkdir $HOME/.netscape/plugins
  154.  
  155.         3. Copy the libtextplugin.so to that directory
  156.  
  157.                 cp libtextplugin.so $HOME/.netscape/plugins
  158.  
  159.         4. Set NPX_PLUGIN_PATH to that directory
  160.  
  161.             for csh:
  162.                 setenv NPX_PLUGIN_PATH $HOME/.netscape/plugins
  163.             for ksh/sh:
  164.                 NPX_PLUGIN_PATH=$HOME/.netscape/plugins; export NPX_PLUGIN_PATH
  165.  
  166.         5. Invoke the netscape that is plugin enabled. In the location
  167.            field type in the file URL address of Test1.html
  168.             e.g if Test1.html was found in /home/dp/plugins/SDK/Test.html
  169.                 the URL to use would be
  170.                 file:/home/dp/plugins/SDK/Test1.html
  171.  
  172.     Result:
  173.         You will see a page with a motif Multiline Text Widget
  174.         that shows the contents of file Test.txt
  175.  
  176.         You might get some debug prints in stderr. To turn them
  177.         off, compile your plugin without defining PLUGIN_TRACE.
  178.         This change can be made in the makefile.
  179.  
  180. Trouble Shooting the sample text plugin
  181. ----------------------------------------------------------------------
  182. If you dont see the text plugin,
  183.  
  184.         (a) See if the file Test1.txt is accessible using a http address
  185.  
  186.         (b) Check if the server returns "text/plain" as the mime type for
  187.             http access to Test1.txt
  188.  
  189.     (c) Select Options->General Preferences->Helpers (if available)
  190.         in the browser and ensure that for the mime-type text/plain,
  191.         the Sample Text Plugin is enabled.
  192.  
  193.     (d) LINUX ELF: if you are writing a plugin for Linux that uses
  194.         the Motif library, that plugin will need to be linked statically
  195.         against Motif.  The reason for this is that the Mozilla executable
  196.         is itself compiled statically against Motif (since most Linux users
  197.         don't have libXm.so at all); and therefore, the Motif symbols are
  198.         not accessible to plugins.
  199.  
  200.     The test/ directory has a few plugin tests that you could run
  201.     to verify if things are ok. Each test is a html file and explains
  202.     how to run the test and verify the result.
  203.  
  204.             
  205.  
  206. Do's and Dont's
  207. ----------------------------------------------------------------------
  208.         - INSTALL YOUR OWN EVENT HANDLERS FOR THE PLUGIN WINDOW TO
  209.           GET EVENTS.
  210.           Netscape Navigator uses Xt/Motif for its display. Plugins
  211.           can use them and install their own event handlers for their
  212.           window.
  213.  
  214.         - DONT USE WorkProcs IN Xt.
  215.           WorkProcs will not be called.
  216.  
  217.         - USE THE X RESOURCE NAME SPACE WITH CARE.
  218.           plugins and netscape share the same X resources space.
  219.           So be sure your plugin gets it resources separately.
  220.           The navigator resources do not follow a pattern although
  221.           we eventually will. Until then, chose unique names that
  222.           are not used by the navigator for its X resources for
  223.           X resources and names of widgets used by plugins.
  224.  
  225.         - TAKE CARE WHEN INSTALLING TIMERS TO GET IDLE CYCLES.
  226.           Plugins installing TIMERS to get idle cycles (e.g for doing
  227.           some animation as long as the plugin is in view) by using the
  228.           XtAppAddTimeOut() should take care to not install 0 interval
  229.           timer callbacks. If they do, then the network events will never
  230.           happen.
  231.  
  232.  
  233.  
  234. Resources
  235. ----------------------------------------------------------------------
  236. A collection of resources that will be helpful in plugin development.
  237. This collection is as of 15 May 1996.
  238.  
  239. http://home.netscape.com/comprod/development_partners/plugin_api/index.html
  240. ftp://ftp.netscape.com/pub/navigator/sdk/
  241.     - SDK is available here.
  242.  
  243. http://home.netscape.com/eng/mozilla/2.0/handbook/plugins/index.html
  244.     - Plugin development handbook.
  245.  
  246. http://cgi.netscape.com/eng/mozilla/2.0/extensions/info.cgi
  247.     - Default plugin will take you here.
  248.  
  249. snews://secnews.netscape.com/netscape.devs-plugins
  250.     - Secure news group for netscape developement partners. All plugin
  251.       related discussion happens here. To enroll into this contact
  252.       developer relations at http://developer.netscape.com
  253.