The Browser Plugin

The HTML EMBED tag is used to put various objects into a Web page, including a Tcl program. Example 20-1 shows the EMBED tag used to insert a Tclet:

Example 20-1 Using EMBED to insert a Tclet

<EMBED
   TYPE="application/x-tcl"
   PLUGINSPAGE="http://www.tcl.tk/plugin/"
   WIDTH="400"
   HEIGHT="300"
   SRC="eval.tcl"
</EMBED>

The width and height are interpreted by the plugin as the size of the embedded window. The src specifies the URL of the program. These parameter names (e.g., width) are case sensitive and should be lowercase. In the above example, eval.tcl is a relative URL, so it should be in the same directory as the HTML file that has the EMBED tag. The window size is fixed in the browser, which is different from normal toplevels in Tk. The plugin turns off geometry propagation on your main window so that your Tclet stays the size allocated.

There are also "full window" Tclets that do not use an EMBED tag at all. Instead, you just specify the .tcl file directly in the URL. In this case, the plugin occupies the whole browser window and will resize as you resize the browser window.

The embed_args and plugin Variables

The parameters in the EMBED tag are available to the Tcl program in the embed_args variable, which is an array with the parameter names as the index values. For example, the string for a ticker-tape Tclet can be passed in the EMBED tag as the string parameter, and the Tclet will use $embed_args(string) as the value to display:

<EMBED src=ticker.tcl width=400 height=50 string="Hello World">

Note that HTML tag parameters are case sensitive. Your Tclet may want to map all the parameter names to lowercase for convenience:

foreach {name value} [array get embed_args] {
   set embed_args([string tolower $name]) $value
}

The plugin array has version, patchLevel, and release elements that identify the version and release date of the plugin implementation.

Example Plugins

The plugin home page is a great place to find Tclet examples. There are several plugins done by the Tcl/Tk team at Sunlabs, plus links to a wide variety of Tclets done on the Net.

http://www.tcl.tk/plugin/

My first plugin was calculator for the effective wheel diameter of multigear bicycles. Brian Lewis, who built the Tcl 8.0 byte-code compiler, explained to me the concept and how important this information is to bicycle enthusiasts. The Tclet that displays the gear combinations on a Tk canvas and lets you change the number of gears and their size. You can find the result at:

http://www.beedub.com/plugin/bike.html

Setting Up the plugin

There are plugin versions for UNIX, Windows, and Macintosh. The installation details vary somewhat between platforms and between releases of the plugin. The following components make up the plugin installation:

• The plugin shared libraries (i.e., DLLs). The Web browser dynamically loads the plugin implementation when it needs to execute a Tclet embedded in a Web page. There is a standard directory that the browser scans for the libraries that implement plugins.

• The Tcl/Tk script libraries. The plugin needs the standard script libraries that come with Tcl and Tk, plus it has its own scripts that complete its implementation. Each platform has a plugin script directory with these subdirectories: tcl, tk, plugin, config, safetcl, and utils. The plugin implementation is in the plugin directory.

• The security policies. These are kept in a safetcl directory that is a peer of the Tcl script library.

• The trust configuration. This defines what Tclets can use which security policies. This is in a config directory that is a peer of the Tcl script library.

• Local hooks. Local customization is supported by two hooks, siteInit and siteSafeInit. The siteInit procedure is called from the plugin when it first loads, and siteSafeInit is called when each applet is initialized. It is called with the name of the slave interpreter and the list of arguments from the <EMBED> tag. You can provide these as scripts that get loaded from the auto_path of the master interpreter. Chapter 12 describes how to manage script libraries found in the auto_path. The plugin also sources a personal start up script in which you can define siteInit and siteSafeInit. This script is ~/.pluginrc on UNIX and plugin/tclplugin.rc on Windows and Macintosh.