httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sl...@locus.apache.org
Subject cvs commit: httpd-docs-1.3/htdocs/manual/howto SSI-HOWTO.html
Date Fri, 10 Nov 2000 21:02:40 GMT
slive       00/11/10 13:02:39

  Modified:    htdocs/manual index.html
               htdocs/manual/mod mod_include.html
               htdocs/manual/howto SSI-HOWTO.html
  Log:
  Some small updates to SSI tutorial, plus a link from mod_include.html.
  Since Rich has, I believe, given up on keeping his source in sync,
  I also ran the tutorial through htmltidy to make it a little easier
  to maintain.  If anyone is offended by this, please let me know.
  
  Revision  Changes    Path
  1.41      +1 -1      httpd-docs-1.3/htdocs/manual/index.html
  
  Index: index.html
  ===================================================================
  RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/index.html,v
  retrieving revision 1.40
  retrieving revision 1.41
  diff -u -r1.40 -r1.41
  --- index.html	2000/11/05 20:59:14	1.40
  +++ index.html	2000/11/10 21:02:39	1.41
  @@ -134,7 +134,7 @@
   </td></tr><tr><td>
   <A HREF="vhosts/index.html">Virtual Hosts</A>
   </td></tr><tr><td>
  -<a href="howto/SSI-HOWTO.html">Introduction to Server Side Includes</a>
  +<a href="howto/SSI-HOWTO.html">Server Side Includes</a>
   </td></tr><tr><td>
   <A HREF="handler.html">Handlers</A>
   </td></tr><tr><td>
  
  
  
  1.30      +5 -1      httpd-docs-1.3/htdocs/manual/mod/mod_include.html
  
  Index: mod_include.html
  ===================================================================
  RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/mod/mod_include.html,v
  retrieving revision 1.29
  retrieving revision 1.30
  diff -u -r1.29 -r1.30
  --- mod_include.html	2000/09/28 17:04:57	1.29
  +++ mod_include.html	2000/11/10 21:02:39	1.30
  @@ -15,7 +15,7 @@
   <!--#include virtual="header.html" -->
   <H1 ALIGN="CENTER">Module mod_include</H1>
   
  -<p>This module provides for server-parsed html documents.</p>
  +<p>This module provides for documents with Server Side Includes (SSI).</p>
   
   <P><A
   HREF="module-dict.html#Status"
  @@ -41,6 +41,10 @@
   elements allow conditional text, the inclusion other files or
   programs, as well as the setting and printing of environment
   variables.</p>
  +
  +<p>For an introduction to this topic, we also provide a
  +<a href="../howto/SSI-HOWTO.html">tutorial on Server Side Includes</a>.</p>
  +
   
   <H2>Directives</H2>
   <UL>
  
  
  
  1.5       +491 -316  httpd-docs-1.3/htdocs/manual/howto/SSI-HOWTO.html
  
  Index: SSI-HOWTO.html
  ===================================================================
  RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/howto/SSI-HOWTO.html,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- SSI-HOWTO.html	2000/11/06 03:06:40	1.4
  +++ SSI-HOWTO.html	2000/11/10 21:02:39	1.5
  @@ -1,344 +1,519 @@
   <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  -<HTML>
  -<HEAD>
  -<TITLE>Apache Tutorial: Introduction to Server Side Includes</TITLE>
  -<LINK REV="made" HREF="mailto:rbowen@rcbowen.com">
  -</HEAD>
  -
  +<html>
  +<head>
  +<title>Apache Tutorial: Introduction to Server Side Includes</title>
  +<link rev="made" href="mailto:rbowen@rcbowen.com">
  +</head>
   <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  -<BODY
  - BGCOLOR="#FFFFFF"
  - TEXT="#000000"
  - LINK="#0000FF"
  - VLINK="#000080"
  - ALINK="#FF0000"
  ->
  +<body bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#000080"
  +alink="#FF0000">
   <!--#include virtual="header.html" -->
  -<H1 ALIGN="CENTER">Apache Tutorial: Introduction to Server Side Includes</H1>
  +<h1 align="CENTER">Apache Tutorial: Introduction to Server Side
  +Includes</h1>
   
  +<a name="__index__"></a> <!-- INDEX BEGIN -->
  + 
   
  -<A NAME="__index__"></A>
  -<!-- INDEX BEGIN -->
  +<ul>
  +<li><a href=
  +"#apache tutorial: introduction to server side includes">Apache
  +Tutorial: Introduction to Server Side Includes</a></li>
   
  -<UL>
  +<li><a href="#what are ssi">What are SSI?</a></li>
   
  -	<LI><A HREF="#apache tutorial: introduction to server side includes">Apache
Tutorial: Introduction to Server Side Includes</A></LI>
  -	<LI><A HREF="#what are ssi">What are SSI?</A></LI>
  -	<LI><A HREF="#configuring your server to permit ssi">Configuring your server
