WebSiphon 2 Guide: Getting Started
contents prev next

  1. Templates
  2. Built-in Variables
  3. WebSiphon Environment


WebSiphon uses standard HTML files as its basic document format - no changes are needed to process any HTML file. However, to gain access to the real power and flexibility WebSiphon offers, the SiphonScript scripting language may be embedded directly into a document using special token characters to designate which sections, or blocks, of the document are HTML and which sections are SiphonScript. We define any document which contains SiphonScript code, and possibly HTML, as a template file.

Now that we have defined what a template is lets take a sample HTML document and add a few items to transform it into a template that will serve a dynamic page when requested from a browser.

Here is an HTML document which we will use for our examples:

<HEAD><TITLE>WebSiphon Example</TITLE></HEAD>
<H1>WebSiphon Example</H1>
The current date is 11/21/00.
The current time is 12:43 AM.

Basic Syntax

Insertion Tokens
Obviously HTML example above does not produce anything special. Also the date and time will be wrong unless you hire a monkey to update the document every minute on the minute. So, we'll make this a dynamic document by adding a few of WebSiphon's built-in functions to insert the current date and time at the moment the page is served to a client. To do this, we use insertion token characters to insert the value of a variable or expression into the resulting HTML page. The insertion tokens are used in the HTML portion of a template, and begin with an open brace, "{", and end with a close brace, "}".

<HEAD><TITLE>WebSiphon Example</TITLE></HEAD>
<H1>WebSiphon Example</H1>
The current date is {currentDate()}.
The current time is {currentTime()}.
Your machine's IP address is {client_ip_address}!

Now, when a user requests our page the exact date will be inserted in place of {currentDate()} and the exact time in place of {currentTime()}. In addition, we added another line which will insert the IP address of the client accessing the page, ie. "Your machine's IP address is!". Notice that there is a subtle difference between this new dynamic insertion of an IP address and the date and time insertions. The reason for this is because currentDate() and currentTime() are function calls and client_ip_address is a built-in variable. In addition to client_ip_address, there is a listing of all built-in variables available for use within any template in the section below.

Optional Insertion Tokens
Obviously, the use of { and } as insertion tokens can be a major concern to someone using client-side JavaScript in their pages. The { and } characters in JavaScript code get interpreted on the server-side by WebSiphon and will end up causing syntax errors when you try to run the script.

Don't give up just yet. With WebSiphon 2.0.2, we've added an optional set of insertion tokens which addresses this situation. <?= and ?> are now synonymous with { and }. The optional escape sequences can be selected via the new #option directive (as shown below).

    #option sgml-escape
    << template_name: <?=template_name?> >>
    #option brace-escape
    << template_name: {template_name} >>

You can switch between the regular and optional insertion tokens anywhere in your template. The #option directive will stay in effect until it encounters another #option directive or until the end of the template. After the script executes, the #option directive reverts to the default state of using the { and } insertion tokens.

Now let's look at our example from above using the optional insertion tokens. You will notice this introduces the next section on block tokens (at the top of this example) where we need to escape from HTML mode and set the #option directive in SiphonScript.

#option sgml-escape
<HEAD><TITLE>WebSiphon Example</TITLE></HEAD>
<H1>WebSiphon Example</H1>
The current date is <?=currentDate()?>.
The current time is <?=currentTime()?>.
Your machine's IP address is <?=client_ip_address?>!

Block Tokens (escaping from HTML)
As we saw in the example above, when adding script code to your templates you use the other type of tokens WebSiphon recognizes, block token characters. Block tokens are used to escape from HTML and putting you in "SiphonScript code mode". The block tokens split a template into multiple sections, or blocks, of SiphonScript code and regular HTML. The block tokens look much like standard HTML tags, but instead of a single < or > character, two are used. To designate a block using these tokens, begin with "<<" and end the block with ">>". Alternatively, the Macintosh extended chevron characters may be used to designate blocks. The chevron symbols are yielded with the key combinations option-backslash, "<<", and shift-option-backslash, ">>".

Note: If you are using WebSiphon with a double-byte language environment such as the Kanji character set, the extended chevron character should not be used. Because of this, if you are developing templates that will be used on servers other than your own, you should not use the chevron character.

When using a double-byte language environment, you should uncheck the option in the WebSiphon Preferences for "Chevrons are Script"

  // WebSiphon Example Page
  if user_agent contains "MSIE" then
    the_browser = "Microsoft Internet Explorer";
  else if user_agent contains "Mozilla" then
    the_browser = "Netscape Navigator or Communicator";
    the_browser = user_agent;
  end if;
<HEAD><TITLE>WebSiphon Example</TITLE></HEAD>
<H1>WebSiphon Example</H1>
The current date is {currentDate()}.
The current time is {currentTime()}.
Your machine's IP address is {client_ip_address} and your 
browser is {the_browser}!

With the above changes made to our template, we are actually including a bit of SiphonScript that figures out if the client is using a Microsoft or Netscape browser and reports this to the user. Looking at the above example, the first line after the opening block token is a single-line comment. Comments are just a simple way to document your scripts, and they are ignored by WebSiphon when it processes the template. The next part of the SiphonScript block uses an if/then statement to figure out what type of browser the client is using based on the user_agent built-in variable. The user_agent variable is a small string sent by a browser identifying what it is. So if the browser's identification contains the string "MSIE" we define a new variable named the_browser and set its value to "Microsoft Internet Explorer". However, if the browser's indentification does not match, we check to see if it contains the string "Mozilla" and if it matches set the_browser to "Netscape Navigator or Communicator". Lastly, if we were unable to match either of these cases we will just use the identification string sent by the browser itself by setting the_browser to the value of the built-in variable user_agent.

