NeoWebScript™ Sysop FAQ

NeoWebScript™ is a programming language that allows both simple and complex programs to be embedded into HTML files.

When an HTML page containing embedded NeoWebScript™ is requested, the webserver executes the embedded script(s), producing a webpage containing customized content created by the program.

NeoWebScript™ programs can make pieces of webpages based on user input, information in the environment, the time and date, data read from disk, and so forth.

NeoWebScripts™ execute in a safe Tcl interpreter, a restricted environment that prevents NeoWebScript™ programs from doing malicious things like running arbitrary commands, deleting files, etc, and thus provides an excellent way for webmasters to allow their users to write CGI and server-side include programs on their webservers, without incurring the risk that the users will, either acidentally or on purpose, allow the system to be subverted by outsiders.

In addition to the command set provided by Safe Tcl, several new commands and variablaes have been added to provide the HTML/NeoWebScript™ author with a number of simple, application-oriented webpage services.

Q. What hardware do I need to run a NeoWebScript™-enabled webserver?

A. You need a UNIX or UNIX-like system, like a Sun, SGI, HP, DEC, etc. Linux and FreeBSD work fine, too.

Q. Why are you doing this?

A1. It worked for Netscape.

A2. Metcalfe's law applies to networks of people, too.

A3. "Gaston, let's make stone soup."

A4. Computers are fun.

Q. What versions of Tcl will this work with?

A. Tcl7.5 or tcl7.6. We have also operated with Itcl2.1 and Itcl2.2's versions of Tcl7.5 and tcl7.6. We have not tried Tcl8 yet, but it should be good.

Q. What Tcl packages can I include in the server?

A. Most any package you want. If you want to load the package into the safe interpreter, it should provide a SafeInit entry point. The author's preference is to staticly load most needed packages into the daemon and load them into the safe interp specifying an empty argument for the package filename. Many packages are pretty safe and are just missing the SafeInit entry point. Sometimes you also find that commands are excluded

Q. How are NeoWebScripts invoked?

A. NeoWebScripts™ are embedded directly into HTML files.

When a NeoWebScript™-enabled webserver retrieves a page in response to an HTTP request, if the webpage meets the criteria for execution of embedded NeoWebScripts™, any NeoWebScripts™ that are present in the webpage are executed sequentially as the webpage is transmitted, and the results of those script executions create some of the contents of the webpage "on the fly" as is served out.

By default, HTML files are NeoWebScript™-enabled if you allow server-side includes for that file. (This behavior can be overridden, or other extensions also set up to trigger NeoWebScript™ execution using the AddType directive within the webserver configuration file, or via the mime.types file.)

The file can contain all of the usual sort of text and HTML directives.

A special comment type, patterned after the special comment type used to activate server-side includes, is used to trigger NeoWebScript™ execution.

Let's look at a simple webpage:


<! Sample NeoWebScript™ Webpage -->

<title>Sample NeoWebScript Webpage</title>
<h1>Sample NeoWebScript-tm Webpage</h1>

This is a sample webpage containing 
embedded NeoWebScript-tm directives.
<P>
The current server time is 
<!--#neoscript eval='
html [clock format [clock seconds]]
' -->
<P>
Thanks for visiting!

In the above example, the embedded NeoWebScript™ directive begins with

<!--#neoscript

...followed by one or more tags of the form tag=value.

The eval tag causes the specified code to be evaluated as a NeoWebScript™. The script can then make calls to html to emit HTML. In this case, it says format the current time into a human readable time (clock format). For the clock value, use the current system time (clock seconds).

Other NeoWebScript™ Tags

In addition to the eval tag, a number of other tags are available:

The code tag is equivalent to the eval tag. There is absolutely no difference in functionality between the two tags.

The var tag says that its corresponding value is the name of a global variable or element within a global array in the NeoWebScript™ interpreter. In this case, the value is fetched and emitted into the HTML being sent to the user.

The expr tag causes its value to be evaluated as a NeoWebScript™ expression. The result of the expression is emitted into the HTML page that's being transmitted.

The return tag causes its value to be evaluated as a NeoWebScript™ expression. The result of the expression is emitted into the HTML page that's being transmitted. So the example above could be simplified into:

The current server time is <!--#neoscript 
return='clock format [clock seconds]' -->
Any number of NeoWebScript™ calls can be embedded into a webpage, and multiple tags may be present in any call. Execution of the NeoWebScript™ calls in a webpage proceeds in order from top to bottom, and evaluation of multiple tags within an embedded NeoWebScript™ call proceeds from left to right. State is retained throughout the execution of NeoWebScript™ in constructing the page, so, for example, global variables and procedures defined in the first part are accessible from the latter ones. Of course, all this information is discarded once the page has been sent.

New NeoWebScript™ Server-Side Tag!

new sequence:is equivalent to:
<nws><!--#neoscript code='
</nws>'-->

In addition, the new tags do not perform automatic decoding of HTML entities or numeric character references. The automatic decoding is part of Apache's default behavior for processing server-side include directives, and forces ugly hacks to "double-encode" HTML entities and numeric character references so that the content may safely pass through the server and then through the client.

The restriction of not using apostrophes (') is also removed thanks to the new tags. Previously, apostrophes were reserved as the absolute delimiters marking the start/end of your NeoWebScript™; any apostrophe within your code would prematurely mark the end of your code, often resulting in an error within the NeoWebScript™ interpreter.

Caveat: the new sequences must be completely lowercase; uppercase such as <NWS>...</NWS> will not be recognized by the server.

Q. Configuration for Dynamic Image Generation

A. In order to generate images (GIF) files dynamically, the generate-image handler must be enabled in srm.conf. After you uncomment the handler lines, they will appear as follows:

	AddType image/gif .gd
	AddHandler generate-image .gd
It is, of course, up to the webmaster exactly which extension to use. The implementation is generic enough that, if you have a Tcl extention for generating other kinds of image formats (eg. JPEG), the code could easily be modified to support it. Also, make sure mod_neoscript.o replaces the regular includes module when the webserver program is compiled.