mirror of
https://github.com/apache/httpd.git
synced 2025-10-22 23:12:44 +03:00
d78c998c6a
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@96194 13f79535-47bb-0310-9956-ffa450edef68
549 lines
21 KiB
Plaintext
549 lines
21 KiB
Plaintext
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy, see www.w3.org" />
|
|
|
|
<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">
|
|
<!--#include virtual="header.html" -->
|
|
|
|
<h1 align="center">Apache Tutorial: Introduction to Server Side
|
|
Includes</h1>
|
|
<a id="__index__" name="__index__"></a> <!-- INDEX BEGIN -->
|
|
|
|
|
|
<ul>
|
|
<li><a
|
|
href="#apachetutorial:introductiontoserversideincludes">Apache
|
|
Tutorial: Introduction to Server Side Includes</a></li>
|
|
|
|
<li><a href="#whataressi">What are SSI?</a></li>
|
|
|
|
<li><a href="#configuringyourservertopermitssi">Configuring
|
|
your server to permit SSI</a></li>
|
|
|
|
<li>
|
|
<a href="#basicssidirectives">Basic SSI directives</a>
|
|
|
|
<ul>
|
|
<li><a href="#todaysdate">Today's date</a></li>
|
|
|
|
<li><a href="#modificationdateofthefile">Modification
|
|
date of the file</a></li>
|
|
|
|
<li><a href="#includingtheresultsofacgiprogram">Including
|
|
the results of a CGI program</a></li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#additionalexamples">Additional examples</a>
|
|
|
|
<ul>
|
|
<li><a href="#whenwasthisdocumentmodified">When was this
|
|
document modified?</a></li>
|
|
|
|
<li><a href="#includingastandardfooter">Including a
|
|
standard footer</a></li>
|
|
|
|
<li><a href="#whatelsecaniconfig">What else can I
|
|
config?</a></li>
|
|
|
|
<li><a href="#executingcommands">Executing
|
|
commands</a></li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#advancedssitechniques">Advanced SSI
|
|
techniques</a>
|
|
|
|
<ul>
|
|
<li><a href="#settingvariables">Setting
|
|
variables</a></li>
|
|
|
|
<li><a href="#conditionalexpressions">Conditional
|
|
expressions</a></li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li><a href="#conclusion">Conclusion</a></li>
|
|
</ul>
|
|
<!-- INDEX END -->
|
|
<hr />
|
|
|
|
<h2><a id="apachetutorial:introductiontoserversideincludes"
|
|
name="apachetutorial:introductiontoserversideincludes">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/core.html#setoutputfilter">SetOutputFilter</a><br />
|
|
<a
|
|
href="../mod/mod_setenvif.html#BrowserMatchNoCase">BrowserMatchNoCase</a><br />
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<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 id="whataressi" name="whataressi">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>
|
|
<hr />
|
|
|
|
<h2><a id="configuringyourservertopermitssi"
|
|
name="configuringyourservertopermitssi">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. Note that most configurations contain
|
|
multiple <a href="../mod/core.html#options">Options</a> directives
|
|
that can override each other. You will probably need to apply the
|
|
<code>Options</code> to the specific directory where you want SSI
|
|
enabled in order to assure that it gets evaluated last.</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
|
|
AddOutputFilter INCLUDES .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>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 id="basicssidirectives" name="basicssidirectives">Basic
|
|
SSI directives</a></h2>
|
|
|
|
<p>SSI directives have the following syntax:</p>
|
|
<pre>
|
|
<!--#element attribute=value attribute=value ... -->
|
|
</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 id="todaysdate" name="todaysdate">Today's
|
|
date</a></h3>
|
|
<pre>
|
|
<!--#echo var="DATE_LOCAL" -->
|
|
</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>
|
|
<!--#config timefmt="%A %B %d, %Y" -->
|
|
Today is <!--#echo var="DATE_LOCAL" -->
|
|
</pre>
|
|
|
|
<h3><a id="modificationdateofthefile"
|
|
name="modificationdateofthefile">Modification date of the
|
|
file</a></h3>
|
|
<pre>
|
|
This document last modified <!--#flastmod file="index.html" -->
|
|
</pre>
|
|
|
|
<p>This element is also subject to <code>timefmt</code> format
|
|
configurations.</p>
|
|
|
|
<h3><a id="includingtheresultsofacgiprogram"
|
|
name="includingtheresultsofacgiprogram">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>
|
|
<!--#include virtual="/cgi-bin/counter.pl" -->
|
|
</pre>
|
|
<hr />
|
|
|
|
<h2><a id="additionalexamples"
|
|
name="additionalexamples">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 id="whenwasthisdocumentmodified"
|
|
name="whenwasthisdocumentmodified">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>
|
|
<!--#config timefmt="%A %B %d, %Y" -->
|
|
This file last modified <!--#flastmod file="ssi.shtml" -->
|
|
</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>
|
|
<!--#config timefmt="%D" -->
|
|
This file last modified <!--#echo var="LAST_MODIFIED" -->
|
|
</pre>
|
|
|
|
<p>For more details on the <code>timefmt</code> format, go to
|
|
your favorite search site and look for <code>strftime</code>. The
|
|
syntax is the same.</p>
|
|
<hr />
|
|
|
|
<h2><a id="includingastandardfooter"
|
|
name="includingastandardfooter">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>
|
|
<!--#include virtual="/footer.html" -->
|
|
</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 id="whatelsecaniconfig" name="whatelsecaniconfig">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>
|
|
<!--#config errmsg="[It appears that you don't know how to use SSI]" -->
|
|
</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 id="executingcommands"
|
|
name="executingcommands">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>
|
|
<pre>
|
|
<!--#exec cmd="ls" -->
|
|
</pre>
|
|
</pre>
|
|
|
|
<p>or, on Windows</p>
|
|
<pre>
|
|
<pre>
|
|
<!--#exec cmd="dir" -->
|
|
</pre>
|
|
</pre>
|
|
|
|
<p>You might notice some strange formatting with this directive
|
|
on Windows, because the output from <code>dir</code> contains
|
|
the string ``<<code>dir</code>>'' 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 id="advancedssitechniques"
|
|
name="advancedssitechniques">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 id="caveat" 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 id="settingvariables" name="settingvariables">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>
|
|
<!--#set var="name" value="Rich" -->
|
|
</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>
|
|
<!--#set var="modified" value="$LAST_MODIFIED" -->
|
|
</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>
|
|
<!--#set var="cost" value="\$100" -->
|
|
</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>
|
|
<!--#set var="date" value="${DATE_LOCAL}_${DATE_GMT}" -->
|
|
</pre>
|
|
<hr />
|
|
|
|
<h2><a id="conditionalexpressions"
|
|
name="conditionalexpressions">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>
|
|
<!--#if expr="test_condition" -->
|
|
<!--#elif expr="test_condition" -->
|
|
<!--#else -->
|
|
<!--#endif -->
|
|
</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>
|
|
<!--#if expr="${Mac} && ${InternetExplorer}" -->
|
|
Apologetic text goes here
|
|
<!--#else -->
|
|
Cool JavaScript code goes here
|
|
<!--#endif -->
|
|
</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>
|
|
<hr />
|
|
|
|
<h2><a id="conclusion" 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>
|
|
<!--#include virtual="footer.html" -->
|
|
</body>
|
|
</html>
|
|
|