Wiklet Server

A Tclet (Tcl Applet) is a Tcl script that is loaded by HTTP and executed in a safe Tcl interpreter in the Tcl Browser Plugin.

A Wiklet is a Tclet whose source code and means of execution are provided on a Wiki page. A Wiki page may have any number of independent Wiklets. This is a generalisation of the term 'Wiklet' as first used on the wiklets page by Brian Theado.

To see Wiklets in action, visit http://www.kerlin.net/22 which has the same Wiki-markup source as Wiklet Test Page

The Wiklet source is carried on a Wiki page as "pre-formatted" text. Wiklet source code is distinguished from other "pre-formatted" text by an initial line that is a Tcl comment, but that also contains an instruction to the server: a "Wiklet Instruction". Example Wiklet Instructions are:

 # For one of these lines to have effect as a Wiklet Instruction, it must be the first line of a pre-formatted block.
 # wiklet 1 200 300 embed
   # wiklet 1 200 300 embed
   # wiklet 2 150 150 embed
   # wiklet 2 150 150
   # wiklet 2
   # wiklet {1 3}

Rules for Wiklet Instructions

• A Wiklet Instruction can occur only as the first non-whitespace line of a block of pre-formatted text.
• A Wiklet Instruction begins with an arbitrary amount of whitespace, followed by '#', followed by a single space and the word 'wiklet'.
• If the first line of the pre-formatted text begins in any other way, it is not a Wiklet Instruction.
• The subsequent characters of a Wiklet Instruction are interpreted as a Tcl list which forms the arguments of the instruction.
• A block of pre-formatted text that begins with a Wiklet Instruction is a "Wiklet Block". A Wiklet Block contains Tcl source code.
• Each Wiklet on a page is identified by an integer. The source code for a Wiklet is the concatenation of all the Wiklet Blocks on that page that are labelled with that Wiklet's integer identifier.
• The first argument of the Wiklet Instruction is the integer identifier of the Wiklet to which the Wiklet Block belongs. Alternatively, this argument can be a list of integers - in this case, further arguments are ignored and the Wiklet Block belongs to each Wiklet whose identifier is in the list. This construct avoids the repetition on a Wiki page of code that is shared between multiple Wiklets.
• The second and third arguments, if present, are respectively the width and height in pixels of the Wiklet area.
• The fourth argument, if present, is 'embed', and indicates that the Wiklet should be embedded in the Wiki page above this Wiklet Block, when such embedding is enabled by the user.

Any Wiklet Block whose Wiklet Instruction includes the arguments for width and height will be displayed with an extra line inserted at the top, which is a Tcl comment with instructions and hyperlinks for using the Wiklet.

Embedding of Wiklets may be switched on or off by the user: it is off by default. The setting applies to the entire domain of the Wiki, and is controlled by a persistent cookie stored in the user's browser. The cookie is set and read by Javascript embedded in each Wiki page; its value is changed when the user clicks on an appropriate hyperlink. Although the cookie is sent to the server, the server neither uses, sets, nor stores its value.

If the page http://www.kerlin.net/22 has Wiklets with integer identifiers 1, 2, then these Wiklets have URLs http://www.kerlin.net/22.1.tcl , http://www.kerlin.net/22.2.tcl respectively.

The Wikit web server must be modified so that it

• (1) serves a Wiklet (instead of HTML) when it receives a request for the appropriate URL. The Wiklet is Tcl source and its Content-Type is 'application/x-tcl'.
• (2) adds extra code to the HTML Wiki pages, to enable access to the Wiklets. This code consists of the extra line with hyperlinks inserted at the start of certain Wiklet Blocks (see above), the code to embed Wiklets in the Wiki page, and code to manage a cookie.

An alpha version of Wikit with the necessary modifications is available from [L1 ]. The patch (against the starkit and CVS of Wikit at 2006-06-25 17:00 UTC, which at that time were identical) is at [L2 ]. The patch has been submitted to JCW to be considered for a future official release of Wikit.

Remarks on pre-formatted text

In HTML, "pre-formatted" text is surrounded by <pre> ... </pre> tags, and is displayed in this Wiki with a grey background.

In Wiki markup, lines that begin with three spaces, a marker, and another space are rendered in HTML as bulleted, numbered, or tagged lists, for markers '*', '1.' and 'tagname:' respectively. Any other line that begins with a space is rendered in HTML as pre-formatted, and the text displayed in a browser is identical to its Wiki markup (including the leading space), with these exceptions:

• trailing whitespace is removed from each line
• consecutive interior lines that are blank or consist only of whitespace are rendered in HTML as a single blank line
• leading and trailing lines that are blank or consist only of whitespace are not rendered in HTML
• if the pre-formatted block consists entirely of such lines, the block is not rendered in HTML

This mangling of whitespace might occasionally be significant in Tcl source code, e.g. if it occurs inside a quoted string. The whitespace is accurately preserved in the Wiki markup.

Initial design by KJN.

Please add suggestions for improvements here, particularly any changes needed to "Wiklet Instructions" for any cases that are not yet handled...

Brian Theado 26Jun2006 - Nice work! I like that multiple wiklets can be embedded into each page. I like the way the embedding can be dynamically enabled and disabled.

It would be fun to also have this functionality available in local mode wikit. The wiki-runner page contains a sandbox function that can be used to run a chunk of code in a safe interpreter environment very similar to the tclplugin environment.

It would be a little easier to read the code for a given wiklet if there were a link that when clicked displays all the code for that wiklet. Otherwise you have to search through the page and mentally figure out which code is involved. But maybe that adds too much clutter and maybe it should be up to the wiklet author to arrange things in a readable fashion.