Server-Side Includes (SSI)

The server-side include (SSI) mechanism enables the Web server to make slight modifications to HTML documents before sending them to a requesting client. The changes the Web server makes are controlled by SSI commands that are embedded in the HTML document. For example, there are SSI commands that instruct the Web server to include another file in the HTML file or print information about the file. HTML documents that contain SSI commands must use the .SSI filename extension and must be stored in a directory that has the server-side include feature enabled.

To set up server-side includes you must

• Enable the server-side include mechanism for a directory
• Create server-side include documents

Creating Server-Side Include Documents

A server-side include (SSI) document is any HTML document that contains embedded SSI commands. All SSI documents must use the .SSI filename extension and must be stored in a directory in which SSI has been enabled. The default directory in which to store SSI documents is SYS:WEB\DOCS\SSI. To include an SSI command in an HTML document, you simply type the command into the document at the point where you want the server to execute the command. All SSI commands are case-sensitive and use the following general syntax:

<!--#command tag=“value”-->

The NetWare Web Server supports the following SSI commands:

• The include command instructs the Web server to include a specified file to the document.
• The echo command instructs the Web server to display information defined by a set of environment variables in the document.
• The flastmod command instructs the Web server to display the date on which a specific file was last modified in the document.
• The fsize command instructs the Web server to display the size of the file or another file in the document.
• The config command instructs the Web server how to display the last modified date or the file size information. This command is used in conjunction with the flastmod command or the fsize command.
• The append command instructs the Web server to append information to a specific text file.
• The count command instructs the Web server to print the number of times the document has been accessed.
• The if command instructs the Web server to perform an operation based on a condition.
• The goto command instructs the Web server to jump to a specific location in the document.
• The label command identifies the location to which an if...goto command or a goto command jumps.
• The break command truncates the document.
• The calc command performs mathematical calculations.

Enabling Server-Side Includes

To enable server-side includes for a specific directory

1. Start the administration utility.

2. Click File.

3. Click Select Server.

4. Select the \WEB directory on the drive that is mapped to the server and click OK.

5. Select the Directories tab.

6. Select the directory in which you want to enable server-side includes from the Existing directories list.

7. Check Enable includes.

8. Click Change.

9. Click OK.

10. Click Save and Restart.

include Command

Use the include command to insert an HTML or text document into the current document at the include command. You can only insert documents that are stored on the local server. The include command supports two tags:

• file, which allows you to identify the file to include using a path and filename that are relative to the current directory (the directory containing the SSI document)
• virtual, which allows you to identify the file to include using a path and filename that are relative to the document root (SYS:WEB/DOCS by default)

The include command uses the following syntax:

<!--#include file|virtual=“filename”-->

For example, to include the file /WEB/DOCS/SSI/NEWDOC.HTM in the file /WEB/DOCS/SSI/SSIDOC.SSI, type either of the following commands into the SSIDOC.SSI file:

<!--#include file=“newdoc.htm”-->
or
<!--#include virtual=“/ssi/newdoc.htm”-->

echo Command

Use the echo command to print information about the current document. For example, you can use the echo command to instruct the Web server to include the document’s name or last modification date in the document.

The echo command uses the following syntax:

<!--#echo var=“environment_variable”-->

The environment variable can be any of the following:

• DOCUMENT_NAME, which is the document’s filename.
• DOCUMENT_URI, which is the document’s Universal Resource Identifier (URI). This is equivalent to the pathname of the document.
• DATE_LOCAL, which is the current date and time.
• DATE_GMT, which is the current Greenwich Mean date and time.
• LAST_MODIFIED, which is the date and time the document was last modified.
• REMOTE_ADDR, which is the IP address of the client requesting the document.
• SERVER_SOFTWARE, which is the name and version of the Web server software.
• SERVER_NAME, which is the local hostname of the Web server.
• SERVER_PORT, which is the TCP port on which the Web server is listening for HTTP requests.
• REMOTE_HOST, which is the hostname of the requesting client.
• AUTH_TYPE, which is the method used to authenticate user requests.
• REMOTE_USER, which is the username of the client who sent the request.

