TeleFinder v5.6 - Active Page Scripting

Active Page Scripting - SPML - SSI

TeleFinder's Web Server allows users to create dynamic pages which can selectively provide information to clients on the fly, setup file downloading, manipulate forms data, perform custom logging and more.
Active Pages are created using TeleFinder's Server Parsed HTML (SPML) commands which includes the well-known NCSA/NetScape/Apache Server Side Include (SSI ) command set, plus a number of very powerful extended commands.

Samples

Sample pages can be found in Web Space/samples/. Command documentation is on the disk in the "Web Space/webdocs/" directory.

Active Page Performance Issues

SPML involves a small amount of parsing overhead, and should be used in place of Plug-In/CGI and external scripting systems whenever possible.
TeleFinder's file caching speeds up SPML performance by retaining the SPML source in memory where it can be quickly parsed.

Active Page Setup

TeleFinder has built-in recognition of the ".spml" and ".spm" file extensions and will parse them as Active Pages automatically. Other file types can be interpreted as Active Pages as well, see "Request Handlers" for more information on assigning a handler to a file type.
The default page may have a ".spml" or ".spm" file extension. The file type search order is ".spml", ".html", ".spm" and finally ".htm." These types are combined with the Server's Default Page name.
TeleFinder's error pages must have the ".spml" file type.

Active Page File Format

