diff options
Diffstat (limited to 'APACHE_1_3_42/htdocs/manual/howto/ssi.html.en')
| -rw-r--r-- | APACHE_1_3_42/htdocs/manual/howto/ssi.html.en | 548 |
1 files changed, 548 insertions, 0 deletions
diff --git a/APACHE_1_3_42/htdocs/manual/howto/ssi.html.en b/APACHE_1_3_42/htdocs/manual/howto/ssi.html.en new file mode 100644 index 0000000000..78c2e68d1f --- /dev/null +++ b/APACHE_1_3_42/htdocs/manual/howto/ssi.html.en @@ -0,0 +1,548 @@ +<!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> + </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="#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 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/mod_mime.html#addhandler">AddHandler</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 <a + href="../mod/mod_include.html">mod_include</a> installed and + enabled. Additionally, 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 + 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 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="today'sdate" 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 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 + <a href="../env.html">environment variables</a>, or some of the + variables we discussed above (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> + </body> +</html> + |