Guile applet specification

This chapter has been written by Gordon Irlam, gordoni@cygnus.com, at Cygnus Support, February 28, 1996. It is included here almost verbatim.

This section provides the specification for writing Guile applets for use with the SurfIt! demo browser.

• HTML applet extension
• Applet requirements
• Applet API
• Applet behavior
• Browser behavior

HTML applet extension

Guile Scheme applets are denoted by the mime type application/guile. This is the default type for the file extension .scm.

An applet can be inlined within a HTML document.

<a href="applet.scm" rel=embed>

fallback_html

</a>

The applet applet.scm will be loaded, inserted into the page, and run when the document containing it is first loaded. fallback_html will be displayed by browsers that don't support Guile applets.

An applet may also be invoked when a hyperlink is followed.

<a href="applet.scm"

fallback_html

</a>

When the hyperlink is selected the applet applet.scm will be loaded and executed. The original document will be cleared from the page only if the applet explicitly requests it to be. fallback_html will be displayed by browsers that don't support Guile applets.

Applet requirements

An applet is required to be a syntactically well formed Guile scheme program. When an applet is invoked the corresponding Guile program is retrieved, loaded, and executed.

Every applet is required to include the applet library:

(require 'applet)

Incorporate the applet library into a Guile application. This is needed as a prerequisite to performing any of the other applet commands.

Every applet is required to define a routine to be called by the browser when the browser requires the applet to terminate execution:

Applet API: define-applet-terminate routine

routine is the name of a routine that will be invoked by the browser when the applet is required to terminate execution. If the applet is visible it should destroy the Tk canvas upon which it is visible and then exit.

An applet will persist for as long as it is accessible -- either externally through it's being displayed on a page, or internally through the scheme environment.

Applet API

All applets reside in the same top level environment. This allows state to be shared between applets and to persist between applet invocations.

An applet has access to all the features of a regular Guile scheme program and to the gtcl/gtk Guile extensions. The features of gtk allow the Guile applet to interactively display itself within the parent document.

Note: While Guile provides the ability to control namespaces, and this is necessary to provide a secure environment within which applets can be run, this has not been done for the SurfIt! Guile demo browser. The SurfIt! Guile demo browser is mainly intended as a research prototype, not a production web browser.

Variable: browser-window-name

Applet API: browser-window args

browser-window-name is a string containing the Tk window name of the browser window. browser-window is the corresponding Tcl proc to which window commands can be sent.

Variable: applet-window-name

Appplet API: applet-window args

applet-window-name is a string containing a Tk window name for a frame that can be used to contain the applet. applet-window is the corresponding Tcl proc to which window commands can be sent. The frame still needs inserting into the browser window, assuming the applet is visible.

Variable: applet-embedindex

applet-embedindex is a string containing the offset within the browser window of the applet's anchor. Most commonly this is used when insert the applet into the browser window at the same location as the original html:

(browser-window 'window 'create applet-embedindex :window
                applet-window-name).

Applet API: applet-newpage

This routine clears the current contents of the browser window.

Applet API: applet-parsehtml html

This routine parses the html specified by html and renders the result adding it to bottom of the browser window.

Applet API: applet-loadurl url

This routine loads and renders the contents of the object specified by URL url inserting it into the applet window.

Applet API: applet-loaddata url

This routine loads and returns the contents of the object specified by URL url. Note: This particular routine will probably not be present in guile-r0. Its suggested incorporation into the API, and it's syntax are still tentative.

Applet behavior

Applets should not monopolize the cpu. Instead they should be written using a callback or event loop polling based style so that the Tk event handler can continues to operate, and the user can continue to interact with the browser.

Browser behavior

Any run time error occurring within an applet that goes uncaught will cause the applet to exit, but the browser will continue to function.