SSI

SSI: a brief overview

SSI = Server Side Includes

Inside of your HTML
Issue commands to the web-server
When web-browser recieves a request for an HTML page from a client's browser, the server can be made to look for Server Side Includes in the HTML and it will execute them, replacing the SSI commands in the HTML with the results and then returns the newly updated HTML to the client machine.
- Server Side Includes use simple HTML style commands you can add to your web page to either import a text page or run a CGI/PERL script or other program before the page is served to the client (viewer of the page).
- Server Side Includes may be the simplest, easiest way to generate simple dynamic web sites without any technical expertise of any sort.
- They let you add dynamically generated content to an existing HTML page, without having to serve the entire page via a CGI program, or other dynamic technology.
Some uses: simple counters, current time displays, rotating banners, showing different content as a function of type of browser client is using or even where they came from.

SSI on Apache Web-Server

Ask your administrator if SSIs are enabled. They are disabled by default.

Configuring Apache to permit SSI.

From www.apache.org:

ON our EBOX accounts, we are using OPTION 1 below...hence all of your HTML files with SSIs in them must be given the file extension .shtml

OPTION 1

To permit SSI on your server, you must have the following directive either in your httpd.conf file, or in a .htaccess file:

Options +Includes

This tells Apache that you want to permit files to be parsed for SSI directives.

Not just any file is parsed for SSI directives. You have to tell Apache which files should be parsed. There are two ways to do this.
You can tell Apache to parse any file with a particular file extension, such as .shtml, with the following directives:

AddType text/html .shtml
AddHandler server-parsed .shtml

One disadvantage to this approach is that if you wanted to add SSI directives to an existing page, you would have to change the name
of that page, and all links to that page, in order to give it a .shtml extension, so that those directives would be executed.

OPTION 2

The other method is to use the XBitHack directive:

XBitHack on

XBitHack tells Apache to parse files for SSI directives if they have the execute bit set. So, to add SSI directives to an existing page,
rather than having to change the file name, you would just need to make the file executable using chmod.

chmod +x pagename.html

Of course, on Windows, there is no such thing as an execute bit to set, so that limits your options a little.

DONT DO!!!!!!

A brief comment about what not to do. You'll occasionally see people recommending that you just tell Apache to parse all .html files for SSI, so that you don't have to mess with .shtml file names. These folks have perhaps not heard about XBitHack. The thing to
keep in mind is that, by doing this, you're requiring that Apache read through every single file that it sends out to clients, even if they
don't contain any SSI directives. This can slow things down quite a bit, and is not a good idea.

Special Issues on Apache

More on Apache and SSI

In its default configuration, Apache does not send the last modified date or content length HTTP headers on SSI pages, because these
values are difficult to calculate for dynamic content. This can prevent your document from being cached, and result in slower
perceived client performance. There are two ways to solve this:

1.Use the XBitHack Full configuration. This tells Apache to determine the last modified date by looking only at the date of the
originally requested file, ignoring the modification date of any included files.
2.Use the directives provided by mod_expires to set an explicit expiration time on your files, thereby letting browsers and proxies
know that it is acceptable to cache them.

Using SSI on other Web-servers.

READ their documentation!!!!!!!!!!!!

Some Special Issues

Many web-servers require that you give your files the extension .shtml (not html or htm)

There can be security concerns involved in the exec cmd call, so some servers have script execution turned off.

Extensive use of SSIs can effect server performance.

For Apache Servers, there is even an Extended SSI module (XSSI). This SSI enhancement allows for if-then-else statements, user-defined variables and other commands similar to those used in CGI/PERL scripts. See www.apache.org for details.

SSI Commands

include

Inserts the text of a specified document into the body of the current
document. Is commonly used for including headers or footers in web pages.




Notes:

Do not leave any spaces between the equal ("=") sign and the file it specifies. Doing so will cause an error message to be displayed.

Any included file is subject to the usual access authorization controls.

If you use a domain name you must use the virtual command. file only works with WebCom URLs.

virtual option

gives a virtual path to a document on the server. A normal file or another parsed document may be accessed using this tag. Please note that the path of this file name should be the URL of the file, with the domain name removed, and the userid added. For instance, if the URL of a file is "http://www.your-domain.com/products/footer.txt" and your userid is "userid" then the path to use with this include directive would be: "/userid/products/footer.txt"

file option

gives a pathname relative to the current directory. ../ cannot be used in this pathname, nor can absolute paths be used. (If you need to refer to a file in a higher directory, you might consider using virtual described above.)

exec

makes the server execute the referenced program. Results returned from program will be inserted in HTML where this exec command exists. The tag cmd specifies the file to execute. This could be a program in any language, the following example has a CGI program. (With Apache and cgi's you use the include SSI command and not the exec command)

echo

prints the value of one of the include variables (select the hotlink for definitions). The only valid tag to this command is var, whose value is the name of the variable you wish to echo.



Result: welcome.shtml

ALL OF THE CGI VARIABLE SET PLUS............

DOCUMENT_NAME: The current filename.

Example: variables.shtml

DOCUMENT_URI: The virtual path to this document (such as /~webcom/sample.shtml).

Example: /help/inc/variables.shtml

DATE_LOCAL: The current date, local time zone.

Example: Friday, 22-Dec-2000 17:51:18 PST

DATE_GMT: Same as DATE_LOCAL but in Greenwich mean time.

Example: Saturday, 23-Dec-2000 01:51:18 GMT

LAST_MODIFIED: The last modification date of the current document.

Example: Tuesday, 30-Mar-1999 15:29:38 PST

config

The config directive controls various aspects of the file parsing. There are two valid tags:

errmsg
controls what message is sent back to the client if an error includes while parsing the document. When an error occurs, it is logged in the server's error log.




Result: [This directive failed miserably!]

sizefmt
determines the formatting to be used when displaying the size of a file. Valid choices are bytes, for a formatted byte count (formatted as 1,234,567), or abbrev for an abbreviated version displaying the number of kilobytes or megabytes the file occupies.

fsize

prints the size of the specified file. Valid tags match those of the
include command. The resulting format of this command is subject to
the sizefmt parameter of the config command.



Result: 1K (without sizefmt)




Result: 329 (with sizefmt)

flastmod

prints the last modification date of the specified file. Valid tags are the
same as with the include command.



Result: Thursday, 13-Jul-95 14:40:33

Illustrations

Example 1 (ssihtml.shtml) Inserts another html page.

<HTML>
<HEAD>
<TITLE>Server Side Includes HTML Sample</TITLE>
</HEAD>
Example of a server side include inserting a block of text onto a Web
page:



</BODY>
</HTML>

Example 2 (ssicgi.html) Calls a CGI Program to process, and inserts results in HTML.

<HTML>
<HEAD><
TITLE>Server Side Includes CGI Sample</TITLE>
</HEAD>
<BODY>
Example of a server side include inserted a script on a Web page:



</BODY>
</HTML>