Server-Side Includes (SSI) Tutorial

SSI: Server-side Includes , a Tutorial
by Justin Watt for Carolina Web Servers (last updated 10-08-01)

What is an HTML document?
- Before creating a webpage (using hypertext markup language or HTML) you have an idea
(1) SEE webdesign.txt (textfile sketch of a simple site design)

- Then you translate your webpage idea from (1) into HTML:
 - You can use a WYSIWYG editor (what-you-see-is-what-you-get) like Dreamweaver or FrontPage
 - Or you can markup by hand, with a simple text editor like Notepad or Wordpad
 - HTML is a standard way to apply formatting to a document using tags in angled brackets
 ex: make text bold
 (2) SEE franklin-st-melee.jpg (jpeg image of kids and fire on franklin street)
 (3) SEE webpage1.html (source)
 (4) SEE webpage1.html (webpage version 1, straight HTML)

- The web browser interprets the HTML tags in (3) and applies formatting to the content they surround, SEE: (4)
- Note: HTML also has structural tags that create tables, frames, and forms

- Question: How could we get the current date and last modified date into the webpage w/o updating it every morning?

What are Server-side Includes?
- Server-side includes (SSIs) direct the webserver to generate content for a webpage every time it's requested
- Note: SSIs only work on Apache (and Apache-compatible) webservers---which run on 50-65% of all webservers

- SSIs are put directly in HTML documents and they resemble HTML comments
ex:  SEE (3) for further examples of HTML comments

    - Putting SSIs in an HTML document requires that the webserver "parse" (or look through) the document
        - Web pages that contain SSIs often end with an .shtml extension, ex: index.shtml
        - The .shtml extension tells the webserver which pages it should parse and which it should not

What does an SSI directive look like?
 - The syntax for an SSI directive looks like this: 
 - If SSI is not enabled on the webserver, the browser will ignore it, but it will be visible in the HTML source
 - If SSI is enabled on the webserver, the directive will be replaced with its results

- An example of an actual SSI directive looks like this: 
- "echo" means write out the "var" (or variable) to the document, in this case, "DATE_LOCAL"

What does an SSI directive do?
- Let's put the SSI directive above into a test .shtml file, surrounded by bold tags ( ... ):

<HTML>
 <BODY>
 
 </BODY>
 </HTML>

- The webserver should process only "", replacing it with the local date/time:

<HTML>
 <BODY>
 04-Feb-2001 23:07:19 EST
 </BODY>
 </HTML>

- The HTML document, now with the local date/time, would then be sent to the web browser
-Note: The web browser will have no knowledge that there was ever an SSI in the HTML source file

(5) SEE: webserverssitest.shtml (Authentic SSI output, testing webserver for SSI capabilities)

- We can also format the date/time ouput by putting this SSI directive above the previous one:
 
 
 -The "%D" above specifies the "mm/dd/yy" date/time format (based on UNIX standards)

- What other variables and time formats are there?
(6) SEE: SSI and CGI variables and SSI Date/Time Formatting

    - Now we know how to pick up with the webpage in (3) and (4):
        (7) SEE: webpage2.shtml (source)
        (8) SEE: webpage2.shtml (webpage version 2 with SSI date/time output and formatting)

- Note how Viewing the Source of (8) from the browser is different than the source in (7)

- A picture of the process from O'Reilly's out-of-print book, CGI Programming on the World Wide Web

Can I get Apache to parse .html documents for SSIs?
    - Yes, of course:
    - Create a text document called ".htaccess" (yes, you need the period, and no, don't add .txt or .html to the end)
    - Put this line in the document "AddHandler server-parsed .html" and save
    - Upload .htaccess to the root directory of your webspace
    - Apache will then parse all .html files
    - Note: you can add other file extensions to that line: "AddHandler server-parsed .html .htm"
        -This will cause Apache to parse all files that end with .html or .htm

So, what else can SSI do for me? Includes.
    - In addition to displaying variables, SSI can:
        - include the results of a CGI program in your webpage
        - execute Unix shell commands (like ls ) and CGI programs
        - set variables and use those variables in comparisons and conditionals (which is very cool!)
        - For info on these more advanced features, SEE: Apache SSI Documentation

    - But wait, there is *one* more amazing thing SSI can do, for which it gets its name:
        - SSI can include a chunk of HTML into another HTML document
        - This is great if you have a site with 12 pages that all need the same menu bar
            -Rather than updating the same HTML in 12 places, use an SSI that includes the menu bar
            -That way, if the menu bar ever needs to be changed, it only has to be changed in one place

- SSI include syntax:  (it's that easy!)

- SEE (7) , look at the clunky header and footer information that obscures the document content
-Imagine designing a newspaper repository that had 10,000 files like that, let alone 12

    - How does it all fit together?
        (9) SEE: navigationmenu.include and pagefooter.include
        (10) SEE: webpage3.html (source)
        (11) SEE: webpage3.html (webpage version 4 with SSI output, formatting, and includes)

- Final Note: Apache parses files before including them, so if you want Apache to parse the .include files:
- Put .include in the "AddHandler server-parsed" line of .htaccess

Sources:
Basic SSI Info: Apache SSI Documentation
O'Reilly CGI book: Chapter 5 Server Side Includes
CGI Variables: http://www.oreilly.com/openbook/cgi/ch02_02.html#CGI-CHP-2-TBL-1
SSI Variables: http://www.oreilly.com/openbook/cgi/ch05_03.html#CGI-CHP-5-TBL-2
SSI Time Formats: http://www.oreilly.com/openbook/cgi/ch05_08.html#CGI-CHP-5-TBL-3