| <!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> |
| <!-- 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 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="#today'sdate">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 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/mod_mime.html#addhandler">AddHandler</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> |
| |
| <hr> |
| <h2><a 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 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.</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 |
| 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 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 name="today'sdate">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 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 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 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 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>ctime</code>. The syntax is the |
| same.</p> |
| |
| <hr> |
| <h2><a 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 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 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 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 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="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 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 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> |
| |