For example, to include the current date and time in an HTML document, type the following in the HTML document:

The current date and time is <!--#echo var=“DATE_LOCAL”-->

flastmod Command

Use the flastmod command to include the date on which of the current file or another file was last modified in the current document.

The flastmod command supports two tags:

• file, which allows you to identify the file using a path relative to the current directory (the directory containing the SSI document)
• virtual, which allows you to identify the file using a path relative to the document root (/WEB/DOCS by default)

The flastmod command uses the following syntax:

<!--#flastmod file|virtual=“filename”-->

For example, to include the last modification date of the file /WEB/DOCS/SSI/STOCKQT.HTM in the /WEB/DOCS/SSI/SSIDOC.SSI, you could type either of the following commands into the SSIDOC.SSI file:

<!--#flastmod file=“stockqt.htm”-->
or
<!--#flastmod virtual=“/ssi/stockqt.htm”-->

By default, the last modification date is displayed using the standard date and time format (for example, Tuesday, 09-Jan-96 09:00:00 PDT). If you want to customize the date and time format, you can use the flastmod command in conjunction with the config command.

fsize Command

Use the fsize command to include the size of the current file or another file in the current document. The fsize command supports two tags:

• file, which allows you to identify the file using a path relative to the current directory (the directory containing the SSI document)
• virtual, which allows you to identify the file using a path relative to the document root (/WEB/DOCS by default)

The fsize command uses the following syntax:

<!--#fsize file|virtual=“filename”-->

For example, to include the size of the file /WEB/DOCS/SSI/BIGFILE.GIF in the /WEB/DOCS/SSI/SSIDOC.SSI, type either of the following commands into the SSIDOC.SSI file:

<!--#fsize file=“bigfile.gif”-->
or
<!--#fsize virtual=“/ssi/bigfile.gif”-->

By default, the file size is displayed in kilobytes. To display the file size in bytes, use the fsize command in conjunction with the config command.

config Command

Use the config command to change the format of the file size returned by the fsize command or the date and time returned by the flastmod command. You can also use the config command to customize the action the server takes when it encounters an SSI error.

The config command supports four tags:

• sizefmt, which changes the format of the file size returned by the fsize command.
  sizefmt can be “bytes,” which displays the file size in bytes or “abbrev,” which displays the file size in kilobytes (this is the default when the fsize command is used alone).
• timefmt, which sets the format of the last modification date returned by the flastmod command.
  timefmt is expressed using a series of formatting symbols called field descriptors. For example, the field descriptor %D is used to display the date in the MM/DD/YY format and %a is used to display the abbreviated weekday name. For a complete list of field descriptors, consult a good source on Web server administration, such as Serving the Web by Robert Jon Mudry (Coriolis Group Books).
• errmsg, which sets the error message returned when the server encounters an SSI error.
• onerr, which indicates what action the server takes when it encounters an SSI error.
  Possible actions are goto (jumps to a specific label command), print (prints specific text), error (prints the current errmsg string), break (terminates the HTML document), errorbreak (prints the current errmsg string and terminates the HTML document), and printbreak (prints specific text and terminates the HTML document).

For example, the following command changes the format of the file size and last modification date so that the file size is displayed in bytes, the date is displayed in the MM/DD/YY format, and the time is displayed in hours, minutes, and seconds AM or PM:

<!--#config sizefmt=“bytes” timefmt=“%D %r”-->

To set the SSI error message to “Sorry, we encountered an error while processing your document” and instruct the server to print this error message when it encounters an SSI error and then terminate the HTML document, type the following commands into the document:

<!--#config errmsg="Sorry, we encountered an error while processing your document"-->
<!--#config onerr=“errorbreak”-->

append Command

Use the append command to append information to a text file whenever a user requests a specific HTML document or submits an HTML form.

The append command supports two tags:

• file, which identifies the text file to which the data is appended
• line, which specifies what information is added to the text file

The append command uses the following syntax:

<!--#append file=“filename” line=“lines”-->

For example, suppose you have an HTML form that requests information about users who are interested in learning more about your products. When the user submits the form, you may want the information about the user to go into a sales database. The form requests the user’s last name, first name, address, city, state, zip code, phone number, and fax number. To append this information to the file salesdb.txt whenever the form is submitted, type the following command into the HTML form:

