
	Resources

DIWE - Interchange

News - ListServs

Research

Surfing the Web

Computer E-mail

Super Search


	Information

UIC Students

Instructors

Associates

SCAILAB Classrooms

SCAILAB MOOn


	Learning

Closed

SCAILAB - Student Computer Aided Instruction Lab

XSSI Tutorial

You just clicked yellow. Click here to jump to the yellow square in this document.

XSSI (Extended Server Side Includes) is available free with Apache web server open source and binary versions. XSSI uses conditions, variables, and commands to return a desired output from the server to the client.

First we will look at the standard XSSI environmental variables shown below, some are from the previous NCSA SSI, then we move into using XSSI to perform logical tasks. An example of the output is shown for each example. To use the code you see on the page copy the text from the text box, and paste it into the body of an html document saving as .shtml. This tutorial assumes you understand basic programming syntax.

For any of these examples to work you need XSSI, and you must save the HTML document as .shtml. UIC student accounts have this service.

Environmental Variables

HTTP_REFERER - This is the page you came from.

HTTP_REFERER = (none)

HTTP_USER_AGENT - This is your browser.

HTTP_USER_AGENT = CCBot/1.0 (+http://www.commoncrawl.org/bot.html)

QUERY_STRING - This is a string passed to the server from the client.

QUERY_STRING = yellow

PATH_INFO - URL with extraneous directories at the end

PATH_INFO = (none)

DATE_GMT - The date and time.

DATE_GMT = Tuesday, 24-Nov-2009 10:13:35 GMT
DATE_LOCAL = Tuesday, 24-Nov-2009 04:13:35 CST

DOCUMENT_NAME - The document name of the document your viewing.

DOCUMENT_NAME = tutorial.shtml

DOCUMENT_URI - The document path relative to the web server root.

DOCUMENT_URI = /depts/scailab/system/tutorial.shtml

Time config - Configures time to the options shown below using timefmt(time format).

Today is Tuesday

Notice %A, if you changed it to %a then you would see the abbreviation for today.

%% - %
%a - Wed: Day of the week abbreviation
%A - Wednesday: Full name of day of the week
%w - 3: Number of day of the week; Sunday is day 0 (0-6)
%b - Oct: Month abbreviation
%B - October: Full name of month
%d - 29: The day of the month (01-31)
%e - 29: The day of the month (1-31)
%H - 19: Hour of day (00-23)
%I - 07: Hour of day (01-12)
%j - 302: Day in the year (001-366)
%M - 37: Minute (00-59)
%p - PM: AM or PM
%S - 44: Second (00-61); watch your leap seconds
%y - 97: Last two digits of the year (00-99)
%Y - 1997: The year
%Z - PST: The time zone

Did you notice the echo command? This prints the environmental variable to the page before being returned to the client. More on echo in a moment.

XSSI Tutorial

When you see XSSI markup, server side html markup, or tags in this documentation, I am referring to the tags similar to this structure . I use it interchangeably throughout this document so be aware of it. Also I refer to expr as an expression. and the entire line of code from  as an element. This tutorial does not cover <, >, <=, >=, !=, =, and == in programming languages. If you don't know this you may experience confusion.

Now we will look at basic programming available in XSSI. An example is shown after each definition. I will do this tutorial in steps with the final example of flow control elements including all the previous examples.

Flow control elements use the following structure in XSSI.

do this if true.


do this if true


do this if the previous elements are false


end the flow control element.

If a elements expression is true it does that, else it moves on to the next element . The expression evaluates the condition in between the quotes to a value true or false.

The elif and else statements are optional, but the endif is required.

A basic example.

First to set a variable in XSSI you simply type within the html

#set var is a XSSI command to define variables.

Lets define a variable to use in the flow control element expressions.
I will spare all from any hello world examples.


The variable's name is testvar and its value is the string uic.

Now lets build the flow control elements.

The code above evaluated by the server and returned to you.
The answer? uic is the string.

What happened to the rest of that stuff? The server removed it after reading the document for any XSSI markups. Take a closer look at the code above. We know the value of the variable testvar is the string uic. The server used the XSSI flow control elements to evaluate the expressions for a match to the string uic. If the server finds a true expression, it keeps the information below this XSSI tag, but removes all other XSSI markup tags and the information between them. The only thing remaining is text, html, or any other browser compatible information. You can use anything compatible with the server as long as the final output sent to the client's browser doesn't error. The else control element gives the server something to evaluate if all other expressions are false. Don't not forget to include the flow control element  last. If forgotten, it will cause problems and errors.

The  is required.

Again, the control element expression evaluates the condition in between the quotes to a value true or false.

What is the $ for? The $ before a name in XSSI is a variable. The $testvar is the variable included in the condition. Of course it could have been $school if I had set the variable name to school. Variables can be used in XSSI conditions and commands.

Example:

Lets use the echo command to print the variable testvar from above to the document.

The code above evaluated by the server and returned to you.
The printed variable = uic

Notice the echo command does not have the $, but the if expr above does. This is because echo is a variable. Look at the tag . You already told the server that testvar is a variable with var="testvar"; echo tells the server to echo(e.g. print it) this variable to the page.

In a condition, if you want to compare the variable testvar to the string uic you need $, otherwise it would compare uic to the string testvar and not the variable testvar. More on strings in a moment.

Variables in control element expressions begin with a $ using XSSI markup.

If your still with me, then lets look at the operators equal, not equal, less than, less than or equal, greater then, greater then or equal used to compare one or more strings using XSSI markup.

string
true if string is not empty
string1 = string2
string1 != string2
string1 < string2
string1 <= string2
string1 > string2
string1 >= string2

Make sure you are aware of how you are comparing the strings.
Some different results can be obtained.
[an error occurred while processing this directive]
HTTP_USER_AGENT = CCBot/1.0 (+http://www.commoncrawl.org/bot.html)

Notice var="browser" value="$(e.g. variable)HTTP_USER_AGENT" below. Look at the variables value above to visualize the element. Use the printed HTTP_USER_AGENT for the variable browser value for reference.

The code above evaluated by the server and returned to you.
The answer? False

What? Take a look at the next example.

The code above evaluated by the server and returned to you.
The answer? False

What is going on here? In the first example, the elements returned a value false since the strings are not identical. In the second example, the elements returned a value true since the strings have common characters between the two.

Look at the following elements for help.


Only true if strings are identical.


True, if string1 contains common characters to string2. If string2 contains common and uncommon characters to string1, then it would have returned the value false.

Example:

HTTP_USER_AGENT = CCBot/1.0 (+http://www.commoncrawl.org/bot.html)

The code above evaluated by the server and returned to you.
The answer? False

For these examples the brackets are not needed. I would use brackets for an environmental variable within an elements expression. I could have just removed the set command from these examples, and replace browser with HTTP_USER_AGENT enclosed in brackets. brackets in Perl can become confusing and are beyond the scope of this tutorial. Just follow the rule, if your using an environmental variable inside an elements expression, enclose it with brackets.

You can use these two plug-in info control elements using the above examples as guides.

Only true if identical.

True if string2 contains common characters as string1 and no other uncommon characters.

The slashes?

The first example uses the back slash to bind the strings being compared. It tells Apache to ignore the quotes within the quotes. This is why the expression is true only if the strings are identical.

The forward slashes around string2 in the second example tells Apache to match string2 as a regular expression. This is why the second example returns a true if string2 contains common characters as string1 and no other uncommon characters.

Note: Conditions use the backslash character ("\") to indicate special forms or to allow special characters to be used without invoking their special meaning. If you use a character in the set command such as var="temp" value="$varname", then for any conditions using this variable would need backslash quoting.
 the $ would be ignored using back slashing and interpreted as a string.

If you use these pre-made control elements, make sure you leave the slashes and the quotes as is using the above examples as guides. Use the same browser you are presently using if you try these examples.

A little tough if your new to programming. Be careful comparing strings.

Now the flow control element expressions with two or more conditions.

( test_condition )
true if test_condition is true
! test_condition
true if test_condition is false
test_condition1 && test_condition2
true if both test_condition1 and test_condition2 are true
test_condition1 || test_condition2
true if either test_condition1 or test_condition2 is true

This allows the elements to use two or more conditions possible in an expression.

Lets take a look at an example using expressions with two or more conditions and the final output returned to the client.

First I define a variable using the #set var and config command. I will use one of the environmental variables.


I configured time format to month full name. You might want to format the date to the desired string before assigning it to a variable. See above time config.


Now I set the variable name month to the environmental variable DATE_LOCAL after it was formatted.

Finally build the flow control elements with multiple conditions.

This is fall term

I could use either methods of comparing strings shown above since I formatted the string variable month holds. In other words, I know what the possibilities are with no margin for error. I chose the second method since its easier to read. Once again be careful of the how you use the different versions I provided.

Lets look at this XSSI markup carefully.

This is fall term

If the variable month ( a string assigned to the formatted environmental variable DATE_LOCAL ) is equal to the string September, or October, or November, the server leaves the text "This is fall term", but removes the other elements and information.

Look at the code again below.


See the two lines || between each condition? This is a logic OR.

If the condition ($month = /September/) is true, or the condition ($month = /October/) is true, or the condition ($month = /November/) is true, then the expression is true. This means if one of the combined conditions is true, then the expression is true for this example.

The logic OR combines different conditions.

Lets take a look at the logic AND.


This is fall term

If the variable month ( a string assigned to the formatted environmental variable DATE_LOCAL ) is equal to the string September, and October, and November, the server leaves the text "This is fall term", but removes the other elements and information.

Look at the code again below.


See the two && between each condition? This is a logic AND.

If the condition ($month = /September/) is true, and the condition ($month = /October/) is true ,and the condition ($month = /November/) is true, then the expression is true, else its false. This means all conditions must be true for the expression to be true. This expression would always be false for this example using the logic AND. Think about it.

The logic AND combines different conditions.

Notice I used the word if, when explaining the conditions above. Think of it like this.

Combining both logic AND & OR in the same expression.

Example:


This is fall term

If the variable month is equal to the string September, and October, or November, the server leaves the text "This is fall term", but removes the other elements and information. If ($month = /November/) is true, or ($month = /September/) && ($month = /October/) is true, then the expression is true.

We also can use braces to control the order of evaluation for multiple conditions.

A second example:


This is fall term

I added an extra open and close brace around October and November to control the order of evaluation. If the variable month is equal to the string September, and (October, or November), the server leaves the text "This is fall term", but removes the other elements and information. If (($month = /October/) || ($month = /November/)) is true, and ($month = /September/) is true, then the expression is true.

Once again for review.

Using a logic && to combine conditions; all conditions must be true for the expression to be true, else its false.

Using a logic || to combine conditions; only one condition needs to be true for the expression to be true.

Using a logic AND & OR to combine conditions; a number of different possibilities can make the expression true.

Simply said, The logic AND/OR can combine two or more conditions in an expression. An expression uses a condition to return a value true or false for the element in XSSI markup.

Back to the flow control elements.





This is fall term

This is added to the document by the server given this expression is true, or it moves on to the next element. Remember the only thing returned to the browser is the result of the evaluated code and all XSSI markup is removed.

The remaining control elements for the months of the year.


This is winter break

This is spring term

This is summer term

Server error, please try to reload

<br>

The code without comments.

The code above evaluated by the server and returned to you.
The answer? This is fall term

We will now look at including a document, executing a cgi script on the server, passing a value from the client, browser sniffing and custom error messages.

If I wanted to include another document into this document; I would simply add this to the html and save as .shtml.

Notice you can include another document with XSSI markup for the server to read and evaluate. The .shtml tells you it contains XSSI markup.

This text below was included with XSSI.

This is really easy

Be sure only html markup language between the <body> tags is used for documents included. You don't want to repeat <body>, <html>, <head> etc. this will cause errors on some browsers.

Note: For tech guys I realize virtual include is a SSI available in XSSI.

The most powerful feature of XSSI is the ability to execute a cgi script on the server, and have the results included in the document before being returned to the client. This opens XSSI to powerful programming languages such as Perl to perform complex tasks.

Its quite simple. Just add this to your document.

Notice the path for the XSSI.

If you have been wondering, this is how you can perform complex mathematical equations, conditions, and object oriented programming using XSSI and Perl without the documents being requested from the cgi-bin.

No example is available since I do not have access to a cgi-bin. Its probably disabled on UIC's server.

ALL TOGETHER NOW

Now to demonstrate the ability of passing a variable to the server from the client using the environmental variable QUERY_STRING, a string compare, and multiple conditions in elements expressions with if else statements.

For a QUERY_STRING you simply add a ?someinfo after the requested document name in the html request ( a hyperlink ) to use the QUERY_STRING. Then you define a variable name with the set command and its value to the variable QUERY_STRING.

Example:

The client side
<a href="qstring.shtml?blue">blue</a>.
The string being passed is blue.

The server side

The variable name is color and its value is the variable QUERY_STRING, which in this case is the string blue.

Once again an example will be shown of actual code working.

The code:


I set the variable color to the string passed from the client.


I set the variable nocolor to the string gray for the else statement.

I used some control elements with virtual includes, and multiple conditions in the expressions. The string compare I used is the second example, could have been the first. I already know what the possibilities are for this example, so either would work. Virtual include once again just adds a document to this document before its returned to the client.



<h1></h1>
I printed the variable to the document using echo.





If none of the above expressions are true, then include the document gray.

<h1></h1>


<br>

I added a neat trick to print the document name the client is viewing for the QUERY_STRING using the echo print command and DOCUMENT_NAME environmental variable.

<a href="?blue">blue</a> | <a href="?green">green</a> | <a href="?red">red</a> | <a href="?yellow">yellow</a> | <a href="?black">black</a>

Here this works, but other occurrences using QUERY_STRING it would not. Just be aware of how you are using it.

The code without comments.

The documents and images used are available here. Copy and paste the above code into the body of an html document, save as .shtml, and upload it to a server. Put the file you unzipped into the same directory as the shtml document.

This result of the code is shown below. To see the string being passed click one of the links below the gray square.

yellow

Now click here to see bob.

blue | green | red | yellow | black

You just clicked yellow.

browser version and type is found with XSSI using the following code.

Remember from above the environmental variable HTTP_USER_AGENT?

See if you can read the flow control elements, and visualize what the server is doing using the info below. You have all the tools, now put it together. The example compares the strings as regular expressions.

HTTP_USER_AGENT = CCBot/1.0 (+http://www.commoncrawl.org/bot.html)

The code above evaluated by the server and returned to you.
The browser you are using is [an error occurred while processing this directive] Unknown

Notice how HTTP_USER_AGENT is used above in the conditions. Remember why I used brackets?

Remember I mentioned something about using the same browser for the string compare example. Actually the elements above were used for the string compare to provided the right answers. The string compare examples you were looking at use the commands #set var, #echo, and the browser sniffer for correct answers with any browser. See if you can figure out how I did that?

Finally, You can use custom error messages for XSSI.

The error message is defined using the errmsg command.

Now lets makes an error with XSSI markup.

The error message for this XSSI tag is: I don't have an answer for that

Note. The error message clears itself after the first error, and defaults to the original [error processing this directive thing]. If you want to use this debugging method you need to add a new error message before every XSSI tag to obtain usable results.

Wow you just learned a simple server side HTML language.

For Apaches official documentation on XSSI click on the link. Apache XSSI

Remember to save your XSSI documents with .shtml to insure the server reads the documents for XSSI markup before it is returned to the client. .shtml is normally used, but you can check with your web server administrator to be sure.

Tutorial written by Steven Jensen.

Back to Top