Staff + Student LoginXSSI Scripting: Introduction
The following guidelines are to help developers new to the Apache Extended Server-Side Includes get up to speed with the technology to be able to use on a site hosted on one of the ITS managed web servers. The reader is assumed to have prior experience in at least one programming language.
Many of the sites currently hosted on the ITS web servers currently use the Apache XSSI module to enable some basic on-the-fly content element generation and to facilitate better separation of content and style. We also use XSSI to select stylesheets to suit the browser type of a page visitor and to dynamically change page layout to better suite to printing without the author having to create a copy of the page and content for that purpose.
Any page that ends with the extension .shtml is generally XSSI enabled and should be able to use the scripting examples demonstrated following. Please email the webteam if you're uncertain whether your site is able to use XSSI.
When a page is requested by a visitor to the website any XSSI commands embedded in that page are interpreted by the web server before the page is returned. The commands are never seen by the visitor, only the results of them being interpreted. The following code examples are only visible to authors on our site who are able to view the actual source of the pages as they are stored on our web-server.
Most of our XSSI use is based around setting variables to contain HTML strings and then echoing these strings later at strategic spots within the document. We also use a number of if-then-else loops to test values of server and SSI variables and conditionally perform further actions.
Following are examples of common usage of XSSI in the ITS include-based publishing mechanism:
- Setting Variables
- Displaying Variables
- Combining Variables
- Server Variables
- Testing Values
- Resources
1. Setting Variables
The
following example sets a variable we will later refer to as $styleSheet to
contain the HTML necessary for a browser to request a CSS file as the page we
generate is loaded...
<!--#set var="styleSheet" value="<link rel='stylesheet'
href='/css/uow_2002.css'
type='text/css'>" -->
Things to Note:
- The whole statement is encapsulated by a standard HTML comment tag, i.e.
it begins with
<!--and ends with-->. - The first character after the opening comment tag is always the pound or
hash symbol '
#' followed immediately by any of the known SSI commands,setin this case. If this is not the case the whole line will be ignored. - The
#setcommand is used to create container variables. The first parametervarspecifies the name of the variable to create and the second parametervalueis its contents. - Each parameter value is encapsulated in a double quote pair, and single quotes are used inside the double quotes if any quoting is required inside the value (e.g. for HTML attributes like the rel one given in the example above)
2. Combining Variables
If we have an existing variable we can concatenate its value before or after
another variable to create a single variable which we might use elsewhere. The
following example takes the $styleSheet variable created above and
adds it to a new variable $headSection...
<!--#set var="headSection" value="$styleSheet" -->
Things to Note:
- When we refer to a variable within a
#setstatement we must prefix its name with the'$'character - Variable names are case-sensitive. When referencing an XSSI variable you must use exactly the same case mix you used when you set the variable.
3. Displaying Variables
After you've created a variable you can then display or echo its value within
a page that uses XSSI. Following is an example of an #echo which
will display the HTML we've set in our $headSection variable above
in the <HEAD> section of our SHTML page (note, the rest of the page is omitted
for brevity)...
<HEAD>
<TITLE>My SSI Page</TITLE>
<!--#echo encoding="none" var="headSection" -->
</HEAD>
Things to Note:
- The
#echocommand has a similar format to the#setcommand, except its parameter names are different - The first parameter tells the XSSI processor not to escape HTML into special HTML entities, this is important when your variable actually contains < and > brackets found in HTML.
- The second parameter is the name of the variable we want to
#echointo place on our page, we do not need the '$' in this case.
4. Server Variables
The XSSI module also provides some server variables that are generated for you that you may like to use to display within your pages, examples include...
| Name | Purpose |
|---|---|
| DATE_LOCAL | The local time of the server providing your page |
| LAST_MODIFIED | The last modification date of the document requested by the user |
| HTTP_REFERER | Address of any page a user clicked a link on to visit your page |
| HTTP_USER_AGENT | The browser ID of the visitor requesting your page |
The following example demonstrates how you might provide a paragraph in your page that shows the browser type the visitor is using to visit your page...
<!--#set var="browser" value="${HTTP_USER_AGENT}" -->
<p>Your Browser is: <!--#echo var="browser"
--></p>
Things to Note:
- Because these server variables are special variables we need to enclose them in curly brackets when referencing them, as in the above example.
5. Testing Values
Sometimes we need to be able to test the values of XSSI variables to be able
to set others. The first example following checks a variable
$prefCoaDisplay that we would have set earlier and if it contains the
string 'none' will blank out whatever value the variable $branding
previously contained..
<!--#if expr="$prefCoaDisplay = /none/" -->
<!--#set var="branding" value="" -->
<!--#endif -->
Things to Note:
- The XSSI command in this case is the
#ifcommand which must have a corresponding#endif - The first parameter of the
#ifcommand isexpr, and its value is an expression which the XSSI processor will run to test the variable following the '$' character looking for the string between the two forward-slashes. - The
#setcommand nested inside the#ifand#endifcommands is only run if the conditional test is successful
The following more complex example checks to see if our custom variable
$options contains the string "printver" anywhere within its content OR if
the variable $prefDisplay is an exact string match for "text"..
<!--#if expr="$options = /printver/ || $prefDisplay = text " -->
<!--#set var="headStyle" value="$headStyle
body { background-image: none }
" -->
<!--#else -->
<!--#set var="headStyle" value="$headStyle
body {
background-image: url(http://www.waikato.ac.nz$imgBackground);
}
" -->
<!--#endif -->
Things to Note:
- The
#ifcommand now include an#elseclause which itself contains other nested SSI commands - The
exprstatement now has an OR operator which combines two tests into the one expression using the '||' characters. You may also perform an AND using '&&' - The two
#setstatements both have values which continue across multiple lines, this is a useful way to format the output so that it is easier to read, both in the SSI file and in the resulting HTML output to the browser. The only requirement is that you must end the value parameter with the" -->sequence at some point before your next SSI command
6. Resources
The above examples demonstrate typical uses of XSSI in our environment. For a more detailed look at the XSSI functionality you should make yourself familiar with the following (especially the Apache documentation). If you have further questions you should then contact the webteam...
