Web Utilities

decodeURL

encodeURL

insertCounter

redirectClient

removeCounter

resetCounter

setCounter

stripHTML

Response Headers

appendHeader

sendPartial

setExpiresDelay

setMIMEType

Session Utilities

authorizeClient

removeCookie

setCookie

File Upload

ulContentType

ulFileName

ulFileSize

ulFileStatus

ulSaveFile

Parameter	Description
encoded-string	any URL-encoded string

Returns the original item specified by encoded-string. The returned item may be any type, including a list if it was encoded using encodeURL().

This function is not necessary in most cases except when working with lists, as WebSiphon automatically decodes other types of encoded data instantiated using GET/POST arguments. In some earlier versions of WebSiphon list variables were automatically decoded as with other types of variable data, but this functionality was altered to prevent the potential of using this feature to launch a denial-of-service attack. Thus, it is necessary that list data be manually decoded before use as a list variable.

Example:

my_string = "A%20B%20C%20D";
print decodeURL(my_string);
>> A B C D

my_list = [1 2 3 4];
print decodeURL(encodeURL(my_list));
>> 1 2 3 4

See Also:

• encodeURL

Parameter	Description
item	an item of any type to encode

Returns a string containing the encoded contents of the item parameter which is suitable for use as a legal URL argument. If item is a list it will be encoded in a special manner which preserves the integrity of data within a list, including lists which contain sublists.

Example:

my_string = "A B C D";
print encodeURL(my_string);
>> A%20B%20C%20D

my_list = [1 2 3 4];
print encodeURL(my_list);
>> %5C[1%5C|2%5C|3%5C|4%5C]

See Also:

• decodeURL

Parameter	Description
counter-name	the counter name

Increments and returns the page counter counter-name. If the specified counter does not exist, it is created and a value of 1 will be returned.

Use this function to easily insert counters in your pages. Passing the built-in variable template_uri as the counter name will provide a unique name for any page on your site, so you can use it in a standard site footer include file to record counters for every page on your site served by WebSiphon.

Examples:

This page has been accessed {insertCounter(template_uri)} times.
>> This page has been accessed 24 times.

print insertCounter("My Home Page Counter");
>> 1

See Also:

• removeCounter
• resetCounter
• setCounter

Parameter	Description
location	a fully qualified URL

Immediately redirects the client to the URL specified in the location parameter. This function will cease further execution of the template.

Though some browsers will properly redirect with a relative URL, most do not. Use a fully qualified URL to ensure maximum browser compatibility.

Examples:

1. redirectClient("http://www.apple.com/");

2. site_list = ["http://www.purity.com/"
                "http://www.be.com/" 
                "http://www.manton.org/" 
                "http://www.starnine.com/" 
                "http://www.metrowerks.com/"];
   redirectClient(random(site_list));

Parameter	Description
counter-name	the exact counter name

Removes the page counter whose exact name is counter-name, and returns the value that it held.

Example:

print insertCounter(template_uri) & " ";
print removeCounter(template_uri);

>> 24 24

See Also:

• insertCounter
• resetCounter
• setCounter

Parameter	Description
counter-name	the exact counter name

Resets the value of the page counter whose exact name is counter-name to zero. If the specified counter does not exist, it is created and set to the value zero.

Example:

print insertCounter(template_uri) & " ";
resetCounter(template_uri);
print insertCounter(template_uri);

>> 24 0

See Also:

• insertCounter
• removeCounter
• setCounter

Parameter	Description
counter-name	the counter name
value	an integer value

Sets the page counter whose exact name is counter-name to the value specified. If the specified counter does not exist, it is created.

Example:

print insertCounter(template_uri) & " ";
setCounter(template_uri, 1000);
print insertCounter(template_uri);

>> 24 1001

See Also:

• insertCounter
• removeCounter
• resetCounter

Parameter	Description
html-text	any HTML text string

This function will strip all HTML tags from the text string passed in html-text. It will insert three carriage returns after the title of the document, two carriage returns for each paragraph tag, and a single carriage return for each line break tag. All other tags are ignored.

Parameter	Description
http-header	a standard HTTP header field/value string

Appends the string passed in http-header to the standard HTTP response header that WebSiphon includes with all returned results. A trailing CRLF will be added if you do not provide one in the string.

Example:

appendHeader("X-MyHeader: 12345");

This function sends the current HTML output back to the client, while the template is still executing. Using send partial allows you to improve the perceived server performance by breaking large portions of a returned page into smaller chunks that the client can view as each piece is returned.

Be careful not to use send partial too much, whereas the overhead of returning multiple chunks of a page actually outweights the perceived performance gain. There is no set rule as to how often to use send partial, so you may wish to try several different combinations to find the best match.

Hint: Call sendPartial() just before performing database queries to return the results page immediately, with the actual search results returned as they are completed.

Parameter	Description
delay-seconds	the expiration delay in seconds

Sets the expiration delay of the returned page, specified in seconds. The delay is added to the current time and used in the "Expires:" HTTP response header.

The default expiration delay WebSiphon uses for all templates is 0, indicating that the returned page should never be cached. You may set the global expiration delay by choosing "Preferences..." from the Edit menu availble in the WebSiphon application.

Example:

setExpiresDelay(1800); // the page will expire in 30 minutes

Parameter	Description
mime-type	any MIME type

Changes the MIME type of the returned document to the string specified in mime-type. Use this function when returning any item that is not "text/html", such as images or other binary files.

Examples:

1. setMIMEType("image/jpeg");  // a JPEG image file

2. setMIMEType("image/vasa");  // an MCF file

3. setMIMEType("text/plain");  // just plain text

Parameter	Description
realm-name	the security realm (displayed to the client)
[return-message]	message returned to client if login failed [optional]

