Including Applets in HTML Documents
There are several methods for including a Tcl applet in a HTML document.
An applet may be "inlined" at any point in the document by using an
anchor element with the REL=embed attribute:
<A REL=embed HREF="applet">...</a>
Note that the use of the <A> tag may not be satisfactory in general, since <A> tags cannot be nested. The proposed <EMBED> tag may be used in the future. An applet may be specified as the destination anchor of a hyperlink, for example: <A HREF="tcl/appinfo.tcl">. In this case, the hyperpage is not cleared when the applet is loaded so that the applet may operate on the hyperdocument which invoked it.
Another method is to specify an applet as the SCRIPT attribute of a form, for example:
<FORM METHOD=GET ACTION="..." SCRIPT="applet">
Safety, Security and Privacy
Given that an applet may contain arbitrary code that is downloaded from a remote,
autonomous source the issues of safety, security and privacy arise. Such applets
are said to contain foreign code. SurfIt!
addresses these issues as follows to ensure that the user's computer is not compromised
in any way.
Whenever SurfIt! executes foreign code any error conditions are caught and ignored.
The execution of one applet should not affect any other applets.
For example, a malicious applet may wish to interfere with the operation
of a competing vendor's applet.
The applet execution environment guarantees that
applet are kept completely independent of each other.
The applet interface has been designed to prevent breaches of privacy.
Applets are given access to the Tk toolkit via the Safe-Tk
extension, which imposes some restrictions on the widgets provided by Tk.
A toplevel widget
is automatically created for the applet. The applet may refer to this
window as the path '.'. The applet is also granted access to the browser
window in which the applet was loaded. The
applet embedwindow
command is used to get a special pathname
for this window. For an example see
appinfo.tcl.
Any scripts for Tk widgets specified via -command
style options are
evaluated in the
applet's safe interpreter. Unfortunately, it is not currently possible to
specify variables for Tk widgets
(such as for the -textvariable
option) since variables cannot be accessed
from other interpreters. This restriction will be removed in a future version
of Tcl or Safe-Tk.
Clearing the Hyperwindow
When a hyperlink is activated that specifies an applet as the destination anchor
the hyperpage is not automatically cleared. It is then up to the applet to clear
the hyperpage page once it has commenced execution. This allows an applet to
manipulate the document
from which it is referenced (for example,
eatdoc.tcl),
or for applets to be loaded without affecting
the current document if they are unrelated
(a trivial example is
example1.tcl).
The applet may use the
applet newpage
command to clear the
hyperpage if necessary.
Applet Scope and Longevity
The SurfIt! browser creates objects of four different types, as follows:
Applets are attached to one of the above types of objects.
When an applet is initially loaded it is attached to the hyperpage which loaded it,
unless the applet is loaded as an attribute of a form, in which case the applet
is attached to that form instead. An applet may use the
applet level
command to change
which object it is attached to. An example is
eatdoc.tcl.
For privacy reasons, applets may only attach to another object of a higher level.
When a hyperpage is cleared to load a new hyperdocument any applets currently attached to the hyperpage, or to any forms within that hyperpage, are destroyed. Any applets attached to a hyperwindow are destroyed when that object is destroyed. Applets attached at the browser level can only be destroyed either voluntarily by the applet itself or by the user via the browser 'Applet' menu.
The Applet Command
The applet interacts with the browser by using the applet
command.
The following methods are defined:
applet browserversion
SurfIt! 0.4alpha
.
An example of its use is
appinfo.tcl.
applet embedwindow
applet embedindex
applet flush URL
URL
from the browser's cache.
For an example see
autopilot.tcl.
applet formendindex
applet formitems
{{type path} ...}
where type is a
valid type for <INPUT> elements, select
or
textarea
for the
<SELECT> and <TEXTAREA> elements respectively. path is
the pathname of the Tk widget which handles input for that element, or an empty
string if the input element is a hidden type.
The applet is also notified when form items are created via the HMapplet_item callin.
applet level ?level?
form
, hyperpage
,
hyperwindow
or browser
. If an argument is supplied then
the applet is reattached at the given level. Applets are only
allowed to promote themselves; they may not change to more
specific levels. An applet attached at the form level may not
change to another level.
applet loaddata url data callback
SurfIt! provides visual feedback to the user to indicate that data is being transferred. It is important for the user to be aware of the actions of the applet in case a malicious applet attempts to abuse network resources.
applet loadurl url ?type?
applet newpage
applet parsehtml html
exit ?code?
destroy .
has the same effect;
if the applet does not require its own toplevel window then it should
use wm withdraw .
instead.
puts ?filed? text
stdout
is used by default, and only
stdout
or stderr
are allowed. The string is prepended
by which applet is outputing the string, to ensure that the user can distinguish
the output of applets from the browser.
getclock convertclock fmtclock random
blt_table
terminate
formready
HMsubmit_form method query
method is the form method by which the query is being sent to the server, and may be one of GET or PUT.
query is a Tcl list describing the query that is to be sent.
The list is of the form {name1 value1 name2 value2 ...}
.
This list is mapped to the application/x-url-www-encoded form
name1=value1&name2=value2&...
HMapplet_item type name value item
type is the type of the input item and may be any of the valid types for HTML <INPUT> items.
name is the name attribute given to the input item.
value is the input item's initial value, if any.
item is the pathname for the widget heirarchy which interacts with the user for this input item. The widget class will depend on the input item type. Hidden-type input items never have a widget associated with them.
anchor_activation url
pageloaded
However, the current implementation of Tcl does not prevent "denial-of-service"
attacks against SurfIt! itself - ie. an attack to prevent the browser from
being usable. While I don't want to make things easy for nasty people, it
is so easy to hang the browser that I thought I'd better warn legitimate
applet developers to take care when writing applets. The problem is that applet
scripts are evaluated synchronously by the (trusted) master interpreter which
means that if an applet script never finishes then the browser will never
regain the flow of control, thereby hanging the browser.
The script while {1} {}
is quite enough to achieve this effect.
If such an attack occurs (either maliciously or by accident) then the only recourse is to kill the SurfIt! process :-( . Future versions of Tcl will implement resource usage constraints which will be used to solve this problem.
Author: Steve Ball