Writing Grail Plug-in Modules

While the Grail browser is primarily known for its support for applets (Python scripts that execute ``within'' a particular HTML page), it can also be extended on a more permanent basis, by writing plug-in modules.

Grail plug-in modules allow for the more permanent addition of functionality to Grail. The main plug-in types are:

Security Considerations

Unlike applets, Grail plug-ins are executed in unrestricted mode. This means that you should verify the origin and authenticity of any plug-in that you didn't write yourself before installing it. Consider a plug-in to be just another application -- if you don't trust the source or the route through which you got it, don't use it!

Plug-in Locations

Plug-in modules can be installed as part of the standard Grail sources ("standard plug-ins") or installed by the user ("user plug-ins"). User plug-ins override standard plug-ins of the same name. User plug-ins must be installed in a subdirectory of the user's Grail configuration directory (default ~/.grail; $GRAILDIR overrides), in a subdirectory whose name indicates what kind of plug-in it is. The subdirectory names are protocols, html, filetypes, and prefspanels. Standard plug-ins live in subdirectories of the Grail source directory with the same names.

Protocols Plug-ins

A protocol plug-in provides the implementation of a "protocol scheme identifier" such as "http" or "ftp", as found at the start of a URL. Protocol plug-ins can also implement "fake protocols" such as "mailto" (which brings up a dialog for sending mail) or the proposed "data" scheme (where the rest of the URL encodes the data to be "retrieved").

All protocols supported by Grail are implemented by standard protocol plug-ins. These are: doc, file, ftp, hdl, http, mailto, and null.

Writing a "real" protocol plug-in (such as "http") is a fairly complex task, since the plug-in has to operate asynchronously with respect to the rest of Grail. However, writing a "fake protocol" is pretty simple (especially if you subclass of the handler for the "null" scheme). See the Protocol Plug-in Modules Reference Manual for more information.

HTML plug-ins

An HTML plug-in extends Grail's HTML parser with one or more new tags. (HTML plug-ins currently can't override the semantics of existing tags.) Some standard HTML tags are implemented as HTML plug-ins in Grail: fn (HTML 3.0 footnote), form, frameset, isindex, and table. An HTML plug-in module can implement additional tags if those tags can only occur inside the module's primary tag; for example, the form plug-in also implements the input, textarea, select and option tags.

HTML plug-in modules have a fairly complicated interface with Grail's HTML parser as well as with the viewer. See the HTML Plug-in Modules Reference Manual for details.

File type plug-ins

A file type plug-in extends Grail's capability to display documents of a particular (MIME) content type. Standard plug-ins exist for the following content types: audio/basic, image/gif, and image/jpeg.

See the File Type Plug-in Modules Reference Manual.

Preference panel plug-ins

A preference panel plug-in adds another entry to the Preferences menu. All standard preference panels are implemented as plug-ins. See the Preferences Infrastructure document and the Preference Panel Plug-in Reference Manual for information on the architecture and panel development. There is also a complete list of the settings defined in the Grail distribution.

GUI plug-ins

Although they have been planned for a long time, GUI plug-in modules (which would allow you to arbitrarily extend Grail's user interface) are not yet supported.