<!--#append file=“salesdb.txt” line=“&&Last&&, &&First&&, &&Addres&&, &&City&&, &&State&&, &&Zip&&, &&Phone&&, &&Fax&&”-->

count Command

Use the count command to display the number of times the current file has been accessed.

The count command supports one tag:

• file, which identifies what file the server will use to track the number of document hits. You can use any valid filename.

This command uses the following syntax:

<!--#count file=“filename”-->

The following example shows how to use the count command to display the number of hits:

<p>
You are number <!--#count file=“counter.txt”--> to access this document!
<br>

if Command

Use the if command to instruct the server to perform an operation based on the outcome of a logical comparison (for example, if this then do this).

The if command uses the following syntax:

<!--#if “operand1” operator “operand2” operation-->

operand1 is any string or number to which operand2 should be compared.

operator is the method that should be used to compare operand1 and operand2. Possible operators are == (equal to), != (not equal to), < (less than), > (greater than), >= (not less than), <= (not greater than), or contains (the text string in operand2 is found in the operand1 string).

operand2 is any string or number to which operand1 should be compared.

operation is the action the server should take when the comparison of operand1 and operand2 is true. Possible operations are:

• goto, which instructs the server to jump to a specific label command
• print, which instructs the server to print specific text
• error, which instructs the server to print the current errmsg string
• break, which instructs the server to truncate the HTML document
• errorbreak, which instructs the server to print the current errmsg string and then truncate the HTML document
• printbreak, which instructs the server to print specific text and then truncate the HTML document.

For example, the following if command instructs the server to jump to a specific line if the request came from an NCSA Mosaic browser. If the request did not come from an NCSA Mosaic browser, the server will jump to a different location in the HTML file.

<!--#if “&&HTTP_USER_AGENT&&” contains “Mosaic” goto mosaiclabel-->
<p>You are not using Mosaic.
<!--#goto “defaultlabel”-->
<!--#label “mosaiclabel”-->
<p>You are using Mosaic
<!--#label “defaultlabel”-->

goto Command

Use the goto command to jump to the point in the HTML document that is identified by a specific label command. When the server encounters a goto command, it jumps to the label command without executing any SSI commands or printing any HTML text between the goto command and the label command.

The goto command uses the following syntax:

<!--#goto “label”-->

For example, when the server encounters the following goto command in an HTML document, it jumps to the jumphere label without printing the line in between the goto and label commands:

<!--#goto “jumphere”-->
<p>This line will not print.
<!--#label “jumphere”-->
<p>This line will print.

label Command

Use the label command to mark the spot in the HTML document to which the server jumps when it encounters a goto command that identifies that label as the target.

The label command uses the following syntax:

<!--#label “labelname”-->

labelname is a string of 254 characters or less.

For example, when the server encounters the following goto command in an HTML document, it jumps to the jumphere label without printing the line in between the goto and label commands:

<!--#goto “jumphere”-->
<p>This line will not print.
<!--#label “jumphere”-->
<p>This line will print.

break Command

Use the break command to truncate an HTML document.

The break command uses the following syntax:

<!--#break -->

The following example illustrates the break command:

<p>This line will print.
<!--#break -->
<p>This line will not print because the document has been truncated and transmission to the client is terminated.

calc Command

Use the calc command to perform mathematical calculations.

The calc command uses the following syntax:

<!--#calc variablename1 = “value” -->
<!--#calc variablename2 = “value” -->
<!--#calc sum = “variablename1+variablename2” -->

The following operands are valid: +, *, -, /. Equations may contain parentheses to prioritize operations. The following example illustrates the calc command:

calc test:
<!--#calc number1=“1” -->
<!--#calc number2=“2” -->
<!--#calc number3=“3” -->
<!--#calc sum=“(number1+number2)*number3” -->
<p>The result is <!--#echo format “%8.2f” “sum”-->

The above example will print the following results:

The result is 9.00

Go to top of file or to the Novell NetWare Web Server Home Page.