Server Side Includes

14th of August, 2008

One of the oldest and simplest techniques for creating dynamic Web pages is the use of Server-side Includes (SSI). First demonstrated in Apache, most other Web servers support SSI using the Apache syntax.

Freeway will automatically create the necessary code to allow you to use server-side includes. You will need to be sure you understand what is going on in an include, though, or you will either have some unintended results, or simply get confused. It is very simple once you grasp the concept.

How does it work?
At the most basic level, SSI works by taking a fragment of HTML or an image from one file and including it into an HTML page when the page is served. A simple example would be a home page where you wanted a different message to appear from time to time. You could edit the entire home page (or let your client do that – shudder!) or you could include the message from a simple text file, and only edit the text file when you had changes.

The key thing to grasp is that there is a page which is requesting the include file (call that the template, to keep it straight in your head) and the include file itself. When the server encounters a request for an include file within your template, it looks for that include at the location you have specified for it, and if it finds the file, it merges it seamlessly with your template. From the browser's perspective, only one file is returned.

What do you need?
There are three major requirements for using includes: your server and ISP must support it, you must name your files correctly, and you must make certain that all of the files are correctly made.

Your ISP can tell you if your Web server supports SSI, and if so, what filename extensions are required. By default, Web servers do not read through the pages they serve – they simply get them from the filesystem or server cache and send them to the browser as fast as they can. By using a different filename extension for the files than .html, you signal to the server that it must actually read through the HTML and look for (and follow) commands before sending the page. This is called "parsing" the page.

Most Web servers allow you to use .shtml as your signal that the page must be parsed. Your ISP can tell you exactly how their server is configured. Some ISPs even set their server to parse ALL pages, even though this imposes a slight performance drag on the server.

By tradition, the file you include is named with a .inc extension. But this can be anything at all: .txt, .html, .foo. Using .inc helps keep things straight in your head, which is why it is traditionally used.

It is very important that this included (.inc) file not be a complete Web page! Most browsers will not complain, and may even show you the completed page as you had intended it, but if you look at the source of the page as it is served to you, you will see that it has the normal beginnings of a page: HTML, HEAD, /HEAD, BODY, some content, and then another complete set of HTML, HEAD, /HEAD, BODY etc. This will confuse some browsers to the point that nothing is displayed. Your .inc file can contain any valid HTML, but it must not have the HTML or HEAD or BODY tags on it. Fortunately, there is an action which will strip these off for you. See this KB article for details.

Includes in Freeway
Now that you have all of your background on the subject, here's how to do includes in Freeway. For this example, we will be creating a page in Freeway, and including the content of a single simple text file into that page. The client will be allowed to edit this file, and post the current menu for the lunchroom on that page.

Create Your Page
In Freeway, create a new page in your site. With nothing on the page selected, click in the Filename well of the Inspector, and change it to read "menu.shtml". Sketch your layout, including an HTML box in the middle for your included menu.

Create Your Include
Now create a text file using any plain text editor, like TextWrangler, SublimeText or BBEdit. Your client will be editing this, so it's best to keep it simple. Our example will look like this:



<pre>
Menu for Friday, May 25th:
Braised Pork Loin
Spinach Souffle
7-grain Roll
Caeasar Salad with Sourdough Croutons
Fruit Plate
Almond Cookies
</pre>

(The <pre> tags in this example allow you to avoid any sort of HTML formatting at all – line breaks in the text are honored, and the text is shown in a monospaced font, so you can even create tabular data by simply using spaces to align the text.)

Upload this file to your Web server. Ideally, you would put it in a different folder from the rest of your site, and ask your ISP to set up a separate login for you client that would only allow her access to that one folder. For this example you will put the file in the same folder as your site files.

Include the File
Back in Freeway, select the HTML box you placed on the page where you want the include to display (Apple-Click on the edge of the box, so the selection handles appear. If you click inside the box, you will get a text cursor, which is not what you need.) In the Inspector, select the left-most tab and change the Type picker from HTML to URL. In the URL field, type the full name to your include file. If you have located that file somewhere other than in the folder with your HTML files, you will need to add a relative path to the file. For example, if you placed the file in a folder named "includes" inside your web root folder, and your page is at the top level of that same root folder (this is where it gets tricky) you have to add the folder to the filename, like this: "includes/menu.inc". If your template page is itself in a folder, you will have to traverse the file structure, moving up a level, then back down into the includes folder, like this: "../includes/menu.inc" (if the template is in another folder at the same level as the "includes" folder).

The Result:
Upload your Freeway file to the server (you cannot preview this sort of thing locally) and you should see your combined page, with the menu appearing in the middle of your template page.