The low-down on #<CODE>include</CODE>s

The low-down on #includes

Introduction
This article is broken down into three parts. The first part explains the basics of server side includes and demonstrates how to use them. Even if you are the bomb at server-side includes, I'd recommend that you read this first part. There are some interesting topics covered (such as how to include files outside of the web directories). The second part discusses the gritty details of server-side includes, the benefits of including files, and naming conventions to use. Finally, part three discusses what dynamic includes are, why you can't use them, and workarounds for simulating dynamic includes.

- continued -

What are #includes?
#include, or server side includes (SSI), allow you to dump the contents of a file into another file. The benefit of including files is that you can group common functions and code into a file, and then just make a reference to that file in all of your ASP scripts that need to use those functions! Using server-side includes allow you to modularize your code; rather than having to rewrite functions, you can write them once and access them easily from all the ASP pages that need them.

Let's look at an example. Say that you were building an eCommerce site, where visitors could purchase goods. On a number of ASP pages, you might need to determine the sales tax for the current user, based on the state they live in. Since your company is located in Washington, you will need to add an 8.6% sales tax to Washington-based customer's totals. You might write a function like:

function AdjustedCost(totalCost) AdjustedCost = totalCost * 1.086 end function

There may be a number of ASP scripts that need to use this very function. Rather than cutting and pasting this function into all of those ASP scripts, you could create a file called SalesTax.asp with the following content:

<% function AdjustedCost(totalCost) AdjustedCost = totalCost * 1.086 end function %>

Note that all we added were the ASP script delimiters (<% ... %>) around the function. When you #include a file, it's as if the contents of that file were cut and pasted directly into the file that issues the #include command. Since the #include command is issued outside of the ASP script delimiters, you need to have a starting and closing ASP script delimiter in the included file (or use <OBJECT RUNAT=server> ... </OBJECT>).

Now, let's say we had an ASP script in which we wanted to include the sales tax function, AdjustedCost. All we would need to do is issue a server-side include:

 <% 'The cost is $10.45 Dim fCost fCost = 10.45 'Display the adjusted cost Response.Write "You owe: " & AdjustedCost(fCost) %>

First, note the syntax for the #include. It must appear outside of your ASP script, and takes one of two forms:

 -- or -- 

If you use the keyword file, the file that you are including must exist in the directory relative to the ASP script that is including the file. In our example above, since we used #include file, SalesTax.asp would need to exist in the same directory as the file that was including it. Let's look at a few quick examples:

/scripts/Report.asp

formatFunctions.asp must exist in the directory /scripts, otherwise an error will occur.

/scripts/Report.asp

formatFunctions.asp must exist in the directory /scripts/ReportScripts, otherwise an error will occur.

An interesting note: you can use the ../ syntax with the file keyword to include a file in a parent directory. Why is this interesting? IIS is the only webserver I've seen that allows you to do that! (Of course, I've not used many.) According to the NCSA HTTPd documentation, the #include file cannot contain ../. I guess Microsoft is just doing its own thing here. One side effect of allowing developers to use include files in parent directories is that you can include files outside of your web site!

To be able to include files in parent directories, the Enable Parent Paths option must be checked. You can only do this if you have the Enable Parent Paths turned on. You can turn this on or off through the Internet Service Manager. Just right click on the Web you want to set this property for and click on Properties. Click on the Home Directory tab and then on the Configuration button. A new dialog box will appear. Navigate to the App Options tab, and you should see something very similar to the image on the right.

You may wonder how to do this. Well, it's not too tricky. Say that your root web maps to the physical drive C:\InetPub\wwwroot. If you want to include the file C:\Status\currentStatus.txt from /default.asp (which is physically located in C:\InetPub\wwwroot, you'd just need to issue the following #include:

There are a few warnings here, though. If you were to make changes to C:\Status\currentStatus.txt, the changes would not be reflected through IIS until the Web Server was restarted. When you include files that are in your website (i.e., the exist in C:\InetPub\wwwroot of one of its subdirectories), any changes in the included file appear when the client next requests the include file.

#include virtual is more flexible. Using #include virtual, you can specify the exact path of the file to include. For example:

/scripts/Report.asp

formatFunctions.asp must exist in the directory /format, otherwise an error will occur.

/scripts/Report.asp

header.asp must exist in the directory that the ASP page calling the server-side include exists in, otherwise an error will occur.

The nice thing about using the virtual keyword is that you can place all of your commonly included files into one directory (perhaps named /inc, or /scripts), and then use:

That way you don't have to worry about SalesTax.asp belonging in the same directory as all the the ASP scripts that need to include it.

Well, that's it for this first part. Be sure to read the second part for information on why we should use server-side includes, as well as naming conventions and other technical information!

Proceed to Part 2