With that completed, we close out the SiphonScript block and make a small change in the HTML to report what browser the client is using by utilizing the insertion token to insert the value of our the_browser variable in the resulting page.

So what about results? Here is an example of the output produced when requesting this template with the Netscape Navigator browser.

Netscape Example
Figure 1.1: Netscape Navigator example.

Built-in Variables

Built-in variables are a special kind of variable that WebSiphon automatically creates for you each time a template is requested.

One common mistake among those new to the WebSiphon environment is to accidentally create variables with the same name as those listed in this section. Obviously, this can create unexpected results and should be avoided. In particular, note that username and password are both CGI parameters and should not be used as variable names within your scripts.

CGI Parameters

These variables are sent from the web server and contain connection-specific parameters, such as the HTTP method used, the client's IP address, and so forth.

script_nameURL name of this template/script
action_namethe action name
action_paththe action path
path_argumentsarguments to the URL after a $
search_argumentsarguments to the URL after a ?
post_argumentsactual form data from a POST
full_client_requestfull HTTP request sent by the client
http_methodGET, POST, etc.
http_versionversion of HTTP used by browser
usernameauthenticated username
passwordauthenticated password
from_usere-mail address of remote user (obsolete)
client_addressIP address or domain name of remote client
client_ip_addressIP address of remote client
cgi_host_nameHost as defined in the client request
server_nameIP address or domain name of server
server_portTCP/IP port number being used by server
content_typeMIME content type of post_arguments
refererthe URL of the page referencing this template
user_agentname and version of the remote client software
cgi_connection_idunique ID used by the web server to identify the TCP/IP connection
user_agent_osclient OS - not all browsers send this value
user_agent_cpuclient CPU type - not all browsers send this value
connection_typefrom full HTTP request
client_acceptfrom full HTTP request
client_accept_languagefrom full HTTP request
client_accept_encodingfrom full HTTP request


This group of variables contains file information about the currently running template and the web site. You can use them to make a template work regardless of its name or location in the site.

site_pathThe full path of the folder containing the web site.
template_nameThe name of the template file being executed.
template_mod_dateThe modification date of the template being executed.
template_mod_date_secsThe modification date of the template being executed as the number of seconds since January 1, 1904.
template_pathThe full path of the folder containing the current template.


size = getImageSize(template_path & "big-icon.gif");

log_message = "\r" & username & " at " & now();
appendFile(template_path & "my_log.log", log_message);
template_uriThe URI of the currently executing template.
__context__The execution context of the currently executing template. The value can be one of "STARTUP", "SCHEDULER", "CGI", or "RUN_FUNCTION".
__instance_id__A unique ID for each instance

Error Information

These variables are available when using try/catch statements.

siphon_error_messageThe textual message returned for an error
siphon_error_numberThe numerical error
siphon_error_source_fileThe source file producing the error
siphon_error_file_pathThe path to the error producing file
siphon_error_line_numberThe line number of the error
siphon_error_uriThe URI that produced the error
siphon_error_full_requestThe full headers of the request that produced the error

Note: some of these error variables may not be set, depending on the type of error.


This group of variables contains information specific to the WebSiphon application itself.

siphon_prefs_error_fileThe name of the file served for invalid URL requests.
siphon_prefs_index_fileThe name of the file served when a URL points at a directory.
siphon_prefs_no_access_fileThe name of the file served for denied security URLs.
siphon_osOperating System version.
siphon_versionWebSiphon version.
siphon_sapiWebSiphon API version.

Support directories

This group of variables contains information about WebSiphon application support files and folder paths.

siphon_data_pathThe full path to the "WebSiphon Data" folder.
siphon_startup_pathThe full path to the "Startup" folder.
siphon_templates_pathThe full path to the "Templates" folder.
siphon_libraries_pathThe full path to the "Libraries" folder.
siphon_lib_data_pathThe full path to the "Library Data" folder.
WebSiphon Environment

Now that you know how to create templates that serve dynamic pages or web-applications using WebSiphon, we'll turn our attention to the WebSiphon application environment itself. Since WebSiphon is a server application, its interface is very limited but there are a few items of interest you should know about.

Log Window

WebSiphon Log Window
Figure 1.2: WebSiphon Log Window

WebSiphon's main log file records each time WebSiphon is launched or quit, and depending on your preferences it will log each template served. In addition, any custom logging you have designated using the built-in function appendLog() will appear in this window.

Status Window

WebSiphon Status Window
Figure 1.3: WebSiphon Status Window

As WebSiphon receives requests, the status window displays what templates are currently being processed and served. Each item in this window represents a thread, or template execution, that is occuring at any particular moment. In the above image, only one template is currently executing, "/helloworld.t". The top row in this window displays a few statistics (from left to right): the total number of pages served, total number of invalid URLs received, and the total number of errors which have occured while a template was executing (runtime errors). The last item shows the total number of bytes WebSiphon has served.

Inspector Window

Thread Inspector Window
Figure 1.4: Thread Inspector Window

When a thread is executing, clicking on the thread name in the Status window will open up the Inspector. Processing of the thread is paused when you open the Inspector. Several bits of information about the template execution is shown, including the current line number and the section of script code around that line. This is very helpful when debugging troublesome problems such as infinite loops or semaphore deadlocks. Clicking on the "Stop Execution" button will abort execution of the thread. Clicking the "Resume Execution" button will continue running the script. The lower portion of the window will show the script content as it is executed. If you simply close the insepctor window the thread will continue processing.

contents prev next

Copyright (c)1996-2003 Purity Software