NeoWebScript is both a web server and 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 Common Gateway Interface (CGI) programs and customizable server-side include (SSI) functions 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 platforms are supported for NeoWebScript?
A. It will run on most UNIX systems, and has already been successfully built on FreeBSD, Linux, and Sun Solaris.
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. This release is built on Tcl 8.0.3, and is not guaranteed to work with older versions.
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 interpreter 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 from the safe interpreter. These commands are available in the trusted master interpreter, and there are mechanisms to access these them from the safe interpreter. Still, we recommend that proper SafeInit entry points should be written for the packages.
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 SSIs 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 container tag of <nws>
is used to trigger
NeoWebScript execution, with it's ending tag of
</nws>
ending execution. Unlike HTML, these tags are case
sensitive, so <NWS>
or <Nws>
will not
work. The previous way of starting code execution, an insertion tag patterned
after the special comment type used by the NCSA server to activate SSIs,
is still available, and will be examined in the next section.
Let's look at a simple webpage:
<! Sample NeoWebScript Webpage --> <html> <head> <title>Sample NeoWebScript Webpage</title> </head> <body> <h1>Sample NeoWebScript-tm Webpage</h1> This is a sample webpage containing embedded NeoWebScript-tm directives. <P> The current server time is <nws> html [clock format [clock seconds]] </nws> <P> Thanks for visiting! </body> </html>
...NeoWebScript code goes here...
</nws><nws>
ends the embedded code. Normal HTML output resumes.
In this example, the code tells the server to:
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.
NCSA-styled SSI comments vs. NeoWebScript Tags
The <nws>
container tag was introduced in
NeoWebScript 2.1. Prior to that, NeoWebScript used
insertion tags modeled on the NCSA-styled SSIs. These tags all still work for
complete backwards compatability. Although there are two serious problems with
how Apache processes these NCSA style tags, there is a property that may be an
advantage in some circumstances.
The insertion tags can start with any of these three ways. They are all do the same thing, and are completely interchangeable.
<!--#nws
tags -->
<!--#neowebscript
tags -->
<!--#neoscript
tags -->
tags is of the form tag='value'.
The tag specifies how NeoWebScript is to handle value, where value is the
NeoWebScript commands enclosed in apostrophies. eval is the most
commonly used tag, causing the server to evaluate the specified code in the
same fashion as the current <nws>
container.
<--#nws eval='
html [clock format [clock seconds]]
'-->
is exactly equivalent to
<nws>html [clock format [clock seconds]]</nws>
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 <!--#nws return='clock format [clock seconds]' -->
The main problem with SSIs is automatic decoding of HTML entities or numeric
character references prior to execution of the code. 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.
This leads directly into the second major problem, that apostrophes (') must
not appear anywhere within the code. Since apostrophes act as the stard/end
delimiters of your NeoWebScript; any apostrophe within your code
would prematurely mark the end of your code, often resulting in an error from
the NeoWebScript interpreter. There was no escape code (e.g.
\'
) to disable this behavior; and because of the automatic
decoding problem, the SGML entity '
for the apostrophe
would cause the same error. Only &#39;
could generate an
apostrophe for output.
However, the possible advantage is that SSIs are treated as HTML comments by
web browsers and HTML editors alike. If you view the page locally, or through
a non-NeoWebScript server, the contained NeoWebScript
code will not appear on the web page. The code will only be visible by
selecting an option to view the HTML source. On the other hand, the
<nws>
container tag will be treated as an unknown tag.
The exact behavior varies between applications, but most will simply ignore
unknown container tags while displaying all the text contained within
(i.e. the code), and thus any real HTML tags would take effect.
Q. Configuration for Dynamic Image Generation
A. In order to generate images (GIF) files dynamically, the neo-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 .gdIt 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.