Using the include Command
The include command is where it all started for SSIs. Someone said, “I want to include another file in my HTML and I don’t want to have to cut and paste every time I need to include it in my file.” Of course, the signature file is the most common use for the include command and, overall, the include command can make your task as a Web page builder and Administrator much easier. Used properly, the include command can dramatically decrease the amount of HTML that you have to write and modify.
With the include command in your toolbelt, you will never type your ending copyright notice or signature into your Web HTML again. Figure 3.3 shows the inclusion of my company’s signature on a business Web page. When I added my company’s tag to this Web page, I did not type it in; I used this SSI:
Figure 3.3 : Including a signature file.
<!--#include virtual="/include_files/pi_signature.html" -->
Analyzing the include Command
The SSI include command has two values for the command-argument parameter.
Remember that the syntax of all your SSI commands starts out the same:
<!--#command cmd_argument="argument_value" -->
The two command arguments for the include command follow:
- file: Any path and filename that is in the current directory or a subdirectory of the current directory.
- Virtual: Any path and filename that begins at the server root.
Both the command arguments are used to tell the server how to find the file you want to include. The difference between the virtual command argument and the file command argument is the location from which the server starts its search for the include file.
Using the virtual Command Argument
When you use the virtual command argument, the server begins its search for the file from the document root directory. The document root directory is defined by your System Administrator and can be found in the srm.conf file. You also can find out what the document root is by printing your CGI environment variables. Environment variables are covered in Tutorial 6 “Using Environment Variables in Your Programs.”
The argument value for the virtual command argument always should begin with a forward slash (/). The complete path to the file is required when using the virtual command argument.
The syntax of the include command when using the virtual command argument follows:
<!--#include virtual = "/full pathname/filename.html" -->
Using the file Command Argument
The file command argument should be used when including files that are in the same directory the SSI file is in (the current directory) or a subdirectory of the current directory.
When using the file command, you cannot include a pathname that begins above the current directory. In other words, any pathname that begins with ../ is illegal.
| Tip |
|
You cannot include CGI programs using the SSI include command, but you can include other SSI parsed files. This gives you a tremendous amount of flexibility, because your included files can execute SSI commands also, including executing a CGI program. In the next section, you will use this technique to show how each article in an electronic paper can identify when it was last modified.
