|
Softpanorama
(slightly skeptical)
Open Source Software Educational Society |
May the
source be with you,
but remember the KISS principle ;-)
|
Server Side Includes (SSI)
Apache, NCSA HTTPd, Netscape Enterprise and several other
servers allows users to include into document other documents from the
current directory and/or simple information about the document. Such information
can include the current date, the file's last modification date, and the size or
last modification of other files. Having the server parse documents is a double
edged sword. It can be costly for heavily loaded servers to perform parsing of
files while sending them and can present a security risk. Therefore documents
that need to parsed usually have a default extension shtml. User can
specify directories to allow SSI.
To a certain extent SSI can be used as a "poor man" ASP.
Taking off with the idea of SSI, several companies including Cold Fusion and
Net Objects designed custom web servers with incredible SSI functionality. These
third party web servers provided a huge API which offered a host of server
embedded resources which app developers could use to make their web pages
dynamic that extended far beyond the limited set of commands offered by the
operating systems.
They also provided a huge number of formatting options as well including
complex tabular display.
Cold Fusion, perhaps the best-known SSI-based application server offers a set
of over 70 custom "CFML" tags that execute most, if not all of your average
needs on the custom Cold Fusion Web Server. Cold Fusion also allows you to set
name/value pairs in your HTML as well.
Notes:
- Those pages are written by people for whom English is not a
native language. Some amount of grammar and spelling errors
should be expected.
- This is a Spartan WHYFF (We Help You For Free) site. It
cannot replace the best teachers and
the
best books.
- The site contain some obsolete pages as it develops like a
living tree... Some links on older pages
are broken. Please
try to use Google, Open directory, etc. to find a replacement link
(see
HOWTO search the WEB for details).
We would appreciate if you can
mail us a correct link.
|
|
CGI
Programming Chapter 5 Server Side Includes
You're starting to get the hang of CGI, but
aren't too thrilled with the fact that you have to write full-fledged CGI
programs even when you want to output a document with only a minimum amount of
dynamic information, right? For example, say you want to display the current
date and time, or a certain CGI environment variable in your otherwise static
document. You can go through the trouble of writing a CGI program that outputs
this small amount of virtual data, or better yet, you can use a powerful
feature called Server Side Includes (or SSI).
Server Side Includes are directives which
you can place into your HTML documents to execute other programs or output
such data as environment variables and file statistics. Unfortunately, not all
servers support these directives; the CERN server cannot handle SSI, but the
servers from NCSA and Netscape can. However, there is a CGI program called
fakessi.pl that
you can use to emulate Server Side Includes if your server does not support
them.
While Server Side Includes technically are not
really CGI, they can become an important tool for incorporating CGI-like
information, as well as output from CGI programs, into documents on the Web.
How do Server Side Includes work? When the
client requests a document from the SSI-enabled server, the server parses the
specified document and returns the evaluated document (see Figure 5-1). The
server does not automatically parse
[Mar 16, 2002]
Webmaster's Guide
to Server Side Includes - WebReference.com
[June 12, 2000]
Apache Today - Apache Guide Introduction to Server Side Includes By
Rich Bowen
This is the first of three articles dealing with Server Side
Includes, usually called simply SSI. In this article, I'll talk about
configuring your server to permit SSI and introduce some basic SSI techniques
for adding dynamic content to your existing HTML pages.
In the second article, we'll talk about some of the somewhat
more advanced things you can do with SSI, and in the third week, we'll look at
the advanced things that can be done with SSI, such as conditional statements
in your SSI directives.
SSI (Server Side Includes) are directives that are placed in
HTML pages and evaluated on the server while the pages are being served. 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.
The decision of when to use SSI, and when to have your page
entirely generated by some program, is usually a matter of how much of the
page is static and how much needs to be recalculated every time the page is
served. SSI is a great way to add small pieces of information, such as the
current time. But if a majority of your page is being generated at the time
that it is served, you need to look for some other solution.
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.
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
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.
Of course, on Windows, there is no such thing as an execute
bit to set, so that limits your options a little if you're running Apache on
Windows.
SSI directives have the following syntax:
<!--#element attribute=value attribute=value ... -->
It is formatted like an HTML comment, so if you don't have
SSI correctly enabled, the browser will ignore it, but it will still be
visible in the HTML source. If you have SSI correctly configured, the
directive will be replaced with the results of the directive.
The element can be one of a number of things, and we'll talk
some more about most of these in the next installment of this series. For now,
here are some examples of what you can do with SSI.
<!--#echo var=DATE_LOCAL -->
The echo element just spits out the value of a
variable. There are a number of standard variables, which include the whole
set of environment variables that are available to CGI programs. Also, you can
define your own variables with the set element.
If you don't like the format in which the date gets printed,
you can use the config element, with a timefmt
attribute, to modify that formatting.
<!--#config timefmt="%A %B %d, %Y" -->
Today is <!--#echo var=DATE_LOCAL -->
This document last modified <!--#flastmod file="index.html" -->
This element is also subject to timefmt format
configurations.
This is one of the more common uses of SSI - to output the
results of a CGI program, such as everybody's favorite, a hit counter.
<!--#exec cgi="/cgi-bin/counter.pl" -->
We'll definitely come back to this in another article.
[July 10, 1999]
Internetter Server Side
Includes Tutorial
- Server Side Includes Tutorial
by Matt Kruse - a nice tutorial
Author's Note: This article was written in 1995, so technical
specifics may be out of date. However, the concepts still stand and I think
this is a good introduction to what SSI's are and how/why they work.
For more information on SSI's, please the
CGI Resources List of articles to continue your learning.
- Internetter Server
Side Includes Tutorial
- New Breed Software
Server Side Includes -- good page
- NCSA
HTTPd Tutorial Server Side Includes (SSI)
- Apache Module
mod_include -- Apache SSI tutorial
- Bill's
Server Side Include Programs
- CERN Server fake
ssi script - A simple Perl script that gives CERN servers "fake" server
side include capability.
- New Breed
Software's Server Side Includes - a collection of free server side include
programs. Includes counters, statistics, random banners, quotes, last-modified
date display and more.
- Server Side
Includes Tutorial -- not impressive
- Web Server 4D - SMTP, Database, HTML
enhancements, new vs. repeat page tracking, much more! From MDG Computer
Services
In Apache any document with handler of "server-parsed" will be parsed for SSI,
if the Includes option is set. If documents containing SSI
directives are given the extension .shtml, the following directives will make
Apache parse them and assign the resulting document the mime type of
text/html:
AddType text/html .shtml
AddHandler server-parsed .shtml
The following directive must be given for the directories containing the
shtml files (typically in a <Directory> section, but this directive
is also valid .htaccess files if AllowOverride Options is set):
Options +Includes
You can use the program Perl scripts to add to you document footer and header
SSI tags or other useful SSI. For adding footer and header tags Perl script
exists. Usage is simple:
toshtml file.html header.html footer.html> file.shtml.
The document is parsed as an HTML document, with special commands embedded as
SGML comments. A command has the syntax:
<!--#
element attribute=value attribute=value ... -->
The value will often be enclosed in double quotes; many commands only allow a
single attribute-value pair. Note that the comment terminator (-->)
should be preceded by whitespace to ensure that it isn't considered part of an
SSI token.
The allowed elements are:
- config
- This command controls various aspects of the parsing. The valid attributes
are:
- errmsg
- The value is a message that is sent back to the client if an error
occurs whilst parsing the document.
- sizefmt
- The value sets the format to be used which displaying the size of a
file. Valid values are
bytes for a count in bytes, or
abbrev for a count in Kb or Mb as appropriate.
- timefmt
- The value is a string to be used by the
strftime(3) library
routine when printing dates.
- echo
- This command prints one of the include variables, defined below. If the
variable is unset, it is printed as
(none). Any dates printed are
subject to the currently configured timefmt. Attributes:
- var
- The value is the name of the variable to print.
- exec
- The exec command executes a given shell command or CGI script. The
IncludesNOEXEC
Option disables this command completely. The valid attributes are:
- cgi
- The value specifies a (%-encoded) URL relative path to the CGI script.
If the path does not begin with a (/), then it is taken to be relative to
the current document. The document referenced by this path is invoked as a
CGI script, even if the server would not normally recognize it as such.
However, the directory containing the script must be enabled for CGI scripts
(with
ScriptAlias or the ExecCGI
Option).
The CGI script is given the PATH_INFO and query string (QUERY_STRING) of
the original request from the client; these cannot be specified in the URL
path. The include variables will be available to the script in addition to
the standard CGI
environment.
If the script returns a Location: header instead of output, then this
will be translated into an HTML anchor.
The include virtual element should be used in preference to
exec cgi.
- cmd
- The server will execute the given string using
/bin/sh. The
include variables are available to the command.
- fsize
- This command prints the size of the specified file, subject to the
sizefmt format specification. Attributes:
- file
- The value is a path relative to the directory containing the current
document being parsed.
- virtual
- The value is a (%-encoded) URL-path relative to the current document
being parsed. If it does not begin with a slash (/) then it is taken to be
relative to the current document.
- flastmod
- This command prints the last modification date of the specified file,
subject to the
timefmt format specification. The attributes are
the same as for the fsize command.
- include
- This command inserts the text of another document or file into the parsed
file. Any included file is subject to the usual access control. If the
directory containing the parsed file has the
Option
IncludesNOEXEC set, and the including the document would cause a program to be
executed, then it will not be included; this prevents the execution of CGI
scripts. Otherwise CGI scripts are invoked as normal using the complete URL
given in the command, including any query string.
An attribute defines the location of the document; the inclusion is done
for each attribute given to the include command. The valid attributes are:
- file
- The value is a path relative to the directory containing the current
document being parsed. It cannot contain
../, nor can it be an
absolute path. The virtual attribute should always be used in
preference to this one.
- virtual
- The value is a (%-encoded) URL relative to the current document being
parsed. The URL cannot contain a scheme or hostname, only a path and an
optional query string. If it does not begin with a slash (/) then it is
taken to be relative to the current document.
A URL is constructed from the attribute, and the output the server would
return if the URL were accessed by the client is included in the parsed
output. Thus included files can be nested.
- printenv
- This prints out a listing of all existing variables and their values. No
attributes.
- For example:
<!--#printenv -->
- Apache 1.2 and above.
- set
- This sets the value of a variable. Attributes:
- var
- The name of the variable to set.
- value
- The value to give a variable.
For example: <!--#set var="category" value="help" -->
- Apache 1.2 and above.
A number of variables are made available to parsed documents.
- DATE_GMT
- The current date in Greenwich Mean Time.
- DATE_LOCAL
- The current date in the local time zone.
- DOCUMENT_NAME
- The filename (excluding directories) of the document requested by the
user.
- DOCUMENT_URI
- The (%-decoded) URL path of the document requested by the user. Note that
in the case of nested include files, this is not then URL for the
current document.
- LAST_MODIFIED
- The last modification date of the document requested by the user.
Copyright © 1996-2007 by Dr. Nikolai Bezroukov.
www.softpanorama.org was
created as a service to the UN Sustainable Development Networking Programme (SDNP)
in the author free time.
Submit
comments This document is an industrial compilation designed and created
exclusively for educational use and is placed under the copyright of the
Open Content License(OPL).
Original materials copyright belong to respective owners. Quotes are made
for educational purposes only in compliance with the fair use doctrine.
Standard disclaimer: The statements, views and opinions presented on
this web page are those of the author and are not endorsed by, nor do they necessarily
reflect, the opinions of the author present and former employers, SDNP or any other
organization the author may be associated with. We do not warrant the correctness
of the information provided or its fitness for any purpose.
Last modified:
March 15, 2008
