Active Server Pages/Server-Side Includes

Objectives

In this chapter we will discuss the use of server-side includes (SSI) to simplify the process of building and maintaining a website. For maximum flexibility, I use SSI for both site templates and common code modules (libraries).

Content

Server-side includes have been around long before Active Server Pages was ever conceived. Basically, it was designed as a web server extension that looked for special macros contained inside of HTML comments. Nearly all webservers support at least some subset of server-side includes. The most useful of these macros is the "server-side include".

So when a web page is accessed, the web server would first scan the source file (or resource) that the visitor requested. If no processing macros were found, then this file is simply delivered to the user without modification. When a macro is found, the web server will do the appropriate processing of the macro (completely replacing the HTML comment with the appropriate results). All of this is done before the content gets delivered to the user (or the remote host).

What it Does

The specific processing directive we are interested in here is the server-side include. This allows you to import the contents of another document into the current one. This is extremely useful for reusing common blocks of ASP code and HTML. One of the most common uses of this is for creating a website template.

Another popular use is for creating code libraries that can be included in the web pages where you need them. I typically create a generic site-wide library that all pages must include, a header and footer template, a database library, an e-mail library and a form processing library. By reusing common code, you can eliminate the errors that may occur when you copy code from one page to another.

There are two different types of server-side includes we will discuss here: "virtual includes" and "file includes". The only difference is in the way that they access the directory structure for the website.

Virtual Includes

A virtual include will import the contents of another file based on the document root of the webserver. The path to the file should begin with a slash (/) which represents the root of the website (not the root of the filesystem).

Internet Information Server (the default webserver for Microsoft Windows) may be configured so that you cannot use a File Include to import the contents of a file from a parent directory. In this case, you will need to use the Virtual Include to accomplish this task.

Shown below is an example of two virtual includes used to pull in a header and footer template into the current page. Contained within an HTML comment (delimitted by <!-- and -->), you will see the processing directive (#include virtual). The path and filename inside the quotes is the resource we want to bring into the current document.

<!-- #include virtual="/lib/header.asp" -->

<h1>Hello World</h1>

<!-- #include virtual="/lib/footer.asp" -->

It is important to note that you can import many different types of files into the current document. You should realize that the webserver simply replaces the contents of the included file directly into your HTML document. Also, you cannot embed any preprocessing macros inside an ASP code block (delimitted by <% and %>).

The include process works recursively, so that if you include one file that //also contains// server-side include directives, then those will be included recursively so that all macros are processed.

File Includes

Another type of include statement is #include file. This statement works just like the virtual include except that the path to the file must be relative to the directory where the current page resides. In other words, you cannot access the directory structure starting from the document root (meaning the root of the website.)

Below is the same example as before with the virtual includes replaced with file includes. When running this script under IIS, you may get an error when trying to access a parent directory in this manner. For this reason, I prefer to use virtual includes whenever possible.

<!-- #include file="../lib/header.asp" -->

<h1>Hello World</h1>

<!-- #include file="../lib/footer.asp" -->

Alternatives to Server-Side Includes

Active Server Pages contains a couple of statements that work similar to server-side includes. These are also useful for the same purposes as server-side includes. However, none is a substitute for the other. They all have their different purposes and you should know when to use each.

Server.Execute

This will execute another Active Server Page file from the website. You can do this conditionally using the If Then ... End If syntax. This is different from the server-side include statement which will be executed wherever it appears.

Another difference between this statement and a server-side include is that all variables, functions and classes defined in the calling script will not be accessible in the executed script. This is a huge barrier to using this as an include and it is the main reason why I prefer server-side include to this statement.

If Application("ShowForum") Then
	Server.Execute("/module/forum.asp")
End If

I have used this to build a modular web portal application with good success. Through a control panel, the user can configure which modules they would like to display on their website. The template engine checks this configuration and pulls in only the modules that we need to display and arranges the layout accordingly.

Server.Transfer

The Server.Transfer statement is similar to Execute in that it executes an external ASP file on the webserver. However, unlike Execute, this function does not return control to the calling script. Instead, control is transferred to the script and, when the script finishes execution, the processing of the request terminates.

This is useful for use as a redirect. Basically, you test for certain conditions in your script and transfer control to another script based on which condition is met. So maybe you could have a login page that contains a form which posts to itself. If the user login is authenticated, you can transfer processing to a member control panel.

If bIsLoggedIn Then
	Server.Transfer("/account/index.asp")
End If

You should note that if any HTML is output to the browser before the Server.Transfer statement is reached, the output of the new ASP file will be appended to the HTML that has already been output. While you could do a standard redirect using the ASP built-in statement Response.Redirect, that would discard any HTML that has already been output and rebuild the response from the beginning.

Summary

Server-side includes provide a powerful mechanism to reuse code in Active Server Pages. You can use it to create a website template, code libraries, and HTML modules which may be reused throughout your site.

The two types of include statements are the virtual include and the file include. Use the virtual include to include ASP or HTML files using a path specifier that begins with a slash (/) denoting the document root of your website. The file include includes the content of a file with a path specifier that is relative to the directory of the calling script. The contents of the external file will be imported into the original document before any ASP code is processed.

Alternatives to server-side include the Server.Execute statement which executes the external file as a stand-alone script and then combines this output with the output of the calling script. The other is the Server.Transfer statement which passes control over to the external script permanently (control never returns).

Review Questions

• What does a server-side include do?
• What are the two types of server-side includes?
• What happens if you include a file which contains server-side includes?
• What are some alternatives to the server-side include?
• Explain how these alternatives work to execute external ASP code

Exercises

• Create the include files (header and footer) for a real simple HTML template
• Write a virtual server-side include to import the HTML template files.
• Write some ASP code to call Server.Execute to display a weather module
• Write some ASP code to call Server.Transfer to log off a user from a member area.