Previous section   Next section

Practical Programming in Tcl & Tk, Third Edition
By Brent B. Welch

Table of Contents
Chapter 20.  Safe-Tk and the Browser Plugin

The Browser Plugin

The HTML EMBED tag is used to put various objects into a Web page, including a Tcl program. For example:

<EMBED src=eval.tcl width=400 height=300>

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 than normal toplevels in Tk. The plugin turns off geometry propagation on your main window so 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. For example, you can type this into your browser, or use it as the HREF parameter in a URL link:


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.


I wrote a cute little plugin that calculates 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. I put together a 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:


Setting Up the plugin

There are plugin versions for UNIX, Windows, and Macintosh. The installation scripts take care of installing the plugin in the correct locations, which are described in the next sections about each platform. The plugin and the security policies that are distributed with it will continue to be updated. You should get the latest version from the Tcl/Tk Web site, http://www.scriptics.com/plugin/. If that URL changes, you can find an up-to-date pointer under http://www.beedub.com/book/. The plugin may already be installed at your site. Bring up the About Plugins dialog under Help in your browser to see if the Tcl/Tk plugin is listed.

The plugin is composed of the following parts, although the location of these files varies somewhat among platforms:

  • 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.

Plugin Environment Variables

The plugin can be configured to run Tcl/Tk directly in the browser process, or to run with a small library in the browser that communicates with an external wish application. The default is to run in process. The advantage of the external process is that you can use custom wish shells that can load various extensions. You control this configuration with the environment variables listed in Table 20-2.

Table 20-2. Plugin Environment Variables
TCL_PLUGIN_INPROCESSIf this is defined and 1, then Tcl/Tk is loaded directly into the browser. Otherwise the plugin forks wish.
TCL_PLUGIN_WISHThis names the wish executable used to run Tclets. This must be version 8.0 or higher to properly support embedding.
TCL_PLUGIN_CONSOLEIf this is set to 1, then a console is opened when a Tclet is loaded. The console prompts for Tcl commands that are evaluated in the master interpreter. If the value is something other than 1, then it is taken to be a script (e.g., TkCon) that implements a console.
TCL_PLUGIN_LOGWINDOWIf 1, various status messages from the plugin are displayed.
TCL_PLUGIN_LOGFILEIf defined, this file captures the log output.

UNIX Configuration

Netscape looks in each user's ~/.netscape/plugins for the shared libraries that implement plugins. It also looks in a plugins directory under its main directory, which will vary from site to site. You can define a search path for plugins with the NXP_PLUGIN_PATH environment variable. The plugin script library is in ~/.tclplug/2.0/plugin. You can change this default location by setting the TCL_PLUGIN_DIR environment variable. Once the plugin finds its script library, it assumes the Tcl and Tk script directories, the security policies, and the trust map are in peer directories.

Windows Configuration

The default location for plugins is in the PLUGINS directory of the Netscape installation. The Tcl/Tk plugin also works in Internet Explorer from the same location. The script libraries are found under C:\TCLPLUG\2.0. You can change this location by setting the registry variable:

Software\Sun\Tcl Plugin\2.0\Directory

Macintosh Configuration

Installing the plugin on the Macintosh is a three-step process. In step one you unpack the initial download file, which creates another installer file. In step two you run that installer, which puts files into two locations. You specify one folder that will hold the documentation and the Netscape plugin. The rest of the plugin goes into a plugin folder under the Tool Command Language folder in your system's Extensions folder. It does not conflict with any existing Tcl/Tk installations you may already have. In step three, you complete the process by moving the Tcl Plugin file into the Plugins directory of your Netscape installation.

The current version of the Macintosh plugin is limited to Netscape. Version 4 works better than Netscape 3, and Internet Explorer is not supported at all.

      Previous section   Next section