Use these to jump around or read it all…
[Can You Run SSI?]
[Types of SSI]
[The Include Command]
[The File Argument]
[The Virtual Argument]
[The Included File]
SSI: Server Side Include
This is a topic that has been requested over and over again by readers. Server Side Includes (SSIs) are PERL language-based commands that allow information to be gathered from the server. It works a lot like ASP.
Actually, I should say ASP works a lot like this, as this was around first. The concept is to use the server to gather and post information. That way you’re not dealing with browser version problems. The thing that is being included is included before it gets to the browser so versions never come into play.
Most UNIX servers are set up to run SSI. Those of you on WindowsNT-based servers might have to go with ASP to get a lot of these effects, but check first before you decide you can’t run these commands. You might be able to.
Can You Run SSI?
The easiest way to check is to post a file that tried to grab something from the server. Copy what is below and paste it into a document.
<HTML>
<TITLE>Test File</TITLE>
<!–#config timefmt=”%A” –> <!–#echo var=”DATE_LOCAL” –>
</HTML>
Save it as an HTML file and upload it to your server. Then use your browser to look at it. You should see the current day name (Monday, Tuesday, Wednesday… you get the idea). If you see the day name, you’re good to go.
If not, try saving the file with the extension .shtml. See the “s” I stuck in there? That “s” acts as a parsing command alerting the server that there’s something on the page it has to play with.
Many servers are configured to parse all pages thus you probably won’t need to set the page to .shtml, but you might.
If both attempts fail, you can try contacting your server people to see if they’ll configure the server for you, but they probably won’t or they would have already.
If it works, read on. You’re in for some good commands ahead.
Types of SSI
There are an absolute slew of Server Side Include commands. In order to keep this tutorial from being just a mind-numbing run of text, I have broken it into three sections:
- Commands that include another file (this tutorial)
- Commands that display dates and time from the server (Click Here)
- Commands that display file information (Click Here)
The Include Command
When you mention SSI, this is the event most people think of. Here’s the concept:
You have 500 files on your Web site. At the top of each of the files is a greeting that you’d like to change daily. You could either go into every page, every day, and change the greeting or you could have a text file that each of your 500 files include. Then you would change just that one text page and all the other pages would update. That’s the concept of the include command.
Every page on the HTML Goodies Web site uses include commands, but you’d never know it by looking at the source code. When you View Source on one of the Goodies pages, there is text and coding galore before you actually get to the meat of the tutorial. I don’t write any of that. I use an include to get the job done. Two lines of code, and all that text just magically pops in there.
Here’s how you do it.
The File Argument
Under the heading of the include command there are two arguments. These arguments work much the same as an attribute under an HTML tag. An example would be the SIZE attribute under the FONT tag.
The format of any include command line looks like this:
The command (in this case “include”) is followed by the argument (in this case “file”) and then what “file” represents.
Sharp-eyed HTML folk will notice that the format looks a lot like an HTML comment. Basically, it is. This command line will not appear on the page. What will appear is the file it represents.
Please Note This:
The format for these SSI command lines is not at all forgiving. You must do the coding correctly or it simply will not work. If it doesn’t work, there’s no error message to help you. You’re left high and dry and wondering what the heck is wrong. Try very hard to get it right the first time.
Follow these rules:
- Commands and arguments are in lowercase letters
- The double quotes around the value are required
- There is no space until after the command
- That hash mark (#) is required
- There is a space after the second double quote, before the second double hyphen (at the end)
That’s not being too picky is it?
That said, let’s look at the format of the File Argument:
The format above will create an SSI that will include the text found in the file “included.html”.
Why Use “file=”?
You use “file=” when the file that will be included is held within the same directory as the file that is calling for it. You can also use the file argument when the file is within a subdirectory of the directory containing the file that is calling for it. This is the one I use every time I create an SSI.
The Virtual Argument
You would use the virtual argument if the file you are calling for is located in a position requiring an address starting at the server root. That’s an academic way of saying the file isn’t in the same directory as the page that’s calling for it.
Maybe you’ll set up a directory unto itself that contains all of your include files. This is a popular method of doing things. If so, then you’ll use the virtual argument to attach the SSI command to the files. Just make a point of giving the command the path from the server root (the domain name). Like so:
That forward slash before the first directory is representative of the domain name (server root). By using that leading slash, the server will add the domain name to the front of the address for you.
Rule of Thumb
Use “file=” when the included file is within the same directory as the page that wants it. Use “virtual=” when it isn’t.
The Included File
Let me talk about the file that will be included before wrapping this up. I like to use HTML files to include, but you don’t have to. You can use a simple .txt text file. I like to use .html files because if they are hit upon by accident, they display. It may not be a good reason, but it’s why I do it.
Please do not think that because the file that is being included is set to the extension .html that it has to be a fully formed HTML document. It does not. If all you want to include is one line of text, then that’s all that should be on that file. If you include a title and a body command and all the other items required of a traditional HTML document, all of that will be included in the SSI and you do not want that.
So… in the file you are setting up to be included, put only what you want to be included in that file, nothing more. Yes, it’ll look sparse, but remember that it should not be standing on its own anyway. It is to be included in another fully formed HTML document.
That’s That!
I want to remind you that I have two other tutorials dealing with SSI Dates and Times and SSI File Returns. Take a look at them both. I think you’ll find them useful.
Good luck with these. I hope your server allows you to play with them!
Enjoy!
[Can You Run SSI?]
[Types of SSI]
[The Include Command]
[The File Argument]
[The Virtual Argument]
[The Included File]