to permit SSI</A></LI>
  -	<LI><A HREF="#basic ssi directives">Basic SSI directives</A></LI>
  -	<UL>
  -
  -		<LI><A HREF="#today's date">Today's date</A></LI>
  -		<LI><A HREF="#modification date of the file">Modification date of the file</A></LI>
  -		<LI><A HREF="#including the results of a cgi program">Including the results
of a CGI program</A></LI>
  -	</UL>
  -
  -	<LI><A HREF="#additional examples">Additional examples</A></LI>
  -	<LI><A HREF="#when was this document modified">When was this document modified?</A></LI>
  -	<LI><A HREF="#including a standard footer">Including a standard footer</A></LI>
  -	<LI><A HREF="#what else can i config">What else can I config?</A></LI>
  -	<LI><A HREF="#executing commands">Executing commands</A></LI>
  -	<LI><A HREF="#advanced ssi techniques">Advanced SSI techniques</A></LI>
  -	<LI><A HREF="#caveat">Caveat</A></LI>
  -	<LI><A HREF="#setting variables">Setting variables</A></LI>
  -	<LI><A HREF="#conditional expressions">Conditional expressions</A></LI>
  -	<LI><A HREF="#conclusion">Conclusion</A></LI>
  -</UL>
  -<!-- INDEX END -->
  +<li><a href="#configuring your server to permit ssi">Configuring your
  +server to permit SSI</a></li>
   
  -<HR>
  -<P>
  -<H1><A NAME="apache tutorial: introduction to server side includes">Apache
