Help

CodingForums
Having trouble with scripting? Visit our help forum to get the answers you need.

Partners
This is a

Ada's Introduction to SSI

SSI is a very useful component of CGI. Using it, you can dynamically embed content onto your webpage or even across your entire site. It is a very handy feature. Better yet, you don't need to know one line of Perl programming to harness and use SSi on your site!

-Overview of SSI

SSI, or Server Side Includes is basically a feature of CGI (in conjunction with your server) that allows you to dynamically insert a piece of information (such as the current date, any HTML file etc) onto any webpage, and have the browser display it as if it was hard coded onto that page. Let's say you're interested in displaying the current date and time on the top of your webpage. Simply by adding one simple SSI code onto the page (<!--#echo var="DATE_LOCAL" --> ), this is accomplished. The ugly alternative would be to manually edit your webpage and change the date to the current one each and every day. Starting to let SSI, are we? And that's just the beginning!

-What do I need to use SSI on my site?

Your web host must support SSI parsing on its' servers in order for you to be able to use SSI on your site. How can you find that out? Simple. Do the SSI test on it!

1) Create a webpage, and put the code <!--#echo var="DATE_LOCAL" --> inside the <body> section of the page.
2) Save and name that page as "test.shtml"
3) Upload the page, and view it using your browser
4) If you see the current date displayed, your webhost supports SSI.

If you don't see the date, then most likely your web host does not support SSI. Of course, the SSI test is not fool proof, so you should ask your site administrator if you're unconvinced.

-Ok, I know my server supports SSI...now what?

Now, you learn what SSI can do, and exactly how to use SSI on your web site. One thing at a time, though.

First and foremost, for all pages that you intend to use SSI on, you'll need to rename those pages from the usual .htm or .html extension to .shtml. For example, index.html should now be called index.shtml. On most servers, this is the only way the server will know that it should parse and respond to the SSI commands on that page.

Assuming that's understood, lets get to the meat of the matter, then. What can SSI do, and why should I use it? Here are some of the most useful things you can do with SSI:

  • Display the current date and time (in many formats)
  • Display the last modified date of a webpage
  • Include a document inside another
  • Execute a CGI script or command directly from the webpage

Ok my furry friend, let see how to do each of these things...

-Display the current date and time

To display the current date and time, add the following SSI code to your webpage:

<!--#echo var="DATE_LOCAL" -->
CODE PURPOSE OF CODE
%a abbreviated weekday name
%A full weekday name
%b abbreviated month name
%B full month name
%c locale's appropriate date and time
%C default date and time format
%d day of month - 01 to 31
%D date as %m/%d/%y
%e day of month - 1 to 31
%H hour - 00 to 23
%I hour - 01 to 12
%j day of year - 001 to 366
%m month of year - 01 to 12
%M minute - 00 to 59
%n insert a newline character
%p string containing AM or PM
%r time as %I:%M:%S %p
%R time as %H:%M
%S second - 00 to 59
%t insert a tab character
%T time as %H:%M:%S
%U week number of year (Sunday is the first day of the week) - 00 to 53
%w day of week - Sunday=0
%W week number of year (Monday is the first day of the week) - 00 to 53
%x Country-specific date format
%X Country-specific time format
%y year within century - 00 to 99
%Y year as CCYY (4 digits)
%Z timezone name

There are ways to customize the format of this output. Take a look at the right table, and the following examples to see how to do just that.

Code: <!--#config timefmt="%m/%d/%y" -->
Sample output: 05/24/05

Code: <!--#config timefmt="%H:%M:%S" -->
Sample output: 23:59:01

Code: Today is <!--#config timefmt="%A -->
Sample output: Today is Friday

Piece of cake, right?

-Display the last modified date of a webpage

To display the last modified date of a webpage, add the following SSI code to it:

<!--#flastmod file="ssi.htm" -->

-Include a document inside another

This must be one of the most useful features of SSI- the ability to include one document inside another.  The SSI code for this is:

<!--#include file="myfile.htm"-->

Put that anywhere in your webpage, and myfile.htm shows up in it's place. The file doesn't have to be a ".htm" file. It could also be a ".txt" file (ie: myfile.txt). So how is this useful? Let's say you have a peice of content that is repeated on many pages of your site (a navigational bar, for example). By saving that content as an individual html file, and using SSI instead to include that content onto those pages, updating that content becomes merely changing that ONE file. The changes is instantly reflected on all pages containing the SSI include command. The ugly alternative, again, would be to manually edit the navigational bar for each and every page containing it. On sites with hundreds or even thousands of pages, prepare to camp out in front of your computer!

-Execute a CGI script or command directly from the webpage

Last but not least, SSI allows you to execute a CGI script or command directly from the webpage. This is where SSI becomes not only handy, but critical, in many cases. It's not a feature you would use by itself, but in conjunction with a CGI script you have installed. You see, many CGI scripts require that it be called directly from the webpage, which only SSI can do. In other words, in order to get some CGI scripts to work, you must use SSI. The SSI code to call a CGI script from the webpage is:

<!--#exec cgi="/cgi-bin/myscript.cgi"-->

Of course, you'll need to change "myscript.cgi" to the script you're trying to call. Ok, so when do you need to call a CGI script, then? If and when the CGI script you're using asks for it!  For example, many hit counter or stats scripts require the use of the above SSI call in order to function. Poll and survey scripts too. Just know that when the scripts says you need SSI in order to use it, it means what I'm talking about here.