Jan's Guide to Web Authoring: Server Side Includes

Server Side Includes (SSI) is exactly what the name tells you it is, order the server to include or add information to an HTML document. Includes take the form of:

Whether or not you can use SSI on your site depends on your provider. Ask your favourite support person if you can use SSI, what server software is used and if there are any special techniques, conditions or rules. For example, on my site I can only use SSI in files that have an .shtml extension instead of the normal .html one. You also have to ask what path to files to use.

Unfortunately, not all includes explained here work for all servers. For example, the #hide and #show includes are specific to WebStar. With Apache server software, you can achieve the same things by using #if and #endif.

Changing The Time Format

Before starting to use server side includes, you need to configure a number of things. For starters, choose a format for date and time you like (the #echo command is explained later in this chapter).

Below is a table of many of the options you can use. You can also include things like colons, commas and slashes as well as bits of text and HTML. You can mix the elements below at will.

The last format you have set will remain valid throughout the rest of the page. However, unless you want to use the default format (which usually is something like 98/07/12:16:45:34) you will have to set your favourite time format in every page that uses server side includes that have to do with time.

Changing The Size Format

The #fsize include is explained later in this chapter. You can see that the "bytes" option gives the size in full in bytes, the "abbrev" option gives the size in kilobytes.

Customize Error Messages

You can change the default error message to anything you want. Here is an example of changing the error message and then trying to include the non-existent file "nosuchfile.html":

There is only one error message available. However, you can change the error message more than once in a single html file:

Sorry, an error occurred including nosuchfile.html. Please mail your complaints to [email protected]

Sorry, an error occurred including nosuchfileagain.html. Please mail your complaints to [email protected]

Specifying your own error messages will make it easier for you to spot and solve problems. If you want to use more than one error message, you have to make sure that you change the error message before the command it refers to.

Including Files

The include command allows you to dynamically insert other HTML files into the current HTML file. Use it like this:

What path to use, again, depends on your provider. Normally it will be a path that is local to the server, so it will not include http://etc. The most sensible use of this command is to take standard bits of your pages such as headers and footer and put them in a separate file. On all of your pages you use the include command to include that file. That way, in order to change the footer on all pages, you only need to change one file. For example, you could make a simple text file that contains:

<P ALIGN="center">Copyright 1998 Tom, Dick and Harry<BR>
Please mail us at [email protected]</P

You save this file as ssifooter.html and include it in your other files by using:

The files you include can be plain text files or can include HTML. You don't need to give them <HEAD> and <BODY> tags, just put in whatever you want to insert. In these files you can use whatever HTML you want and you can make links, etc.

Hide And Show

With the Hide and Show commands you can avoid that your reader sees certain parts of the document:

<P>Now you see me,  This text is not shown.  now you don't.</P

Show and Hide can be used to temporary exclude parts of your document. Hide and Show only work under WebStar, so I cannot show you an example here.

Hide And Show By Time

The next example shows how to display bits of HTML only after certain days. Comparisons like this always use the default time format of 1998/07/24:17:34:45 no matter what you have done with the timefmt option.

This text is shown after 30 June 1998.




This text is shown after 30 June 1999.

Or you can show and hide things on specific days using a combination of 'hide after' and 'show after':

This text is shown on 12 July 1998.




This text is shown on 13 July 1998.




This text is shown on 14 July 1998.

As you can see, you do not have to specify a full date and time but only what is relevant for you. If you would want to show something during 1998 you could use: during="1998".

Hide And Show By Browser

Here is an example of how to show a bit of text only to a user of Netscape's Navigator:

Welcome Netscape Navigator user!




Welcome Internet Explorer user!

As you can see in this example, the output of Webstar is by default on. That's why you start any of these examples by switching the output of (#hide) and then switching it on again if the appropriate condition is fulfilled. At the end of the example you switch the output on again with a #show include. Again, show and hide do not work under Apache so I cannot show you the result here.

Hide And Show At Random

Heads


Tails

If you do a couple of reloads, you should see the text change. Of course you can use the same thing to show and hide images or any other HTML. The number that is used by Webstar is a random number ranging from 1 to 99 inclusive. Here is an example for three random texts:

To be or not to be,



that's the question,


my dear Watson.

More Hide And Show

In fact you can show and hide text at will using any of the environment variables (see the section on Echo below). This example shows a bit of text to a user with IP address 195.99.40.125:

Welcome BTinternet user!

If you have friends with fixed IP addresses you can leave messages especially for them in the same manner. Finally, you should know which operators are available:

If And Endif

Because this server runs Apache I could not show the examples of #hide and #show. I can, however, demonstrate the #if and #endif includes (if and endif, in turn, do not work under Apache):

Hang in there, it's almost weekend

Have a nice weekend

Have a good day

The first thing you will notice is that the #if include, opposite to the #hide and #show, does use the date as formatted with timefmt. This has some clear advantages. You can also see that this example is a bit easier to understand the #show and #hide spaghetti that WebStar seems to need. Note that the #if and #endif are obligatory, the #elif and #else are optional. This example uses date_gmt which is London time -ignoring summertime- rather than date_local which depends on where the server is.

If, Endif And Environment Variables

you can use the #if include to show different information to different browsers. Each browser sets the environment variable http_user_agent differently. This is how Netscape Navigator 4.04, Microsoft Internet Exploder and Apple's Cyberdog respectively do it:

Mozilla/4.04 (Macintosh; I; PPC, Nav)
Mozilla/4.0 (compatible; MSIE 4.0; Mac_PowerPC)
Cyberdog/2.0 (Macintosh; PPC)

As you can see these are all the Macintosh versions. By the way, this is what your own browser makes of http_user_agent: Wget/1.8.2. So this is how to show different information to different browsers:

Fight the Microsoft Monopoly. Get Netscape!

Welcome Netscape Navigator user!

Welcome Apple Cyberdog user!

Welcome! So what browser are you using?

Note that the /Nav/ I am looking for here is produced by Netscape Navigator, which is Communicator without the news, mail and webeditor modules. The above is obviously not an exhaustive list of browsers, which is why there is also an #else include for all the browsers that are not covered.

The two slashes around MSIE, Nav and Cyberdog in the example above means that the second string is interpreted as a regular expression, commonly used under Unix. In this case it checks if http_user_agent contains that string.

Set

The #set include can be used to create your own variables and assign them a value. Variables can be printed or can be used in #if statements:

<BR>

That's a jolly nice car

The $ sign in the #if include is needed to ensure that "carmodel" is interpreted as a variable, not as a string.

Echo

ECHO can be used to insert information from the browser and the server into your document, the so-called environment variables. The following possibilities are available:

Document Name: 
Document URI: 
Local Date: 
GMT Date: 
Last Modified: 
Server Software: 
Server Name: 
Server Protocol: 
Server Port: 
Gateway Interface: 
Request Method: 
Script Name: 
Remote Host: 
Remote Address: 
Remote User: 
Content Type: 
Content Length: 
HTTP Accept: 
HTTP User Agent (Browser): 
HTTP Cookie: 
Unescaped query string: 
Query String: 
Path Info: 
Path Translated: 
Referer: 
Forwarded:

Document Name: ssi.shtml
Document URI: /guide/ssi.shtml
Local Date: Tuesday, 06 August 2002 at 08:59
GMT Date: Tuesday, 06 August 2002 at 06:59
Last Modified: Thursday, 01 August 2002 at 12:03
Server Software: Apache/1.3.20 Sun Cobalt (Unix) mod_ssl/2.8.4 OpenSSL/0.9.6b PHP/4.1.2 mod_auth_pam_external/0.1 FrontPage/4.0.4.3 Chili!Soft-ASP/3.6.2 mod_perl/1.25
Server Name: www.weijers.net
Server Protocol: HTTP/1.0
Server Port: 80
Gateway Interface: CGI/1.1
Request Method: GET
Script Name: /guide/ssi.shtml
Remote Host: (none)
Remote Address: 194.84.119.126
Remote User: (none)
Content Type: (none)
Content Length: (none)
HTTP Accept: */*
HTTP User Agent (Browser): Wget/1.8.2
HTTP Cookie: (none)
Unescaped query string: (none)
Query String:
Path Info: (none)
Path Translated: (none)
Referer: (none)
Forwarded: (none)

Not all ECHO commands always result in information being printed. This can depend on the server, on your browser and on the way you reached this page. The #echo include works both under WebStar and Apache.

Print Environment

If you want to print the entire environment, you do not need to use a whole list of #echo includes. Instead you can use this shortcut.


DOCUMENT_ROOT=/home/sites/site147/web
HTTP_ACCEPT=*/*
HTTP_CONNECTION=Keep-Alive
HTTP_HOST=www.weijers.net
HTTP_REFERER=http://www.weijers.net/guide/
HTTP_USER_AGENT=Wget/1.8.2
PATH=/sbin:/usr/sbin:/bin:/usr/bin:/usr/X11R6/bin
REMOTE_ADDR=194.84.119.126
REMOTE_PORT=1198
SCRIPT_FILENAME=/home/sites/site147/web/guide/ssi.shtml
SCRIPT_URI=http://www.weijers.net/guide/ssi.shtml
SCRIPT_URL=/guide/ssi.shtml
SERVER_ADDR=213.196.37.45
SERVER_ADMIN=admin
SERVER_NAME=www.weijers.net
SERVER_PORT=80
SERVER_SIGNATURE=
SERVER_SOFTWARE=Apache/1.3.20 Sun Cobalt (Unix) mod_ssl/2.8.4 OpenSSL/0.9.6b PHP/4.1.2 mod_auth_pam_external/0.1 FrontPage/4.0.4.3 Chili!Soft-ASP/3.6.2 mod_perl/1.25
UNIQUE_ID=PU9z1dXEJS0AAEanoyE
GATEWAY_INTERFACE=CGI/1.1
SERVER_PROTOCOL=HTTP/1.0
REQUEST_METHOD=GET
QUERY_STRING=
REQUEST_URI=/guide/ssi.shtml
SCRIPT_NAME=/guide/ssi.shtml
DATE_LOCAL=Tuesday, 06 August 2002 at 08:59
DATE_GMT=Tuesday, 06 August 2002 at 06:59
LAST_MODIFIED=Thursday, 01 August 2002 at 12:03
DOCUMENT_URI=/guide/ssi.shtml
DOCUMENT_PATH_INFO=
USER_NAME=jan
DOCUMENT_NAME=ssi.shtml
carmodel=Mercedes

Note that the environment includes the variable "carmodel" that was defined in an earlier example.

Execute A Script

You can use a server side include to run a script. This is what I use on my homepage:

"The secret of a happy life is to know when to stop and then go that little bit further."
Colin Dexter, The silent world of Nicholas Quinn.

The CGI script (which is in Perl 5) opens a file with a dozen quotes, selects one at random and prints it to the page. The script, by the way, is courtesy of Matt Wright who offers a brilliant collection of scripts.

File Size

This inserts the size of the file top.gif (the logo at the top of this page). As explained earlier in this chapter, you can determine if the size is displayed in full bytes or abbreviated in kilobytes or megabytes.

File Date

This inserts the date and the time the file top.gif (the logo at the top of this page) was last modified. The format of the date and time can be customized by you as explained earlier in this chapter.

Element	Value	Example
%a	Abbreviated day of the week	Sun
%A	Day of the week	Sunday
%b	Abbreviated month name	Jan
%B	Month in full	January
%d	Date	1 (and not 01)
%H	24-hour clock hour	13
%I	12-hour clock hour	1
%j	Decimal day of the year	360
%m	Month number	11
%M	Minutes	08
%p	AM or PM	AM
%S	Seconds	09
%U	Week of the year (also %W)	49
%w	Day of the week number	05
%y	Year of the century	95
%Y	Year	1995
%Z	Time zone	EST

Operator	Meaning
"contains" or "con"	variable contains the value string
"starts with" or "start"	variable starts with the value string
"ends with" or "end"	variable ends with the value string
"=" or "=="	variable equals the value string
"!=" or "<>"	variable does not equal the value string
"<"	variable is less than the value string
"<=" or "=<"	variable is less than or equal to the value string
">"	variable is greater than the value string
">=" or "=>"	variable is greater than or equal to the value string

Operator	Meaning
string1 = string2	string1 equals string2
string1 != string2	string1 does not equal string2
string1 < string2	string1 is less than string2
string1 <= string2	string1 is less than or equal to string2
string1 > string2	string1 is greater than string2
string1 >= string2	string1 is greater than or equal to string2

Server Side Includes

Chapters

Introduction