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.
<!--#include virtual="/dir/file.ext"-->
<!--#include file="subdir/file.ext"-->
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)
<!--#exec cmd="cgi/myscript.cgi"-->
|
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.
<!--#echo var="DOCUMENT_NAME"-->
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.
<!--#config errmsg="[This directive failed
miserably!]"-->
<!--#include file="does_not_exist.txt"-->
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.
<!--#config sizefmt="bytes"-->
|
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.
<!--#fsize file="sample.txt"-->
Result: 1K (without sizefmt)
<!--#config sizefmt="bytes"-->
<!--#fsize file="sample.txt"-->
Result: 329 (with sizefmt)
|
flastmod
prints the last modification date of the specified file. Valid
tags are the
same as with the include command.
<!--#flastmod file="sample.txt"-->
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:
<!--#include virtual="directory/insertpage1.html"-->
</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:
<!--#exec cmd="cgi/myscript.cgi"-->
</BODY>
</HTML>
|
|