Active Page Scripting

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

#comment

#count

#deltatime

#dir_list

#echo

#exec

#execonly

#flastmod

#fsize

#if, #ifnot, #else, #endif

#include

#log

#mailargs

#mailbody

#mailform

#post_to_topic

#register

#set

#topic_list_msg

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 #comment

#comment- lets you put a comment in the file that is not transmitted as part of the page to the browser.



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 #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 #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 #echo

#echo - echoes following variables to the browser:
ADDRESS - Client's TCP-IP address.

COUNT - The recorded hit count for this page ( see #count command ).

DATE_LOCAL - local date and time

DOCUMENT_NAME - The name of the requested page.

DIRNAME - The name of the requested directory, or the name of the directory containing the requested file.

FROM - "From" header if supplied by browser ( usually blank ).

FormFieldName - The contents of any Form Field.

HeaderName - The contents of any Request Header.

LOCATION - The location of the page as provided in the URL.

LAST_MODIFIED - Last modified date and time of current page.

PARENT_DIRNAME - The name of the directory containing the requested file or directory.

PARENT_LOCATION - The location of the page or directory's parent as provided in the URL.

PATH_ARGS - The contents of the CGI Path Arguments from the request.

RANDOM - The current random number value.

REFERER - page user came from.

SERVER_NAME - Domain name requested, or the name assigned to the server or thread.

SERVER_HITS - Total number of requests handled by the server since it was started.

SERVER_PORT - The TCP-IP port number the request was received on, 80 by default.

SERVER_PROTOCOL - HTTP/1.0

SERVER_SOFTWARE - "TeleFinder v5.5"

SERVER_STARTED - The date and time the server was booted.

TIMESTAMP - The date and time in #log format.

USER_AGENT - Browser name string.

USER_NAME - The user's name if page is in "Realm."

UserDefinedVariable - The contents of any yuser defined variable.

Example



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

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 #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 #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 #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.

ADDRESS - The clients TCP-IP address.

BYTESSENT - Always 0 for webstat compatibility.

FormFieldName - The contents of any Form Field.

HeaderName - The contents of any Request Header.

LOCATION - The location portion of the page URL.

PATH_ARGS - The path arguments

RANDOM - The Random number.

REFERER - The page linked from.

REGISTER_ERR - The error string generated by the #register command.

TIMESTAMP - The date TAB time.

USER_AGENT - The browser name string.

USER_NAME - The name of the user accessing the page. Valid only on pages within a Realm.

UserDefnedVariables - Any User defined variable. See

the #set command.

"" - 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 #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 tariables and tests you can use:

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



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....



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



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



DIRNAME

Test the contents the of the Directory name string against a string. Operators are IS or CONTAINS, use IS for an exact match; CONTAINS for sub-strings.

FALSE

Never run this block

example



never show this



always show this



FIELDS

Test the contents of two HTML Forms fields against each other. Operators are IS, GREATER_THAN or LESS_THAN . The strings are compared for equality using the ANSI strcmp library function.

example



Compares the contents of the two field names for case sensitive equality. See the BBS registration pages "reg.reg" to see how it can be used for checking a password.

FormsData

Test the contents the of any HTML Forms Data against a string. Operators are IS, STARTSWITH or CONTAINS, use IS for an exact match; CONTAINS for sub-strings. See also the #set command.

HTTPRequestHeader

Test the contents the of any HTTP Request Header against a string. Operators are IS, STARTSWITH or CONTAINS. Use IS for an exact match; CONTAINS for sub-strings. See also the #set command.

LOCATION

Test the contents the of the location of the page as provided in the URL. Operators are IS, STARTSWITH or CONTAINS. Use IS for an exact match; CONTAINS for sub-strings.

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



PARENT_DIRNAME

Test the contents the of the Parent Directory name string against a string. Operators are IS or CONTAINS, use IS for an exact match; CONTAINS for sub-strings.

REFERER

Test the URL of the referring page against a string.
Operand must be 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



REGISTER_ERR

Test the contents the of the Register Error string against a string. See also the #register command. Operators are IS or CONTAINS, use IS for an exact match; CONTAINS for sub-strings.

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



TRUE

Always run this block.

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



UserVariable

Test the contents the of any UserVariable string against a string. Operators are IS or CONTAINS, use IS for an exact match; CONTAINS for sub-strings. See also the #set command.

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 #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.

Using #set

You can use the #set command to over-ride the SPML values of Forms data, and the Request Headers. For example,if there is a forms field named "TEST_VAR" and you redefine TEST_VAR using the SPML set command, subsequent SPML will recognize the value defined by the #set command.

HTML and other data may be stored in a user variable for use in other SPML commands ( #echo, #if, and others ) that accept user variables. This sample creates a variable named "NEW_LINE" and sets it to the HTML break tag, followd by a Return.



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.