Tutorial: Introduction to Server Side Includes</A></H1>
  +<li><a href="#basic ssi directives">Basic SSI directives</a>
   
  -<table border=1><tr><td valign="top">
  -<strong>Related Modules</strong><br><br>
  +<ul>
  +  <li><a href="#today's date">Today's date</a></li>
   
  -<a href="../mod/mod_include.html">mod_include</a><br>
  -<a href="../mod/mod_cgi.html">mod_cgi</a><br>
  +  <li><a href="#modification date of the file">Modification date of the
  +file</a></li>
  +
  +  <li><a href="#including the results of a cgi program">Including the
  +results of a CGI program</a></li>
  +</ul>
  +</li>
  +
  +<li><a href="#additional examples">Additional examples</a>
  +
  +<ul>
  +<li><a href="#when was this document modified">When was this document
  +modified?</a></li>
  +
  +<li><a href="#including a standard footer">Including a standard
  +footer</a></li>
   
  -</td><td valign="top">
  -<strong>Related Directives</strong><br><br>
  +<li><a href="#what else can i config">What else can I config?</a></li>
   
  -<a href="../mod/core.html#options">Options</a><br>
  +<li><a href="#executing commands">Executing commands</a></li>
  +</ul>
  +</li>
  +
  +<li><a href="#advanced ssi techniques">Advanced SSI techniques</a>
  +
  +<ul>
  +<li><a href="#setting variables">Setting variables</a></li>
  +
  +<li><a href="#conditional expressions">Conditional expressions</a></li>
  +</ul>
  +</li>
  +
  +<li><a href="#conclusion">Conclusion</a></li>
  +</ul>
  +
  +<!-- INDEX END -->
  +<hr>
  +<h2><a name=
  +"apache tutorial: introduction to server side includes">Apache
  +Tutorial: Introduction to Server Side Includes</a></h2>
  +
  +<table border="1">
  +<tr>
  +<td valign="top"><strong>Related Modules</strong><br>
  +<br>
  + <a href="../mod/mod_include.html">mod_include</a><br>
  +<a href="../mod/mod_cgi.html">mod_cgi</a><br>
  +<a href="../mod/mod_expires.html">mod_expires</a><br>
  + </td>
  +<td valign="top"><strong>Related Directives</strong><br>
  +<br>
  + <a href="../mod/core.html#options">Options</a><br>
   <a href="../mod/mod_include.html#xbithack">XBitHack</a><br>
   <a href="../mod/mod_mime.html#addtype">AddType</a><br>
   <a href="../mod/mod_mime.html#addhandler">AddHandler</a><br>
  -<a href="../mod/mod_setenvif.html#BrowserMatchNoCase">BrowserMatchNoCase</a><br>
  +<a href=
  +"../mod/mod_setenvif.html#BrowserMatchNoCase">BrowserMatchNoCase</a><br>
   
  -</td></tr></table>
  -
  -<P>This HOWTO first appeared in Apache Today (http://www.apachetoday.com/)
  -as a series of three articles. They appear here by arrangement with
  -ApacheToday and Internet.com.</P>
  -<P>This article deals 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.</P>
  -<P>In the latter part of the article, we'll talk about some of the somewhat
  -more advanced things that can be done with SSI, such as conditional statements
  -in your SSI directives.</P>
  -<P>
  -<HR>
  -<H1><A NAME="what are ssi">What are SSI?</A></H1>
  -<P>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.</P>
  -<P>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
  + </td>
  +</tr>
  +</table>
  +
  +<p>This HOWTO first appeared in Apache Today
  +(http://www.apachetoday.com/) as a series of three articles. They
  +appear here by arrangement with ApacheToday and Internet.com.</p>
  +
  +<p>This article deals 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.</p>
  +
  +<p>In the latter part of the article, we'll talk about some of the
  +somewhat more advanced things that can be done with SSI, such as
  +conditional statements in your SSI directives.</p>
  +
  +<hr>
  +<h2><a name="what are ssi">What are SSI?</a></h2>
  +
  +<p>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.</p>
  +
  +<p>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.</P>
  -<P>
  -<HR>
  -<H1><A NAME="configuring your server to permit ssi">Configuring your server
to permit SSI</A></H1>
  -<P>To permit SSI on your server, you must have the following directive either
  -in your <CODE>httpd.conf</CODE> file, or in a <CODE>.htaccess</CODE>
file:</P>
  -<PRE>
  -        Options +Includes</PRE>
  -<P>This tells Apache that you want to permit files to be parsed for SSI 
  -directives.</P>
  -<P>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 <CODE>.shtml</CODE>,
with
  -the following directives:</P>
  -<PRE>
  +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.</p>
  +
  +<hr>
  +<h2><a name="configuring your server to permit ssi">Configuring your
  +server to permit SSI</a></h2>
  +
  +<p>To permit SSI on your server, you must have the following directive
  +either in your <code>httpd.conf</code> file, or in a
  +<code>.htaccess</code> file:</p>
  +
  +<pre>
  +        Options +Includes
  +</pre>
  +
  +<p>This tells Apache that you want to permit files to be parsed for SSI
  +directives.</p>
  +
  +<p>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 <code>.shtml</code>, with the following directives:</p>
  +
  +<pre>
           AddType text/html .shtml
  -        AddHandler server-parsed .shtml</PRE>
  -<P>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 <CODE>.shtml</CODE> extension,
so that
  -those directives would be executed.</P>
  -<P>The other method is to use the <CODE>XBitHack</CODE> directive:</P>
  -<PRE>
  -        XBitHack on</PRE>
  -<P><CODE>XBitHack</CODE> 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 <CODE>chmod</CODE>.</P>
  -<PRE>
  -        chmod +x pagename.html</PRE>
  -<P>A brief comment about what not to do. You'll occasionally see people
  -recommending that you just tell Apache to parse all <CODE>.html</CODE> files
for SSI,
  -so that you don't have to mess with <CODE>.shtml</CODE> file names. These folks
have
  -perhaps not heard about <CODE>XBitHack</CODE>. The thing to keep in mind is
that, by
  -doing this, you're requiring that Apache read through every single file that
  +        AddHandler server-parsed .shtml
  +</pre>
  +
  +<p>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
  +<code>.shtml</code> extension, so that those directives would be
  +executed.</p>
  +
  +<p>The other method is to use the <code>XBitHack</code> directive:</p>
  +
  +<pre>
  +        XBitHack on
  +</pre>
  +
  +<p><code>XBitHack</code> 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 <code>chmod</code>.</p>
  +
  +<pre>
  +        chmod +x pagename.html
  +</pre>
  +
  +<p>A brief comment about what not to do. You'll occasionally see people
  +recommending that you just tell Apache to parse all <code>.html</code>
  +files for SSI, so that you don't have to mess with <code>.shtml</code>
  +file names. These folks have perhaps not heard about
  +<code>XBitHack</code>. 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.</P>
  -<P>Of course, on Windows, there is no such thing as an execute bit to set,
  -so that limits your options a little.</P>
  -<P>
  -<HR>
  -<H1><A NAME="basic ssi directives">Basic SSI directives</A></H1>
  -<P>SSI directives have the following syntax:</P>
  -<PRE>
  -        &lt;!--#element attribute=value attribute=value ... --&gt;</PRE>
  -<P>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
  -its results.</P>
  -<P>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</P>
  -<P>
  -<H2><A NAME="today's date">Today's date</A></H2>
  -<PRE>
  -        &lt;!--#echo var=DATE_LOCAL --&gt;</PRE>
  -<P>The <CODE>echo</CODE> 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 <CODE>set</CODE> element.</P>
  -<P>If you don't like the format in which the date gets printed, you can use
  -the <CODE>config</CODE> element, with a <CODE>timefmt</CODE> attribute,
to modify that formatting.</P>
  -<PRE>
  -        &lt;!--#config timefmt=&quot;%A %B %d, %Y&quot; --&gt;
  -        Today is &lt;!--#echo var=DATE_LOCAL --&gt;</PRE>
  -<P>
  -<H2><A NAME="modification date of the file">Modification date of the file</A></H2>
  -<PRE>
  -        This document last modified &lt;!--#flastmod file=&quot;index.html&quot;
--&gt;</PRE>
  -<P>This element is also subject to <CODE>timefmt</CODE> format configurations.</P>
  -<P>
  -<H2><A NAME="including the results of a cgi program">Including the results
of a CGI program</A></H2>
  -<P>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.''</P>
  -<PRE>
  -        &lt;!--#include virtual=&quot;/cgi-bin/counter.pl&quot; --&gt;</PRE>
  -<P>
  -<HR>
  -<H1><A NAME="additional examples">Additional examples</A></H1>
  -<P>Following are some specific examples of things you can do in your HTML
  -documents with SSI.</P>
  -<P>
  -<HR>
  -<H1><A NAME="when was this document modified">When was this document modified?</A></H1>
  -<P>Earlier, we mentioned that you could use SSI to inform the user when the 
  -document was most recently modified. However, the actual method for doing that
  -was left somewhat in question. The following code, placed in your HTML document,
  -will put such a time stamp on your page. Of course, you will have to have SSI
  -correctly enabled, as discussed above.</P>
  -<PRE>
  -        &lt;!--#config timefmt=&quot;%A %B %d, %Y&quot; --&gt;
  -        This file last modified &lt;!--#flastmod file=&quot;ssi.shtml&quot;
--&gt;</PRE>
  -<P>Of course, you will need to replace the <CODE>ssi.shtml</CODE> with
the actual name of the file
  -that you're referring to. This can be inconvenient if you're just looking for a generic
  -piece of code that you can paste into any file, so you probably want to use the
  -<CODE>LAST_MODIFIED</CODE> variable instead:</P>
  -<PRE>
  -        &lt;!--#config timefmt=&quot;%D&quot; --&gt;
  -        This file last modified &lt;!--#echo var=&quot;LAST_MODIFIED&quot;
--&gt;</PRE>
  -<P>For more details on the <CODE>timefmt</CODE> format, go to your favorite
search site
  -and look for <CODE>ctime</CODE>. The syntax is the same.</P>
  -<P>
  -<HR>
  -<H1><A NAME="including a standard footer">Including a standard footer</A></H1>
  -<P>If you are managing any site that is more than a few pages, you may find that
making
  -changes to all those pages can be a real pain, particularly if you are trying to 
  -maintain some kind of standard look across all those pages.</P>
  -<P>Using an include file for a header and/or a footer can reduce the burden of these
  -updates. You just have to make one footer file, and then include it into each page
  -with the <CODE>include</CODE> SSI command. The <CODE>include</CODE>
element can determine what file 
  -to include with either the <CODE>file</CODE> attribute, or the <CODE>virtual</CODE>
attribute. The <CODE>file</CODE>
  -attribute is a file path, <EM>relative to the current directory</EM>. That
means that it
  -cannot be an absolute file path (starting with /), nor can it contain ../ as
  -part of that path. The <CODE>virtual</CODE> attribute is probably more useful,
and should
  -specify a URL relative to the document being served. It can start with a /, but must
  -be on the same server as the file being served.</P>
  -<PRE>
  -        &lt;!--#include virtual=&quot;/footer.html&quot; --&gt;</PRE>
  -<P>I'll frequently combine the last two things, putting a <CODE>LAST_MODIFIED</CODE>
directive
  -inside a footer file to be included. SSI directives can be contained in the included
  -file, and includes can be nested - that is, the included file can include another
  -file, and so on.</P>
  -<P>
  -<HR>
  -<H1><A NAME="what else can i config">What else can I config?</A></H1>
  -<P>In addition to being able to <CODE>config</CODE> the time format,
you can also <CODE>config</CODE> two
  -other things.</P>
  -<P>Usually, when something goes wrong with your SSI directive, you get the message</P>
  -<PRE>
  -        [an error occurred while processing this directive]</PRE>
  -<P>If you want to change that message to something else, you can do so with the <CODE>errmsg</CODE>
  -attribute to the <CODE>config</CODE> element:</P>
  -<PRE>
  -        &lt;!--#config errmsg=&quot;[It appears that you don't know how to use
SSI]&quot; --&gt;</PRE>
  -<P>Hopefully, end users will never see this message, because you will have resolved
  -all the problems with your SSI directives before your site goes live. (Right?)</P>
  -<P>And you can <CODE>config</CODE> the format in which file sizes are
returned with the <CODE>sizefmt</CODE>
  -attribute. You can specify <CODE>bytes</CODE> for a full count in bytes, or
<CODE>abbrev</CODE> for an
  -abbreviated number in Kb or Mb, as appropriate.</P>
  -<P>
  -<HR>
  -<H1><A NAME="executing commands">Executing commands</A></H1>
  -<P>I expect that I'll have an article some time in the coming months about using
  -SSI with small CGI programs. For now, here's something else that you can 
  -do with the <CODE>exec</CODE> element. You can actually have SSI execute a
command using
  -the shell (<CODE>/bin/sh</CODE>, to be precise - or the DOS shell, if you're
on Win32).
  -The following, for example, will give you a directory listing.</P>
  -<PRE>
  +This can slow things down quite a bit, and is not a good idea.</p>
  +
  +<p>Of course, on Windows, there is no such thing as an execute bit to
  +set, so that limits your options a little.</p>
  +
  +<p>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:</p>
  +
  +<ol> 
  +
  +<li>Use the <code>XBitHack Full</code> 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. </li> 
  +
  +<li>Use the directives provided by <a
  +href="../mod/mod_expires.html">mod_expires</a> to set an explicit
  +expiration time on your files, thereby letting browsers and proxies
  +know that it is acceptable to cache them. </li>
  +
  +</ol>
  +
  +
  +<hr>
  +<h2><a name="basic ssi directives">Basic SSI directives</a></h2>
  +
  +<p>SSI directives have the following syntax:</p>
  +
  +<pre>
  +        &lt;!--#element attribute=value attribute=value ... --&gt;
  +</pre>
  +
  +<p>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 its results.</p>
  +
  +<p>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</p>
  +
  +<h3><a name="today's date">Today's date</a></h3>
  +
  +<pre>
  +        &lt;!--#echo var=DATE_LOCAL --&gt;
  +</pre>
  +
  +<p>The <code>echo</code> 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 <code>set</code>
  +element.</p>
  +
  +<p>If you don't like the format in which the date gets printed, you can
  +use the <code>config</code> element, with a <code>timefmt</code>
  +attribute, to modify that formatting.</p>
  +
  +<pre>
  +        &lt;!--#config timefmt="%A %B %d, %Y" --&gt;
  +        Today is &lt;!--#echo var=DATE_LOCAL --&gt;
  +</pre>
  +
  +<h3><a name="modification date of the file">Modification date of the
  +file</a></h3>
  +
  +<pre>
  +        This document last modified &lt;!--#flastmod file="index.html" --&gt;
  +</pre>
  +
  +<p>This element is also subject to <code>timefmt</code> format
  +configurations.</p>
  +
  +<h3><a name="including the results of a cgi program">Including the
  +results of a CGI program</a></h3>
  +
  +<p>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.''</p>
  +
  +<pre>
  +        &lt;!--#include virtual="/cgi-bin/counter.pl" --&gt;
  +</pre>
  +
  +<hr>
  +<h2><a name="additional examples">Additional examples</a></h2>
  +
  +<p>Following are some specific examples of things you can do in your
  +HTML documents with SSI.</p>
  +
  +<hr>
  +<h2><a name="when was this document modified">When was this document
  +modified?</a></h2>
  +
  +<p>Earlier, we mentioned that you could use SSI to inform the user when
  +the document was most recently modified. However, the actual method for
  +doing that was left somewhat in question. The following code, placed in
  +your HTML document, will put such a time stamp on your page. Of course,
  +you will have to have SSI correctly enabled, as discussed above.</p>
  +
  +<pre>
  +        &lt;!--#config timefmt="%A %B %d, %Y" --&gt;
  +        This file last modified &lt;!--#flastmod file="ssi.shtml" --&gt;
  +</pre>
  +
  +<p>Of course, you will need to replace the <code>ssi.shtml</code> with
  +the actual name of the file that you're referring to. This can be
  +inconvenient if you're just looking for a generic piece of code that
  +you can paste into any file, so you probably want to use the
  +<code>LAST_MODIFIED</code> variable instead:</p>
  +
  +<pre>
  +        &lt;!--#config timefmt="%D" --&gt;
  +        This file last modified &lt;!--#echo var="LAST_MODIFIED" --&gt;
  +</pre>
  +
  +<p>For more details on the <code>timefmt</code> format, go to your
  +favorite search site and look for <code>ctime</code>. The syntax is the
  +same.</p>
  +
  +<hr>
  +<h2><a name="including a standard footer">Including a standard
  +footer</a></h2>
  +
  +<p>If you are managing any site that is more than a few pages, you may
  +find that making changes to all those pages can be a real pain,
  +particularly if you are trying to maintain some kind of standard look
  +across all those pages.</p>
  +
  +<p>Using an include file for a header and/or a footer can reduce the
  +burden of these updates. You just have to make one footer file, and
  +then include it into each page with the <code>include</code> SSI
  +command. The <code>include</code> element can determine what file to
  +include with either the <code>file</code> attribute, or the
  +<code>virtual</code> attribute. The <code>file</code> attribute
is a
  +file path, <em>relative to the current directory</em>. That means that
  +it cannot be an absolute file path (starting with /), nor can it
  +contain ../ as part of that path. The <code>virtual</code> attribute is
  +probably more useful, and should specify a URL relative to the document
  +being served. It can start with a /, but must be on the same server as
  +the file being served.</p>
  +
  +<pre>
  +        &lt;!--#include virtual="/footer.html" --&gt;
  +</pre>
  +
  +<p>I'll frequently combine the last two things, putting a
  +<code>LAST_MODIFIED</code> directive inside a footer file to be
  +included. SSI directives can be contained in the included file, and
  +includes can be nested - that is, the included file can include another
  +file, and so on.</p>
  +
  +<hr>
  +<h2><a name="what else can i config">What else can I config?</a></h2>
  +
  +<p>In addition to being able to <code>config</code> the time format,
  +you can also <code>config</code> two other things.</p>
  +
  +<p>Usually, when something goes wrong with your SSI directive, you get
  +the message</p>
  +
  +<pre>
  +        [an error occurred while processing this directive]
  +</pre>
  +
  +<p>If you want to change that message to something else, you can do so
  +with the <code>errmsg</code> attribute to the <code>config</code>
  +element:</p>
  +
  +<pre>
  +        &lt;!--#config errmsg="[It appears that you don't know how to use SSI]" --&gt;
  +</pre>
  +
  +<p>Hopefully, end users will never see this message, because you will
  +have resolved all the problems with your SSI directives before your
  +site goes live. (Right?)</p>
  +
  +<p>And you can <code>config</code> the format in which file sizes are
  +returned with the <code>sizefmt</code> attribute. You can specify
  +<code>bytes</code> for a full count in bytes, or <code>abbrev</code>
  +for an abbreviated number in Kb or Mb, as appropriate.</p>
  +
  +<hr>
  +<h2><a name="executing commands">Executing commands</a></h2>
  +
  +<p>I expect that I'll have an article some time in the coming months
  +about using SSI with small CGI programs. For now, here's something else
  +that you can do with the <code>exec</code> element. You can actually
  +have SSI execute a command using the shell (<code>/bin/sh</code>, to be
  +precise - or the DOS shell, if you're on Win32). The following, for
  +example, will give you a directory listing.</p>
  +
  +<pre>
           &lt;pre&gt;
  -        &lt;!--#exec cmd=&quot;ls&quot; --&gt;
  -        &lt;/pre&gt;</PRE>
  -<P>or, on Windows</P>
  -<PRE>
  +        &lt;!--#exec cmd="ls" --&gt;
  +        &lt;/pre&gt;
  +</pre>
  +
  +<p>or, on Windows</p>
  +
  +<pre>
           &lt;pre&gt;
  -        &lt;!--#exec cmd=&quot;dir&quot; --&gt;
  -        &lt;/pre&gt;</PRE>
  -<P>You might notice some strange formatting with this directive on Windows, because
  -the output from <CODE>dir</CODE> contains the string ``&lt;<CODE>dir</CODE>&gt;''
in it, which confuses browsers.</P>
  -<P>Note that this feature is exceedingly dangerous, as it will execute whatever
  -code happens to be embedded in the <CODE>exec</CODE> tag. If you have any situation
  -where users can edit content on your web pages, such as with a ``guestbook'', for
  -example, make sure that you have this feature disabled. You can allow SSI,
  -but not the <CODE>exec</CODE> feature, with the <CODE>IncludesNOEXEC</CODE>
argument to the
  -<CODE>Options</CODE> directive.</P>
  -<P>
  -<HR>
  -<H1><A NAME="advanced ssi techniques">Advanced SSI techniques</A></H1>
  -<P>In addition to spitting out content, Apache SSI gives you the option of setting
  -variables, and using those variables in comparisons and conditionals.</P>
  -<P>
  -<HR>
  -<H1><A NAME="caveat">Caveat</A></H1>
  -<P>Most of the features discussed in this article are only available to you if you

  -are running Apache 1.2 or later. Of course, if you are not running Apache 1.2 or
  -later, you need to upgrade immediately, if not sooner. Go on. Do it now. We'll wait.</P>
  -<P>
  -<HR>
  -<H1><A NAME="setting variables">Setting variables</A></H1>
  -<P>Using the <CODE>set</CODE> directive, you can set variables for later
use. We'll need this
  -later in the discussion, so we'll talk about it here. The syntax of this is
  -as follows:</P>
  -<PRE>
  -        &lt;!--#set var=&quot;name&quot; value=&quot;Rich&quot; --&gt;</PRE>
  -<P>In addition to merely setting values literally like that, you can use
  -any other variable, including, for example, environment variables, or some of the
  -variables we discussed in the last article (like <CODE>LAST_MODIFIED</CODE>,
for example)
  -to give values to your variables. You will specify that something is a variable,
  -rather than a literal string, by using the dollar sign ($) before the name of 
  -the variable.</P>
  -<PRE>
  -        &lt;!--#set var=&quot;modified&quot; value=&quot;$LAST_MODIFIED&quot;
--&gt;</PRE>
  -<P>To put a literal dollar sign into the value of your variable, you need to escape
  -the dollar sign with a backslash.</P>
  -<PRE>
  -        &lt;!--#set var=&quot;cost&quot; value=&quot;\$100&quot; --&gt;</PRE>
  -<P>Finally, if you want to put a variable in the midst of a longer string, and there's
  -a chance that the name of the variable will run up against some other characters,
  -and thus be confused with those characters, you can place the name of the variable 
  -in braces, to remove this confusion. (It's hard to come up with a really good
  -example of this, but hopefully you'll get the point.)</P>
  -<PRE>
  -        &lt;!--#set var=&quot;date&quot; value=&quot;${DATE_LOCAL}_${DATE_GMT}&quot;
--&gt;</PRE>
  -<P>
  -<HR>
  -<H1><A NAME="conditional expressions">Conditional expressions</A></H1>
  -<P>Now that we have variables, and are able to set and compare their values, we 
  -can use them to express conditionals. This lets SSI be a tiny programming language
  -of sorts. <CODE>mod_include</CODE> provides an <CODE>if</CODE>,
<CODE>elif</CODE>, <CODE>else</CODE>, <CODE>endif</CODE>
structure
  -for building conditional statements. This allows you to effectively generate 
  -multiple logical pages out of one actual page.</P>
  -<P>The structure of this conditional construct is:</P>
  -<PRE>
  -        &lt;!--#if expr=&quot;test_condition&quot; --&gt;
  -    &lt;!--#elif expr=&quot;test_condition&quot; --&gt;
  +        &lt;!--#exec cmd="dir" --&gt;
  +        &lt;/pre&gt;
  +</pre>
  +
  +<p>You might notice some strange formatting with this directive on
  +Windows, because the output from <code>dir</code> contains the string
  +``&lt;<code>dir</code>&gt;'' in it, which confuses browsers.</p>
  +
  +<p>Note that this feature is exceedingly dangerous, as it will execute
  +whatever code happens to be embedded in the <code>exec</code> tag. If
  +you have any situation where users can edit content on your web pages,
  +such as with a ``guestbook'', for example, make sure that you have this
  +feature disabled. You can allow SSI, but not the <code>exec</code>
  +feature, with the <code>IncludesNOEXEC</code> argument to the
  +<code>Options</code> directive.</p>
  +
  +<hr>
  +<h2><a name="advanced ssi techniques">Advanced SSI techniques</a></h2>
  +
  +<p>In addition to spitting out content, Apache SSI gives you the option
  +of setting variables, and using those variables in comparisons and
  +conditionals.</p>
  +
  +<h3><a name="caveat">Caveat</a></h3>
  +
  +<p>Most of the features discussed in this article are only available to
  +you if you are running Apache 1.2 or later. Of course, if you are not
  +running Apache 1.2 or later, you need to upgrade immediately, if not
  +sooner. Go on. Do it now. We'll wait.</p>
  +
  +<hr>
  +<h2><a name="setting variables">Setting variables</a></h2>
  +
  +<p>Using the <code>set</code> directive, you can set variables for
  +later use. We'll need this later in the discussion, so we'll talk about
  +it here. The syntax of this is as follows:</p>
  +
  +<pre>
  +        &lt;!--#set var="name" value="Rich" --&gt;
  +</pre>
  +
  +<p>In addition to merely setting values literally like that, you can
  +use any other variable, including, for example, environment variables,
  +or some of the variables we discussed in the last article (like
  +<code>LAST_MODIFIED</code>, for example) to give values to your
  +variables. You will specify that something is a variable, rather than a
  +literal string, by using the dollar sign ($) before the name of the
  +variable.</p>
  +
  +<pre>
  +        &lt;!--#set var="modified" value="$LAST_MODIFIED" --&gt;
  +</pre>
  +
  +<p>To put a literal dollar sign into the value of your variable, you
  +need to escape the dollar sign with a backslash.</p>
  +
  +<pre>
  +        &lt;!--#set var="cost" value="\$100" --&gt;
  +</pre>
  +
  +<p>Finally, if you want to put a variable in the midst of a longer
  +string, and there's a chance that the name of the variable will run up
  +against some other characters, and thus be confused with those
  +characters, you can place the name of the variable in braces, to remove
  +this confusion. (It's hard to come up with a really good example of
  +this, but hopefully you'll get the point.)</p>
  +
  +<pre>
  +        &lt;!--#set var="date" value="${DATE_LOCAL}_${DATE_GMT}" --&gt;
  +</pre>
  +
  +<hr>
  +<h2><a name="conditional expressions">Conditional expressions</a></h2>
  +
  +<p>Now that we have variables, and are able to set and compare their
  +values, we can use them to express conditionals. This lets SSI be a
  +tiny programming language of sorts. <code>mod_include</code> provides
  +an <code>if</code>, <code>elif</code>, <code>else</code>,
  +<code>endif</code> structure for building conditional statements. This
  +allows you to effectively generate multiple logical pages out of one
  +actual page.</p>
  +
  +<p>The structure of this conditional construct is:</p>
  +
  +<pre>
  +        &lt;!--#if expr="test_condition" --&gt;
  +    &lt;!--#elif expr="test_condition" --&gt;
       &lt;!--#else --&gt;
  -    &lt;!--#endif --&gt;</PRE>
  -<P>A <EM>test_condition</EM> can be any sort of logical comparison -
either comparing values
  -to one another, or testing the ``truth'' of a particular value. (A given string is
  -true if it is nonempty.) For a full list of the comparison operators available to 
  -you, see the <CODE>mod_include</CODE> documentation. Here are some examples
of how one might
  -use this construct.</P>
  -<P>In your configuration file, you could put the following line:</P>
  -<PRE>
  +    &lt;!--#endif --&gt;
  +</pre>
  +
  +<p>A <em>test_condition</em> can be any sort of logical comparison -
  +either comparing values to one another, or testing the ``truth'' of a
  +particular value. (A given string is true if it is nonempty.) For a
  +full list of the comparison operators available to you, see the
  +<code>mod_include</code> documentation. Here are some examples of how
  +one might use this construct.</p>
  +
  +<p>In your configuration file, you could put the following line:</p>
  +
  +<pre>
           BrowserMatchNoCase macintosh Mac
  -        BrowserMatchNoCase MSIE InternetExplorer</PRE>
  -<P>This will set environment variables ``Mac'' and ``InternetExplorer'' to true,
if the
  -client is running Internet Explorer on a Macintosh.</P>
  -<P>Then, in your SSI-enabled document, you might do the following:</P>
  -<PRE>
  -        &lt;!--#if expr=&quot;${Mac} &amp;&amp; ${InternetExplorer} --&gt;
  +        BrowserMatchNoCase MSIE InternetExplorer
  +</pre>
  +
  +<p>This will set environment variables ``Mac'' and ``InternetExplorer''
  +to true, if the client is running Internet Explorer on a Macintosh.</p>
  +
  +<p>Then, in your SSI-enabled document, you might do the following:</p>
  +
  +<pre>
  +        &lt;!--#if expr="${Mac} &amp;&amp; ${InternetExplorer}" --&gt;
           Apologetic text goes here
           &lt;!--#else --&gt;
           Cool JavaScript code goes here
  -        &lt;!--#endif --&gt;</PRE>
  -<P>Not that I have anything against IE on Macs - I just struggled for a few hours
last
  -week trying to get some JavaScript working on IE on a Mac, when it was working 
  -everywhere else. The above was the interim workaround.</P>
  -<P>Any other variable (either ones that you define, or normal environment variables)

  -can be used in conditional statements. With Apache's ability to set environment
  -variables with the <CODE>SetEnvIf</CODE> directives, and other related directives,
this 
  -functionality can let you do some pretty involved dynamic stuff without ever 
  -resorting to CGI.</P>
  -<P>
  -<HR>
  -<H1><A NAME="conclusion">Conclusion</A></H1>
  -<P>SSI is certainly not a replacement for CGI, or other technologies used for
  -generating dynamic web pages. But it is a great way to add small
  -amounts of dynamic content to pages, without doing a lot of extra work.</P>
  +        &lt;!--#endif --&gt;
  +</pre>
   
  -</BODY>
  +<p>Not that I have anything against IE on Macs - I just struggled for a
  +few hours last week trying to get some JavaScript working on IE on a
  +Mac, when it was working everywhere else. The above was the interim
  +workaround.</p>
  +
  +<p>Any other variable (either ones that you define, or normal
  +environment variables) can be used in conditional statements. With
  +Apache's ability to set environment variables with the
  +<code>SetEnvIf</code> directives, and other related directives, this
  +functionality can let you do some pretty involved dynamic stuff without
  +ever resorting to CGI.</p>
  +
  +<hr>
  +<h2><a name="conclusion">Conclusion</a></h2>
  +
  +<p>SSI is certainly not a replacement for CGI, or other technologies
  +used for generating dynamic web pages. But it is a great way to add
  +small amounts of dynamic content to pages, without doing a lot of extra
  +work.</p>
  +</body>
  +</html>
   
  -</HTML>
  
  
  

Mime
View raw message