The document is parsed as an HTML document, with special commands embedded as comments. Commands are introduced by the pound sign (#) and followed by a list of named, or unnamed parameters.

or,

or simply a command by itself.

The total size of a command and its parameter list is limited to 8192 bytes.
Quoting is necessary for parameters that contain embedded spaces, tabs, returns or other control characters.
Commands and parameters are case-sensitive
Commands cannot be embedded within other commands, but commands can be embedded within an HTML tag.

Active Page Commands and Variables

These are the commands that you can use within Active Pages to add dynamic features to your web site.
#config
#flastmod
#fsize
#echo
#include
#count
#exec
#execonly
#log
#deltatime
#if, #ifnot, #else, #endif
#mailbody
#mailform
#mailargs
#dir_list
#topic_list_msg
#post_to_topic
#register

Each of the commands is explained in detail on the following pages.

Using #config

This command controls output formatting and the random number variable. The valid named parameters are: sizefmt, timefmt, logfmt, random, dir_domain, and dir_port.
The resutls of #config last for the lifetime of the request, and do not affect any other subsequent or concurrent requests.

sizefmt

The value sets the format used to display the size of a file. Valid values are bytes for a count in "bytes", or "abbrev" for a count in Kb or Mb as appropriate. The default is in abbreviated format. See also #fsize.
Example usage


timefmt

The value is a string to be used by the ANSI C strftime library routine when printing dates. The default format string is "%a, %B %d, %Y %I:%M %p". See also #flastmod, #echo DATE_LOCAL, #echo LAST_MODIFIED.
Format string parameters
%a - abbreviated weekday name
%A - full weekday name
%b - abbreviated month name
%B - full month name
%c - date and time in the form Mon Apr 15 13:25:31 1996
%d - day of the month as a number ( 01-31 ).
%H - hour as a number ( 00-23 , uses 24 hour clock )
%I - hour as a number ( 00-12 , uses 12 hour clock ) (uppercase i)
%j - day of the year as a number ( 001-366 )
%m - month as a number ( 01-12 )
%M - minute as a number ( 00-59 )
%p - AM/PM designation for a 12 hour clock
%S - second as a number ( 00-59 )
%U - week number of the year ( with Sunday as the first day of the first week ) as a number ( 00-53 )
%w - weekday as a number ( 0 (Sunday) - 6 ( Saturday ) )
%W - week number of the year ( with Monday as the first day of the first week )
as a number ( 00-53 )
%x - date the form Apr 15 1996
%X - time in the form 1:32:03.
%y - year without the century ( 00-99 )
%Y - year with the century as in 1996.
%Z - current time zone ( if available )
%% - prints %.
Example usage


logfmt

This lets you control formatting of log file entries created with TeleFinder's scripting. Valid parameters are nosep and tabsep.
The default is tabsep, which produces the standard tab delimited log files.
Example

Using the nosep option lets you create free form data in a log file; entries are not separated by Tabs, and lines are not terminated with "Returns."

random

This stores a random number in the RANDOM variable. Valid parameters are numeric lower and upper bounds. The lower bound is zero by default. All random numbers are nonnegative integers.
The default value is zero.
Examples

produces a number less than 20

produces a number between 10 and 19

dir_domain

The dir_domain can be set so that the "dir_list" command will
produce requests directed to a server other than the one generating the page.
By default, dir_domain is empty, and "dir_list" links will point to the serving computer.
Example

Produces links specifying "bbs.spiderisland.com"
http://bbs.spiderisland.com/Public%20Files/Macintosh/

dir_port

The dir_port can be set so that the "dir_list" command will produce requests directed to a different TCP-IP than the one receiving the request to generate the page.
The default dir_port is empty, and TeleFinder will create links with the port number unspecified.
Example

Produces links specifying Port 8080 like:
http://www.spiderisland.com:8080/Public%20Files/Macintosh/

Using #flastmod

#flastmod - echoes the date of last modification of a given file.
Example

produces the output: 4/16/96

Using #fsize

#fsize - gives size of file.
Example

produces the output: 13 Kb

Using #echo

#echo - echoes following variables to the browser:
DATE_LOCAL - local date and time
REFERER - page user came from.
ADDRESS - Client's TCP-IP address.
USER_NAME - The user's name if page is in "Realm."
FROM - "From" header if supplied by browser ( usually blank ).
LAST_MODIFIED - Last modified date and time of current page.
USER_AGENT - Browser name string.
SERVER_SOFTWARE - "TeleFinder v5.6"
SERVER_NAME - Domain name requested, or the name assigned to the server or thread.
SERVER_PROTOCOL - HTTP/1.0
SERVER_PORT - The TCP-IP port number the request was received on, 80 by default.
SERVER_STARTED - The date and time the server was booted.
SERVER_HITS - Total number of requests handled by the server since it was started.
COUNT - The recorded hit count for this page ( see #count command ).
RANDOM - The current random number value.
PARENT_DIRNAME - The name of the directory containing the requested file or directory.
DIRNAME - The name of the requested directory, or the name of the directory containing the requested file.
PARENT_LOCATION - The location of the page or directory's parent as provided in the URL.
LOCATION - The location of the page as provided in the URL.
DOCUMENT_NAME - The name of the requested page.
TIMESTAMP - The date and time in #log format.
HeaderName - The contents of any Request Header.
FormFieldName - The contents of any Form Field.
Example

This displays the pages "hit count" variable as text.

Using #include

#include - lets you include ( merge ) another document into the page. (This does for html what the <IMG SRC> tag does for images. )
Example

This merges the contents of sample.html in the page. Only files in the same directory or sub-directory of the page may be included.

Using #count

#count - increment ".cnt" file for the current page. TeleFinder stores the results in a file with the same name as the page, but using the ".cnt" extension. ( ie The count for homepage.spml is stored in homepage.cnt ).
Example

This increments the COUNT variable and stores it in the ".cnt" file. It does not display the variable.

Using #exec

#exec - run and display the results from a Plug-In or CGI. Nnote that the CGI must NOT include HTTP headers in its output.
Example

This runs the Spider Island Wisdom Plug-In to display a random quote from the "Slack" file.

Using #execonly

#execonly - run a Plug-In or CGI, but do not display its results.
Example

This runs the FrameServer CGI to capture an image and store it as "new.jpeg."

Using #log

#log (file=) - Write chosen variables to this pages log file, or to the file specified by the optional "file=" parameter. By default, TeleFinder stores the results in a file with the same name as the page, but using the ".log" extension. ( ie The log file for homepage.spml is stored in homepage.log ). Note that this command does not use the "var=" notation for parameters. The parameter list is simply a space separated list of variable names. The variable names may be enclosed in double quotation marks.
Any of these variables can be logged.
TIMESTAMP - The date TAB time.
ADDRESS - The clients TCP-IP address.
LOCATION - The location portion of the page URL.
BYTESSENT - Always 0 for webstat compatibility.
REFERER - The page linked from.
USER_AGENT - The browser name string.
RANDOM - The Random number.
REGISTER_ERR - The error string generated by the #register command.
HeaderName - The contents of any Request Header.
FormFieldName - The contents of any Form Field.
"" - Any character string.
TeleFinder can log the environment variables shown, Forms data, Strings, and Request headers. Forms and Header data is available using the case sensitive Header name, or Form field name. Strings are entered by surrounding the text with double quotes.
Example


Using #deltatime

#deltatime - Calculate and display time remaining until, or time elapsed since a given date requires 2 parameters. Note that this command does not use the "var=" notation for parameters. The parameter list is simply a space separated list of variable names. The variable names may be enclosed in double quotation marks.
param1 = date in format mm/dd ( timer loops again ) or mm/dd/yyyy.
param2 = output format ( Years, Days, Hours, Minutes, Seconds ) any combination of ymdhus
y - years
m - months ( 30.5 days )
h - hours
u - minutes
s - seconds
Example
 until Christmas!
Displays the current number of days until Christmas.

Using #if, #ifnot, #else, #endif

#if , #ifnot , #else, #endif - these let you conditionally execute script and send HTML. The commands if and ifnot require a full expression to evaluate. This expression is in the form:

or

The previous format is used to test the contents of Form Fields or Request Headers. You can nest if - endif and ifnot - endif blocks.
Theses are the tests you can make:

TRUE

Always run this block.

FALSE

Never run this block
example

never show this

always show this


COUNT

Test numbers against the page's hit count.
Parameters are any number
Operators are IS, GREATER_THAN or LESS_THAN
example

You are the 100th visitor and win a free trip to this URL....


DAYOFWEEK

Test the current day of the week against a list of day names.
Operands are SUN MON TUES WED THUR FRI SAT
Operator is IS
example

show this on Saturday and Sunday


TIMEOFDAY

Test the current hour of the day ( 24 hour clock ) against a list of hours.
Operands are 0 ... 23
Operator is IS
Example

show this at midnight and 1 am


MONTH

Test the current month against a list of month names.
Operands are JAN FEB MAR APR JUN JUL AUG SEP OCT NOV DEC
Operator is IS
Example

show this during December


DAYOFMONTH

Test the current day of the month ( 1 thru 31 ) against a list of dates.
Operands are 1 ... 31
Operator is IS
Example

show this at the 25th of any month


USER_AGENT

Make a case sensitive comparison of the browser string against a string.
Operand is a quoted string (ie: "Mozilla 1.0" )
Operators are IS or CONTAINS, use IS for an exact match; CONTAINS for sub-strings.
Example

show this to any version of NetScape only

show this to any other browser


ADDRESS

Test the user's address against a string.
Operand is a quoted IP address (ie: "199.35.3." )
Operators are IS, STARTSWITH or CONTAINS; use IS for an exact match, STARTSWITH for a sub-string match beginning with the first character, CONTAINS for a sub-string match beginning at any character.
Example

show this to clients in Spider Island's net


REFERER

Test the URL of the referring page against a string.
Operand is a quoted string (ie: "http://www.spiderisland" )
Operators are IS, STARTSWITH or CONTAINS; use IS for an exact match, STARTSWITH for a sub-string match beginning with the first character, CONTAINS for a sub-string match beginning at any character.
Example

show this to browsers linking from Spider Islands homepage


Using #mailargs, #mailbody

These commands let you process data from the Web as email. Like #echo and #log, the data sources can be the built-in environment variables, HTTP Headers and Forms Data. The #mailbody command has the additional capability of supporting the NetScape "File Upload" forms button.
Samples demonstrating the mail commands are found in /Samples/mail-forms/.
The mail commands are dependent upon using Mail Server and User Manager along with the Web Server. When a mail command runs, the Web Server spools the message into Mail Server's Mailbox as a MIME message in RFC822 format.

#mailargs

You can use this for page access notification and automatic "thank you" notes. The #mailargs command accepts a variable number of parameters to form the message headers and content. #mailargs works like the #log command, except that some params are used to address the message, and the rest create its content.
This sample uses the LOCATION and REFERER environment variables to automatically notify the site's Web Master about bad links.
Example:

The first is parameter the mailto address. It can be a string, or a variable from a form. If no domain name is provided in the address, mail server will deliver it to the local host.
The second is the mailfrom address. It can be a string, or a variable from a form. In this sample the return address is empty since its an error message from a web page.
The third is the subject of the message. It can be a string, or a variable from a form.
The fourth and subsequent parameters form the body of the message using the LOCATION and REFERER variables and other strings.

#mailbody

The #mailbody command is used to process the "multipart/form-data" generated when using the NetScape "file" input type in a form.
When using multipart/form-data TeleFinder cannot process individual Form fields as variables, so the #mailbody parameters need to come from strings , HTTP headers or the environment variables. The forms variables will show up in the content of the mail message as "Form Name=data."
#mailbody takes three (3) named parameters: addr, subj and from, to form the message's to address, subject and from address.
The #mailbody command must be in an Active Page that is the target of a Post command. Begin the form with a form tag as follows:
<FORM ACTION="upload.spml" METHOD="POST" ENCTYPE="multipart/form-data">
In the FORM's ACTION parameter substitute the name of your page for "upload.spml." The ENCTYPE and METHOD must be as shown here. The full sample can be found in /Samples/mail-forms/homepage.html and /Samples/mail-forms/upload.spml.
In the actual HTML form, you need to add the NetScape "file" input button.
<INPUT TYPE=FILE VALUE="Browse" NAME="attachment" >

NetScape's FILE Input Type only supports the "data fork" of Macintosh files so they must be converted into a data only file before uploading. Converting the file to BinHex format using Aladdin System's StuffIt Expander is a good way to convert Macintosh files to BinHex format.
DOS, Windows and UNIX files are all single fork, and do not need converting.
In the Form's Action page use the #mailbody command as shown here.

In this example the file attachment and forms data will be delivered to "sysop" at the local host. The Subject field will be filled in with the page's location. The From header of the message will contain "webserver."

Using #dir_list

The #dir_list command accepts a named parameter to indicate which directory to index, followed by a variable list of parameters to HTML for each item in that directory.
dir="" path to the directory to index. If the path is empty ("") the requested directory is indexed. Always use dir="" in the dir.spml Active Page.

For each item the following parameters generate HTML.
FILENAME - the text of the file name.
FILEHREF - a link to the file.
ICON - the icon ( gif ) of the file. TeleFinder uses the file "file extension".gif in the icons folder, so that "page.html" will be represented by the icon "html.gif."
FILESIZE - size of file in the format according to #fsize config.
LAST_MODIFIED - last mod date of the file in the format according to #flastmod config.
DESCRIPTION - the file's SitC description output as HTML.
"" -- any quoted text/html.
This sample will generate a basic list of links to the contents of a directory.

A more substantial example can be found in the "dir.spml" Template file.

Using #topic_list_msg

The #topic_list_msg command accepts a variety of parameters that display information in the message and can create links to specific messages.
When #topic_list_msg is run, is looks at the "which" and/or "msg_id" parameter passed in the request so that it can determine if it should display all messages, or a specific message in the topic.
The which parameter can be: which=all, to display links to all the messages in a topic.
The other "which" variations require an additional "msg_id" (Message ID) parameter. The Message ID is an internal reference number for TeleFinder, and is generated for you by the THIS_URL, NEXT_URL, and PREV_URL items.
If "which=this" then TeleFinder displays the message identified by the msg_id parameter.
If "which=next" then TeleFinder displays the message following the one identified by the msg_id parameter.
If "which=prev" then TeleFinder displays the message previous to the one identified by the msg_id parameter.

For each requested item, the following parameters generate HTML for a given message.
AUTHOR - The name or e-mail address of the person posting the message.
RECIPIENT - The name or e-mail address of the person the message was addressed to.
SUBJECT - The subject of the message.
POST_DATE - The date and time the message was posted.
PREV_URL - A link to the previous message in the topic.
NEXT_URL - A link to the next message in the topic.
THIS_URL - A link to the this message.
MSG_BODY - The body of the message.
MSG_NUMBER - The internal message number.
"" -- any quoted text/html.

This is the result of the topic_list_msg command in the "topic.spml" template file when displaying a single message.

Using #post_to_topic

The #post_to_topic command takes Forms data and posts it to a TeleFinder topic. The #post_to_topic command requires the poster's User Name, the To Address, Subject, and Content of the message to be posted.
TeleFinder uses the Authenticated User Name ( provided with password when entering a "Realm" ) if available, or input from a Form. The remaining data must be provided in a form.
Each of the Input Form's fields must be indentified with specific name tags:
User Name : 'name'
To Address : 'to'
Subject : 'subject'
Content : 'message'
These name tags are case sensitive. Please see the "topic.spml" Template file for an example of correct usage. The default posting form is shown below.

Using #register

The #register command creates an account in User Manager for a user. The #register command must be run in a page that is the Action of a Forms page. It requires two (2) form fields must be identified with specific name tags:
User Name: 'name'
Password: 'password'
The User Name must be at least three (3) characters, and less than thirty-two (32) characters long.
The Password must be at least three (3) characters, and less than ten (10) characters long.
After completion, #register sets the "REGISTER_ERR" environment variable to one of the following strings:
"OK" - the user was added.
"DUP_USER" - the user name is already in use.
"BAD_PASS" - the supplied password was too long or short.
"BAD_NAME" - the supplied name was too long or short.
"BAD_FORM" = the Registration form was missing required fields.
"NO_USER_MGR" - TeleFinder's User Manager is unavailable.
"BAD_CREATE" - an unknown error prevented the user from being added.
You can test and echo the REGISTER_ERR after the #register command runs, it is an empty string prior to that.