Using PageObject DTCs

The PageObject DTC allows you to designate a page in your application as a page object, an ASP Web page containing server script you can use in your application. It provides the server-side events onenter and onexit, and also the onbeforeserverevent client event. The PageObject DTC also allows a page to expose methods and properties. (A page utilizing the Scripting Object Model can also be treated as an object itself through the use of the thisForm HTML form.)

When a user navigates to the ASP file, the onenter event fires. This allows you to place code in an event handler that executes when the page is first entered. When the page finishes, the onexit event fires; you can place code in an event handler for this event to clean up the page.

The PageObject DTC and the Scripting Object Model provide us with an object-oriented programming environment in both ASP and DHTML pages. You can treat your ASP code as objects with methods and properties. Both ASP and DHTML pages now are event driven.

There are other page events you can use, such as placing an onclick event in your ASP file that is called by HTML in the browser. These events are provided by the run-time Scripting Object Model components and are implemented by using DTCs.

This new object model is tremendously powerful. You can see all this magic in action by running an ASP application that uses these events. First set breakpoints in the code to stop your application. Next debug the application starting with that page.

To use the PageObject DTC to implement an ASP file as a page object, all you need to do is insert the DTC in a page:

1. Open the ASP file in the code editor.
2. Enable the Scripting Object Model for this page.
3. Drag the PageObject DTC from the Design-Time Controls tab of the Toolbox onto the page and inside the Scripting Object Model code.
4. Enter the name for the PageObject DTC in its Name text box.

The page should look similar to the one shown in Figure 4-6.

Figure 4-6. The PageObject DTC's name is important because it is used to refer to items in the page.

You can use the name you select for the page object when you want to refer to the page. The name is automatically registered in your Visual InterDev project and will remain the same, even if the page is moved. You can also move ASP files that are page objects into other projects.

Defining Page Methods

You can define methods on a page and expose them with the PageObject DTC. Once you have exposed a method using the PageObject DTC, you can execute the methods from either a client or server script. You do not need to do anything special for the methods that you create. The PageObject DTC will allow you to expose both function and procedure methods.

The PageObject DTC supports two types of methods. Navigate methods are used when a page needs to execute a procedure in an ASP file and then navigate to that or another page. Execute methods use remote scripting to execute ASP methods and return the data to the current page. Execute methods can be used from client script only. Navigate methods can be executed from either client or server script. To create a method of either of these types for a PageObject DTC, follow these steps:

1. Open the ASP file in the code editor. The page must contain the PageObject DTC and the script functions that you want to use.
2. Display the PageObject DTC's Properties dialog box by right-clicking the DTC and choosing Properties from the context menu.
3. Click the Methods tab.
4. Enter the name of your method in the Navigate Methods or Execute Methods section, depending upon which method type you want.

Once you enter the method name, the property page will display the method as shown in Figure 4-7. You can also enter method names that do not exist, but they will be shown in red until you create the method.

Once you enter the name of your method in the Navigate Methods or Execute Methods section, that method will be exposed to other pages. You can execute the method in your code by using this syntax:

 <%     MyProp.Execute.CheckInventory() %> 

or

 <%     MyProp.Navigate.CheckInventory() %> 

Figure 4-7. This figure shows the PageObject Properties dialog box with one method that has been exposed..

This syntax is similar to the Execute syntax you use with stored procedures. When you execute a method using Execute, the execution takes place either synchronously—that is, the current page waits on the method to execute—or asynchronously—the current page stays in the browser and the user can continue to work with it while the method executes. When you use Execute to asynchronously execute a method, you can pass a parameter containing the name of a callback procedure. The callback procedure will be executed when the method completes. The callback procedure name should be included as the last parameter in the parameter list:

 <%     MyProp.Execute.TotalInventory(ItemNumber, displayTotal) %> 

The callback procedure is simply a procedure or function in the client application. You can use the callback procedure to access the results of the function and display them or use them in some other manner. A callback procedure would look like this:

 <script LANGUAGE="JavaScript"> function displayTotal(retObj) {     if (retObj.return_value == "OK")         ProcessTotal(return_value); } </script> 

This example uses the retObj variable to access the object returned from the executed procedure. The return_value property allows us to retrieve the return value of a function.

You can also use Navigate to execute methods. In fact, you must use Navigate to execute methods from ASP script. Execute can only be used by client script.

Defining Page Properties

You can use the PageObject DTC to define properties for an ASP file in the same manner you define methods. Page properties are global variables that you create in your code.

Page properties have three possible scopes:

• Page The property can be used anywhere on the page and is available until the user navigates to another page.
• Session The property is stored in a Session variable and is available anywhere in the user's session.
• Application The property is stored in an Application variable and is available anywhere in the application.

Storing values using the PageObject DTC is easier than using Session and Application variables. If you select Session as the variable scope, browsers visiting your site must support cookies. Browsers that do not support cookies will not be able to use Session level variables.

You define properties using the PageObject DTC using these steps:

1. Open the ASP file in the code editor. The page must contain the PageObject DTC and the script functions that you wish to use.
2. Display the PageObject DTC's Properties dialog box by right-clicking the DTC and choosing Properties from the context menu.
3. Click the Properties tab.
4. Enter the name of the property in the Name column.
5. Select the Lifetime value to set the property's scope.
6. Select the Client and Server access settings.

Figure 4-8 shows three properties in the PageObject Properties dialog box. ItemNumber and ItemName are both Page properties and are read-only for the client. This allows the user to see the property data, but the data cannot be changed. The OrderNumber property is read/write for the client and is a Session property. This allows the user to change the data in the property, and it allows the application to access the property throughout the user's session.

Figure 4-8. Page properties are a useful way to store values in your application.

You can access the properties in your script code by using IntelliSense. When the PageObject DTC creates the property procedures to use for accessing the properties, it builds them as setxxx and getxxx, where xxx is the name of a property. In other words, if we take the example shown in Figure 4-8, you would set these properties like this:

 <%     ProjectCallback.setItemName = "My Widget"     ProjectCallback.setItemNumber = "101"     ProjectCallback.setOrderNumber = "98-01001" %> 

The properties in this example can be referenced using these statements:

 <%     Response.Write ProjectCallback.getItemName     Response.Write ProjectCallback.getItemNumber     Response.Write ProjectCallback.getOrderNumber %> 

Figure 4-9 shows IntelliSense with these properties' get procedures displayed.

It might seem strange using get and set as the prefix to page property procedures. The PageObject DTC builds the property procedures similar to the way Visual Basic classes use Property Get and Property Set procedures. This ensures that your property names do not clash with the names of other objects or items in a project and make debugging the project a nightmare. This also prevents you from overriding a built-in property or method with one of your properties.

Figure 4-9. The set and get procedures for page properties are available in your script code using IntelliSense.