When called, this function will return a standard authentication challenge to the client accessing the page, with the realm specified in realm-name. After the user provides a username and password, they will be available using the built-in variables username and password for verification purposes.

Depending on the browser being used to access your site, the username and password fields may or may not be case-sensitive. If you wish to ensure that the username and password are not case-sensitive, use the uppercase() or lowercase() functions prior to checking for access. The example shown below demonstrates this functionality.

The string passed in the return-message parameter will be returned to the client only if they do not to enter a valid username/password combination. If this optional parameter is not specified, the client will be returned the message, "Document contains no data" or possibly a blank page with some browsers.

Examples:

1. authorizeClient("secret-realm");

2. authorizeClient("downloads", "<html><body>Sorry!</body></html>");

3. if (uppercase(username) = "MYKUL" and 
       uppercase(password) = "CLAIRE") then
     print "You have access!";
   else
     authorizeClient("mykuls-realm", "Take off, hoser!");
   end if;

Parameter	Description
cookie-name	exact name of HTTP cookie
[domain]	exact domain name used to set HTTP cookie [optional]
[path]	exact path used to set HTTP cookie [optional]

This function will remove the defined HTTP cookie whose name is specified in cookie-name from the client's web browser. The domain and path parameters must match the values used when the cookie was originally created. If their values are not specified, the host name of the server and the path to the running template is used. If you did not specify these parameters when the cookie was set, you will not need to specify them for removal.

WebSiphon's implementation of HTTP cookie support conforms with Netscape's cookie specification at http://www.netscape.com/newsref/std/cookie_spec.html.

See Also:

• setCookie

Parameter	Description
cookie-name	name of HTTP cookie
cookie-value	value to store
[domain]	valid domain name [optional]
[path]	valid path [optional]
[expires]	formatted expiration date [optional]
[require-ssl]	only transmit securely? (true/false) [optional]

This function will define or modify a HTTP cookie whose name is cookie-name. The value stored by the cookie is specified in the cookie-value parameter and is encoded for you so you can safely store list values. Once a cookie has been defined it is available for use with each request as with other runtime session variables, such as GET or POST arguments.

If the optional domain or path parameters are provided, a web browser will only send the cookie to a URL that matches the specified values. If these parameters are not specified, the host name of the server and the path to the running template are used as default. In most cases you will not need to use the domain and path parameters at all, but may be helpful in some runtime scenarios.

The expires parameter designates an expiration date for the cookie which must be specified as an formatRFC1123() date, with the slight variation that the field delimiters within the date-portion of the string must be dashes rather than spaces. If this optional parameter is not specified, the cookie will only last for the user's current browsing session (ie. temporary; until they quit and relaunch their web browser).

Finally, if the require-ssl parameter is set to true, a web browser will only send the cookie if the connection is transmitted using SSL.

WebSiphon's implementation of HTTP cookie support conforms with Netscape's cookie specification posted at http://www.netscape.com/newsref/std/cookie_spec.html.

See Also:

• removeCookie

Examples:

1. // creates a cookie 'cname' whose value is "Grover"
   setCookie("cname", "Grover");

2. // as above, but expires tomorrow:
   // convert timestamp string to a list
   tlist = timeToList(now());
   // increment day field by one, and coerce back to a date string;
   // convert to specially-formatted RFC1123-style date
   tlist'3 = tlist'3 + 1;
   tomorrow = formatRFC1123CookieDate(listToTime(tlist));
   setCookie("cname", "Grover", null, null, tomorrow);

Parameter	Description
file-ref	reference name assigned to FILE entity in HTML form

When provided with a reference to an uploaded file, the MIME type of the file will be returned as a string.

Keep in mind that this is not necessarily the correct MIME type but only what was sent by the web browser. For instance, MSIE will send a MIME type of "text/plain" for any file whose name contained the "#" character or did not contain a suffix mapping, ie. ".gif", ".jpg" etc. In other words: You may not be able to rely on this value.

Parameter	Description
form-ref	reference name assigned to FILE entity in HTML form

When provided with a form-ref, the original file name as sent by the web browser will be returned. If the remote user agent is a Windows machines this is likely the full path to the file, ie. "C:\\some\path\file.gif". Generally Mac OS browsers will include only the filename itself.

Parameter	Description
form-ref	reference name assigned to FILE entity in HTML form

Returns the size of uploaded file form-ref in bytes.

Parameter	Description
form-ref	name attribute string assigned to FILE input entity in HTML form

This function is used to determine the status of an HTTP file upload in requests which include multipart/form-data.

When provided a form-ref which matches the name attribute of a file input entity included in the HTTP request, this function returns a result code which indicates the status of the received file upload.

Possible return values include:

-1		upload data was missing or form-ref invalid
0		upload data received OK
1		upload data was too large (exceeds WebSiphon global limit preference)
2		upload data was invalid

Example:

// if trouble, output file upload status to console
file_stat = ulFileStatus(import_data);
if (file_stat != 0) then
  case file_stat of
    (-1): err_msg = "upload missing";
       1: err_msg = "upload too large";
       2: err_msg = "upload was corrupt";
    otherwise: err_message = "unknown error";
  end case;
  appendLog(file_stat & ": " & err_msg);
end if;

Parameter	Description
form-ref	reference name assigned to FILE entity in HTML form
path	full-path to file destination
[new-filename]	new name for file [optional]

When processing a multi-part encoded POST with a file upload present, the field name you chose for the file upload will contain an ID. This is the ID you pass into 'id' so that WebSiphon knows what file you wish to work with. 'path' should be the path to a folder where you wish the file to be placed. If you include the optional 'new_filename' parameter, the file will be renamed to this (from its name as uploaded by the user)

Based on the ID value passed in with the file POST arg, allows saving of file to a permanent location.