Documentation is found at the Tcl Developer Exchange. This documentation does not tell you what you can do in the Tclet. Instead it talks a bout "Policies".
Policies are the rules which determine what commands are allowed and not allowed to be used in a plugin. This is determined on the basis of classes of restrictive command sets, ranging from the most resticted home policy up to the unrestricted trusted policy. home is the default policy for plugins.
The home policy allows the tclet to access facilities on the home (host) which sent the tclet. This means that a Tclet on your webpage that you view on your own computer may not behave the same on someone elses computer. Interactions with the webpage-viewer's computer are prevented.
The Tclet cannot be used to save a file on the viewers computer (unless you view the tcllet on your own server), not even clipboard access etc. Basically all the tclet provides is a window by which the viewer can see whatever you want to show them from your computer. Thats it.
But for simple games, demonstrations, static illustrations or illustrations that respond to the user it is great.
In most browsers a simple <embed> tag is sufficient, as in:
Microsoft is still engaged in legal disputes about its use of <embed> so the <object> tag has to be used instead. So the invocation above only produces a blank box. This situation is similar to that for flash and other plugins. The <object> tag is supposed to be different from <embed> which accounts for its clumsy syntax. The general format for invoking the plugin is:
Notice the two different ways of specifying parameters - <param name='myArg' value='itsValue' /> in the <object> tag and the myArg='itsValue' in the <embed> tag. With this html you should be able to see the tclet displayed here.
Notice that "id" and "classid" do not appear in the embed_args array. This keeps the interface the same as for <embed>.
I use the following routines to create my <object/embed> html for my webpages.
[plugin] is a generic procedure for all plugins, so it can do Flash as well as anything else.
["plugin tcl"] is the special form for a Tcl Plugin. Notice the quotes.
Where the height and width determine the size of the window on the webpage in pixels. The size of the window is not determined from the Tcl code, so it is up to you to match the dimensions.
The plugin procedure is for use in a server or some other program which is generating the html code for the webpage. There are two options here. If the webpage being created is static, or pseudo-static, for instance it is a cached template page which is only sometimes regenerated in response to a page request, then in this case the plugin procedure above needs to be used. But if the page is being dynamically generated in response to each user request then the plugin procedure can look at its environment and produce either the <object> or the <embed> html code required by the particular user.
Write the plugin procedure which does this.
Within the Tclet the embed_args array contains an element for each parameter passed into the tclet from the html. This means that you can size your tclet based on the embed_args(width) and embed_args(height) values. The Tclet above echoes the embed_args values back. someArg becomes an array element variable known in the Tclet.
The height and width values passed into the tclet can be used there to scale the tclet if you wish or to determine if the tclet needs scrollbars to be displayed properly.
Notice that the embed_args array has an element embed_mode set to embed. This is a way you can tell that your tcl code is being used as a tclet without relying on the existence of the embed_args array which you may find convenient to have regardless of whether your Tcl is in a tclet or is just a wish script.
You need to click inside the plugin frame in order to get focus. Then you can move the scrollbar. The text widget containing the text has text editor functions - select ,insert and delete. Copy and Paste are not available as they access the system clipboard. The Tclet code is shown below:
frame .f -borderwidth 10 -relief raised -background #ff0000
pack .f
text .f.t -yscrollcommand {.f.sy set} -width 60
pack .f.t -side left -fill both -expand true
scrollbar .f.sy -command {.f.t yview} -orient vertical
pack .f.sy -side right -fill y
.f.t insert end "Echo Plugin Parameters"
foreach i [array names embed_args] {
.f.t insert end "\nembed_args($i) = $embed_args($i)"
}
# Notes on this Tclet
#
# the frame .f enclosing the text and scrollbar widgets is given some borderwidth,
# relief and colour so that you can see it clearly.
#
# the frame height and width dimensions are in pixels
# while the text height and width are in lines and characters respectively
The man-type webpage provides a detailed specification of the Plugin. A couple of things to note here are:
One webpage can source the same tclet several times. Each tclet is run in its own independant interpreter. A tclet does not share any resources with other Tclets on the same webpage.
The src attribute accets a URL relative to the webpage it is invoked in. You typically keep the tclet code file in the same directory, or else in a Tclet library with an absolute URL.
The source file must end in .tcl. This is used to determine that it is the Tcl Plugin that gets invoked and not Flash or javascript. In this case you can leave out the type=application/x-tcl attribute but this is not good practice.
A script attribute can be used. The script attribute contains Tcl code which is appended to the code from the source attribute, if present. You can have the script attribute without the source. In this case you must have the type attribute to tell the browser to use the tcl plugin. The browser is not clever enough to work it out from looking at your code. Some browsers may not cope with a script but no src attribuite, but this now a rare situation.
Even if you use the plugin procedure above, the Tcl in your script option gets repeated twice on the page, and makes for ghastly looking webpage source. Also you can find ourself in quoting hell. Note that if you use the script attribute on a tcl template page (.tml file) the variables and subcommands inside [...] in the script will be substituted. To protect them on the .tml page use [set var $var] just ahead of the <embed> tag. And avoid using [...] within the script. If the script is of any size or complexity or is going to be used more than once, then put it in its own .tcl file and src it.
Tclets can invoke the [policy] command to request permission from the reader to access additional features.
Here is a rough guide to the Policies which a Tclet can ask to be allowed to use:
home - the most restrictive. The most restrictive. The Tclet can access resources on the host (server) machine.
inside - This policy allows access to resources on the intranet that the host is located on. (Not the intranet that the webpage is being viewed on, unless it is the same.)
javascript - This allows the Tclet to access anywhere on the web and send email. It has access to the HTTP features and the use of sockets.The tclet could operate as a little webserver, i.e. be a powerful program and potentially dangerous And yes, the implication is that javascript on a webpage is potentially dangerous, a good reason not to permit it on a site that is particular about its security. This policy is able to invoke javascript code.
outside - This is like the javascript policy , but without the javascript. Also it does not allow access to the hosts intranet, bur does allow acces to the rest of the internet. So for example it could be used to search the internet for particular webpages and display them.
trusted - No restrictioins. This is like running the full Tcl/Tk interpreter in the guests computer. Potentially very dangerous and should only be used in a closed shop.
There are additional policies that allow access to the guests computer, such as the tempfile policy. This policy is set up on the guests computer in the Plugin directories. It will probably be specially written to enable a specific application used within a company. It will limit file sizes and number of files that a Tclet can use, so as not to impact on the guests computer.
These additional policies are for the very advanced user writing a special applicatiopn for an intranet.
This and Tcl/Javascript are covered in the book "Web TCL Complete" by Steve Hall, McGraw-Hill. ISBN: 007913713X
