To read the article online, visit http://www.4GuysFromRolla.com/webtech/080199-1.shtml

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.

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:

<!--#include file="SalesTax.asp"-->

<%
'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:

<!--#include file="filename"-->

       -- or --

<!--#include virtual="filename"-->

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
<!--#include file="formatFunctions.asp"-->
formatFunctions.asp must exist in the directory /scripts, otherwise an error will occur.

/scripts/Report.asp
<!--#include file="ReportScripts/formatFunctions.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:

<!--#include file="../../Status/currentStatus.txt"-->

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
<!--#include virtual="/format/formatFunctions.asp"-->
formatFunctions.asp must exist in the directory /format, otherwise an error will occur.

/scripts/Report.asp
<!--#include file="header.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:

<!--#include virtual="/scripts/SalesTax.asp"-->

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


  • Article Information
    Article Title: 4GuysFromRolla.com - The low-down on #includes
    Article Author: Scott Mitchell
    Published Date: Sunday, August 01, 1999
    Article URL: http://www.4GuysFromRolla.com/webtech/080199-1.shtml


    Copyright 2017 QuinStreet Inc. All Rights Reserved.
    Legal Notices, Licensing, Permissions, Privacy Policy.
    Advertise | Newsletters | E-mail Offers