This directory contains a "Lisp as an Internet Browser Plugin" example.
It works only in the Allegro CL Enterprise edition.

This functionality is available on Intel Windows, and works with Netscape
and Internet Explorer.

Trying the Example

1. Start the ACL IDE, and load in the rtbuild.cl file found in this directory.
2. When the resulting building phases are complete, exit the Lisp, and
   copy the files found in the resulting rt-plugin directory, which will
   be created in this directory, to the Plugins directory of either your
   Netscape or Internet Explorer installation.  Do not copy the system-dlls
   subdirectory or any of its files.

   Note that if you are using the Windows Explorer to copy the files
   from the rt-plugin/ directory, some of the files may be hidden.  To
   ensure that the Windows Explorer copies all the files, set the
   Windows Explorer options to enable viewing all files.
   
3. Use the browser for which you added the Lisp plugin to view the life.htm
   file found in this directory.

Trying the Example in a Client/Server Environment

1. Build and install the plugin as described above.
2. Copy the life.htm and life.cl files found in this directory to
   a server location.
3. Modify the life.htm copy on the server, changing the line reading:

   <embed src="life.cl" width=400 height=400 console=N>

   to:

   <embed src="life.cl" width=400 height=400 type="application/x-lisp" console=N>
4. Using a browser that has the Lisp plugin installed, view the life.htm
   server page.

About the Example

The example started as a normal Common Graphics project - life
directory found this directory. You can start the ACL IDE and
open the project if you wish to examine it and run it in the usual IDE
environment. Notice that the life game does not use a menu bar - since our goal
is to insert it into the browser window as a pane, it is not appropriate to
depend on a menu bar.

The life.cl file found in this directory consists of:

1. The entire contents of life/life.cl, copied without any change.
2. The contents of life/life.bil, copied without any change.
3. The following code, which is all that is needed to convert the project
   into a plugin application:

   (defvar *window*)
   (defvar *idle-function*)

   (defun do-life ()
     (when (and *window* (not (windows *window*)))
       (setf (state 
	      (make-life :parent *window*
		         :child-p t :border :none
		         :exterior 
		         (make-box 0 0 (width *window*) (height *window*))))
         :normal)))

   (setq *idle-function* #'do-life)

Building Your Own Plug-in Application

For an "applet" similar to the life game, you should be able to adapt
this example to fit your needs.

Here are some things to consider when attempting a more complex project:

1. Lisp source code is sent as clear text.
2. Code is run in interpreted mode.
3. Your app can create windows that are separate from the browser
   window - just use *screen* as the parent as you would in any
   Common Graphics project.
4. If you wish to do cleanup when the browser closes the plug-in window,
   include a 'user::np-delete-hook function (it has no arguments).

There are some strategies you may consider to address #1 and #2, above:

a. Your *idle-function* code can call 'compile to compile compute intensive
   code areas. Note that you can only do this if your license allows to 
   include the compiler in runtime application. Note also that you must
   alter the rtbuild.cl file generate-application options to include the
   compiler.

b. You can exclude most of your app's code from the embedded source file, and
   instead produce a fasl file (or files) that the *idle-function* loads. Note
   that when running locally, sys: is the directory where the HTML source file
   and the embedded Lisp source file is located; when running in client/server
   mode, sys: is the Internet browser Plugins directory.

   To run this app, users must install the Lisp plugin and the required fasl
   file(s) into the Plugins directory.

c. You can build the application functionality into the plugin Lisp
   image. To do this, alter the rtbuild.cl file found in this
   directory to add the required application components. With this
   strategy, only users that have your custom Lisp plugin image will
   be able to run your app in Plugin mode.

Debugging

The Lisp plugin will put up a console window if the first embedded
Lisp application includes a "console=Y" attribute, as in:

<embed src="life.cl" width=400 height=400 console=Y>

Since the image is a runtime image, limited debugging functionality is
available.

For complete debugging using the IDE:

1. Build and install a runtime plugin.
2. Build a Lisp plugin dxl file that includes the IDE by loading the
   idebuild.cl file found in this directory into an IDE Lisp session.
3. Replace the npacl.dxl file in the Plugins directory with the
   resulting npacl.dxl file that is created in this directory.  Copy
   the devel.lic file from ACL installation directory into the Plugins
   directory.
4. Browse the page containing the Lisp plugin application.
5. The IDE will start up.  Be patient while waiting for the plugin app
   to come up - there is a 10 second delay at the first loading to
   insure that the IDE is completely operative before the plugin
   starts running the *idle-function*.
6. To switch back to a runtime Lisp plugin, recopy the files created
   in the rt-plugin directory into the Internet browser's Plugins
   directory.  Remove the devel.lic file from the plugins directory.