Introduction to Active Server Pages

This chapter is from the book 

The IIS Application Project

A new project type in Visual Basic 6.0 is the IIS Application. An IIS Application is a special type of ActiveX DLL that works on a Web server to process requests from the client and return HTML to the user's browser. Does this sound similar to what an ASP page does? Well, it should. IIS applications allow you to access many of the same objects (Server, Response, Request, and so on) as an ASP page and are themselves hosted in an ASP page. As a matter of fact, an IIS application works in a similar way to what was covered in the last section regarding calling an ActiveX DLL from an ASP page. The difference is that an IIS Application is set up specifically to deal with the Web; although an ActiveX DLL project contains a standard VB class module, an IIS Application project contains a WebClass.

Creating an IIS Application

To start an IIS application, open Visual Basic, and choose IIS Application from the list of available project types. A new project is created with a single object, WebClass1, shown in Figure 31.7.

Figure 31.7

An IIS application is a specialized type of ActiveX DLL that runs on the Web server.

Notice that WebClass1 is not a form or standard class module, but an ActiveX Designer. ActiveX Designers help you create specific kinds of ActiveX components and are integrated right into the VB development environment. In an IIS application, the WebClass designer takes care of a lot of "low-level" work for you in working with HTML. In fact, when you finally compile your IIS Application DLL, much of the VB code you write will be talking to the WebClass DLL.

Because the Web is inherently document-based, an IIS application depends on files being in their proper locations. Therefore, it is very important to save the IIS project before you start doing anything. Go ahead and create a separate directory for the application, such as C:\IISDemo, and save the project files.

As with forms, WebClass1 has both a code view and a design view. Open the design view by right-clicking the WebClass and selecting View Object. You then see the screen shown in Figure 31.8.

Figure 31.8

A WebClass can contain two types of WebItems.

As you can see, a WebClass contains WebItems. There are two different types of WebItems, which you'll learn about shortly:

• HTML Template WebItems. A WebItem based on an HTML template file that already exists.

• Custom WebItems. A WebItem created totally in code.

So, what is a WebItem? Well, it is nothing but code (remember this is just an ActiveX DLL) and because this is a server-based application, there is no visual interface. WebItems provide a way to connect Visual Basic program events to the document-based world of HTML.

Running an IIS Application

Before you go any further, look at the code for the WebClass. Right-click the class name in the Project Explorer window, and choose View code. You should see the default code for the WebClass' Start event, as shown in Figure 31.9.

Figure 31.9

The WebClass' Start event provides an initial HTML screen via the familiar Response object.

Go ahead and run the project by clicking the VB Start button or pressing F5. Remember, because IIS applications are Web server-based like ASP, you need to have a Web server running to use and debug them.

Each time you run your IIS Application in the VB IDE, Visual Basic generates an ASP file and attempts to launch it in Internet Explorer. The first time you run a new IIS Application, you will see a message like that shown in Figure 31.10, which asks you for the virtual directory name.

Figure 31.10

Visual Basic automatically creates a virtual directory and ASP file to host your WebClass.

When the application runs, you should see the HTML screen provided by the WebClass' Start event. If you look in the project directory, you might notice that Visual Basic has created an ASP file that creates an instance of your WebClass. By now, you should understand a little bit more about how an IIS application works—kind of like an ASP file, but with all the Web activity accessible through the Visual Basic environment. In the next section, you learn more about what a WebClass can do by adding WebItems to it. For now, stop the project in Visual Basic, and return to design mode.

WebClass Instancing

Open the Code window again, and note the standard events available for a WebClass. Put Debug.Print eventname statements in each of them, and run the project again. Watch the sequence of events:

1. When you start the project, the browser is launched. The ASP file loaded by the browser contains a Server.CreateObject statement, which creates an instance of the WebClass, causing the Initialize event to fire.

2. The ASP file also makes a request for a Web page to the WebClass, causing the BeginRequest event to fire.

3. The WebClass' Start event fires (much like the Form_Load event), causing HTML to be sent back to the browser.

4. When all the HTML has been sent to the browser, the request has been satisfied, so the EndRequest event fires.

5. The Terminate event fires, causing the instance of the WebClass to be destroyed.

Step 5 in the preceding list should have at least caused you to raise an eyebrow. Why was the WebClass created and then immediately destroyed? The answer is because the StateManagement property of the WebClass was set to wcNoState. This means if you set a local variable or property in the Start event of the WebClass, it would not be available on successive calls. If the StateManagement property was set to wcRetainInstance, then each call to the WebClass from the ASP page would be to the same instance, and you could store state information.

However, there is a deeper issue here than just setting a property. It is more a philosophy of how you write applications. The connection-less nature of the Web is more suited to transaction-based processing instead of state-based processing. When working with transactions, you really don't care about communicating with the same instance of an object because you pass all the information needed to complete a transaction along with each call to the object.

Most of us tend to write code that depends on an object's being in a certain state—for example, you will set a bunch of properties on an object and then later call a method on the object that uses those properties:

x.AccountID = 123456
x.AccountHolder = "Stephanie and Brent"
x.Amount = "$20.00"
x.DepositMoney

