Procedure Descriptions

This section describes the VOV Tcl CGI procedures in more detail, describing the arguments and actions of each.

Note: The names of these procedures are mainly taken from the type of HTML tag which they implement, to make them easy to remember for persons familiar with HTML. Again, they are not HTML tags; each of the following is a Tcl procedure which takes zero or more arguments, so the script that you write using them must be in valid Tcl syntax.

Pay special attention to this for any parameter which is named args or script. See the description of the TABLE procedure and the example scripts for more information.

VOVHTML_START {}

Description
The VOVHTML_START procedure begins a new HTML page. It opens a temporary file to receive the text of the page. This procedure must be called before any of the following ones.
Arguments
None

VOVHTML_FINISH {[contentType HTMLtype]}

Description
The VOVHTML_FINISH procedure closes a HTML page. It writes the HTML header information, then the text which was stored in that page's temporary file, and removes the file.
This is the procedure which actually returns the page text.
Arguments
  1. content-type (optional); default is text/html

OUT {text}

Description
The OUT procedure adds the text of its argument to the page, without a newline.
Arguments
  1. text text to insert into the page

OUTLN {text}

Description
The OUT procedure adds the text of its argument to the page, with a newline.
Arguments
  1. text text to insert into the page

HTML {script}

Description
The HTML procedure builds the HTML section of the page, starting with the <html> tag, the text of the page, and then closes it properly with the </html> tag. It executes the Tcl script passed as its argument, and inserts the resulting text into the page.
Arguments
  1. script Tcl script that builds the HTML of a page

TITLE {title}

Description
The TITLE procedure inserts its text as the page title in the HEAD section of the page.
Arguments
  1. title text of page title

BODY {script}

Description
The BODY procedure executes the Tcl script, and inserts the text which the script returns as the page body in the BODY section.
Arguments
  1. script Tcl script that builds text to form the page body

COLOR {color text}

Description
The COLOR procedure surrounds its text argument with HTML code so that it will display using the named color.
Arguments
  1. color HTML color name or #code
  2. text text to be displayed in color

FONT {args}

Description
The FONT procedure surrounds its text argument with HTML code so that it will display using the named color. All except the last argument are taken as attributes of the FONT tag.
Arguments
  1. args text to be displayed in using the named font.

SPAN {args}

Description
The SPAN procedure defines a region of args to which a style rule may be applied.
Arguments
  1. args variable-length argument list.

FORM {args}

Description
The FORM procedure defines an HTML form for user interaction.
Arguments
  1. args attributes and Tcl script defining the form

SCRIPT {text}

Description
The SCRIPT procedure inserts its text as the code of a script into the current page. Typically, the code will be JavaScript.
Arguments
  1. text text to be inserted as script code

OPTIONS {args}

Description
Inserts an OPTION element into the current SELECT element. Must be used in the scope of a SELECT.
Arguments
  1. args variable-length argument list

SELECT {args}

Description
Inserts an SELECT element into the current FORM. Must be used in the scope of a FORM. The SELECT element forms a one-of-many choice using a drop-down list. Each item in the list is defined by an OPTION item.
Arguments
  1. args variable-length argument list

VOV_SET_COOKIE {name value [expires]}

Description
Store a cookie in the browser memory for future reference.
Arguments
  1. name the name of cookie to be stored
  2. value the value of cookie to be stored
  3. expires (optional) the expiration timestamp of the cookie. Without this argument, the cookie will survive the session, i.e., the cookie expires after all browser windows are closed.

VOV_GET_COOKIE {name}

Description
Retrive a cookie value.
Arguments
  1. name the name of cookie to retrieve
Returns
  1. value the value of the cookie retrieved or blank("") if no cookie with name name is found

TABLE {attributes} script

Description
Defines a table in the current HTML page. The table may contain nested TR, TH, and TD procedures.
The HTML <table> tag may have attributes such as cellspacing=0 border="1" , etc. between the <table part and the closing >.
Example:
 <TABLE ALIGN="CENTER" BORDER="1" { .... }
All items except the last one are taken as attributes. The final argument is evaluated as a Tcl script, and the resulting text is inserted into the page between the <table> and </table> tags.
Arguments
  1. attributes for the table, such as ALIGN="CENTER" BORDER="1" etc.
  2. script Tcl script that builds the rows of the table.
Returns
  1. value the value of the cookie retrieved or blank("") if no cookie with name name is found

TR {attributes} script

Description
The TR procedure defines a row in a table. It must appear in the scope of a TABLE procedure.
Example:
TR { ...script... }
TR BGCOLOR="white" { ...script... }
Arguments
  1. attributes optional attributes for the row (e.g. bgcolor)
  2. script Tcl script that builds the content of the rows.

TH {attributes} script

Description
The TH procedure defines a header cell in a table. It must appear in the scope of a TR procedure. The text of a table header cell is formatted bold and is centered in the cell.
Example:
TH { OUT "Ciao" }
TH VALIGN="top" BGCOLOR="white" { ...script... }
Arguments
  1. attributes optional attributes for the cell
  2. script Tcl script that builds the content of the header cell.

TD {attributes} script

Description
The TD procedure defines a table data cell in a table. It must appear in the scope of a TR procedure. The text of a table data cell is formatted plain and is usually aligned to the top left of the cell.
Example:
TD { OUT "Some data" }
TD VALIGN="right" BGCOLOR="red" { ...script... }
Arguments
  1. attributes optional attributes for the cell
  2. script Tcl script that builds the content of the cell.

HREF {url label}

Description
The HREF procedure defines a hyperlink in the current page.
Arguments
  1. url destination URL of the link
  2. label visible label of the link, which appears in the current page

BR {}

Description
The BR procedure begins a new line in the current page.
By default, HTML text in a page is flowed, rather than fixed-format. Without tags to define the structure of the document, its text will be flowed together to fit into the current window size whenever you change your browser window.
Arguments
None

HR {}

Description
The HR procedure inserts a horizontal rule (line) into the current page. The width of the line will vary as the window displaying the page is resized.
Arguments
None

Section Header Procedures

HTML defines six section header styles, ranging from H1 through H6, with H1 being the most emphatic (largest point size, and bold-face), and H6 being the least emphatic. VOV provides the corresponding H1 through H6 procedures.
H1 {script}
The H1 procedure evaluates its script as a Tcl script, and inserts the resulting text, surrounded by H1 tags, into the current page.
Arguments: script
H2 {script}
The H2 procedure formats its text using the Header2 style.
H3 {script}
The H3 procedure formats its text using the Header3 style.
H4 {script}
The H4 procedure formats its text using the Header4 style.
H5 {script}
The H5 procedure formats its text using the Header5 style.
H6 {script}
The H6 procedure formats its text using the Header6 style.

Other Formatting Procedures

VOV CGI also provides procedures to support other common formatting requests, including:
  • B display text boldface
  • EM display text emphasized
  • TT display text in TTY (fixed width) font
  • BIG display text in larger size
  • SMALL display text in smaller size
  • P start a new paragraph
  • OL start a ordered (numbered) list
  • UL start an unordered (bulleted) list
  • LI start a List Item in an ordered or unordered list
  • PRE start section of pre-formatted text (displayed in TTY font, not flowed)

The procedures described are defined in VOVDIR/tcl/vtcl/vovhtmlgen.tcl.