In these lines of code, x represents an instance of an ActiveX component that handles bank account functions. The last line is a method call to DepositMoney, which presumably requires the other account information to work. This code depends on repeated access to the same object. Another way to write this, in which all of the information is passed to the object, is as follows:

x.DepositMoney(123456,"Stephanie and Brent","$20.00")

Of course, this example is very simple, but think about a more complex example in which you were repeatedly calling functions on the object. In the first example, you would have to have access to the same instance of the object x; in the second example, it does not matter. Although the second example looks like more work, if you can write code that is state-independent, you can use tools such as Microsoft Transaction Server to pool object connections and create a very "scalable" application.

Using an HTML Template WebItem

To learn how HTML templates work with a WebClass, first create the following simple HTML template, TEST.HTM:

<HTML>
<BODY>
<H1> This is a test page </H1>
<BR>
<A HREF="http://www.somewhere.com> Link to somewhere! </A>

<IMG SRC=guestbook.gif>

</BODY>
</HTML>

There is nothing special about TEST.HTM until you import it into the project. To do this, open the Designer window for WebClass1, right-click WebClass1, and choose Add HTML Template. Select TEST.HTM from the File dialog box. Your Designer window should now look like the one in Figure 31.11.

Figure 31.11

When you add an HTML template to a WebClass, you are presented with all of the HTML tags in the template that can be connected to VB events.

After importing an HTML file, it becomes a WebItem.

Creating a Template Event

In the right pane of the Designer window, you see a list of all the HTML tags in the template file that can be connected to Visual Basic events. The new WebItem itself is also given a name: Template1.

By way of comparison, think about what happens when you add a TextBox control to a standard Visual Basic form. You are in effect placing an object (the text box) in a container (the form). After you draw the text box, you can access all its properties and events from the form's Code window. Similarly, Template1 is an object in your WebClass, much like the text box object on a form.

The only difference between the events in a text box and those in a WebItem is that WebItem events are not automatically available from the Code window. You first have to go through the process of connecting HTML tags to program events.

Try it with your sample program. Remember the hyperlink in the template to www.somewhere.com? When you imported the template, it was given the name Hyperlink1. Right-click it and choose Connect to Custom Event. A new event appears in the Designer window, also called Hyperlink1. Double-click the event name, and the Code window opens in the Template1_HyperLink1 event. This new event is fired whenever a user clicks the hyperlink. Enter the following Response.Write statement so that the event procedure looks like this:

Private Sub Template1_Hyperlink1()
    Response.Write "<BR> You clicked me!<BR>"
End Sub

Next, run the project. When the first page loads, change the filename at the end of the URL (something like Project1_WebClass1.ASP) to the template filename, TEST.HTM, and press Enter. The template page loads. If you choose View Source, you might notice that the hyperlink no longer points towww.somewhere.com, but points instead to an event in the WebClass. Click the hyperlink and you should see the words You Clicked Me displayed in the browser. You have just seen how a hyperlink in an HTML file can be connected to a Visual Basic program event.

Sending a Template to the Browser

By default, a WebClass' Start event sends a few lines of HTML back to the browser. You can also send templates back to the browser, such as the sample just created, by using the WriteTemplate method. Open the Start event of the WebClass and replace the default lines of code with the following line:

Me.Template1.WriteTemplate

Run the application, and the template based on the file TEST.HTM should be the first thing you see. Notice that the browser is not redirected to TEST.HTM, but instead the HTML from the template file is passed back during the Start event.

The WriteTemplate method can be very useful when combined with the ProcessTag event. This event can be used to dynamically generate HTML content, similar to the way you use Response.Write statements in an ASP page to generate HTML on-the-fly. It works by searching for tags within your template (much like HTML tags, but with a special prefix) and replacing them with whatever information you choose.

To demonstrate this, again bring up the template file TEST.HTM. (Make sure to bring up the file in the project directory, not the original import file.) Add the following line to the template somewhere in the body of the document and save it:

<WC@mytag>My Information/WC@mytag

The preceding line of code contains a "customized" tag, <WC@mytag>. During execution of the WriteHTMLTemplate method, each time the WebClass encounters a tag with the wc@ prefix, the ProcessTag event is fired. The tag name (mytag) and contents (My Information) are passed to the event and can be modified before being sent to the browser:

Private Sub Template1_ProcessTag(ByVal TagName As String, TagContents As String, SendTags As Boolean)

If TagName = "WC@mytag" Then

    TagContents = "<B> Here is some new information </B>"

End If
End Sub

Using a Custom WebItem

The other type of WebItem that can be added to the WebClass is a custom WebItem. The events in a custom WebItem are just like the ones in an HTML Template WebItem, and you have the option to add your own custom events that can be raised from a Web page. However, there is no template in a Custom WebItem. It exists only in your VB code as a set of event procedures. You can connect items in an HTML Template WebItem to a Custom WebItem with a few simple steps:

1. Right-click the WebClass' name in the Project Explorer window and choose View Object. The Designer window appears.

2. Again, right-click the WebClass' name in the Designer window, and choose Add Custom WebItem.

3. Select an HTML tag name in an HTML Template WebItem, and connect it to the custom WebItem.

4. Write code for the events, as described in the previous section.

As you might have realized from the examples, using WebClasses is a little more complex than standard ASP pages. However, they exist in the Visual Basic environment, which opens up a new realm of possibilities.