Extending the Scripting Object Model Across Pages

See Also

Using design-time controls and the scripting object model allows you to create and script a Web page using standard object-oriented techniques. However, Web applications differ from other development environments in an essential way: they are usually constructed out of a collection of pages.

In a simple application, you can simply add links to other pages. When the user clicks a link, the browser follows the link, reads the page, and displays it. More complex applications, however, use more sophisticated linking techniques. For example, your application might require links that:

• Jump conditionally to different pages.
  
  
• Process a specific script on another page when the user jumps to it.
  
  
• Navigate to pages that provide server processing (such as database lookups) for your applications.

The scripting object model extends across pages to help you design applications with these types of requirements. You can use the scripting object model to designate pages as page objects.

A page object is an ASP page that contains server script that you use in your application. The procedures — functions or subroutines — on the page can become methods for the page object.

For example, you might have an ASP page in your application that you call from a form to display a list of employees. Procedures on the target page construct different queries for displaying the list — in different order, using different fields, or with different selection criteria. When you convert the page to a page object, you can specify each of these procedures as a method. You can then invoke the methods from other pages in your application.

Page objects also allow you to create properties, which maintain state over multiple round trips to the server.

Page objects give you:

• Simplified navigation. You can navigate to other pages in your application using standard object references, without having to track the URL of the page.
  
  
• An easy way to execute specific script on another page. By exporting procedures as methods, you can jump directly to a specific procedure on another page without writing script to parse hidden form elements or query strings.
  
  
• A means of maintaining state information. You can define properties on a page object that maintain their value for the duration that you specify — page lifetime, session, or application.
  
  
• A way to execute server script from a page displayed in the browser. For more details, see Executing Server Script Remotely.

The basic steps in creating a page object are these:

• Specify a page as a page object.
  
  
• Export procedures on the page as methods.
  
  
• Define the properties that the page object will support.
  
  
• Reference any other page objects that you will use in your scripts, on that page and in other pages.

Specifying a Page as an Object

You can specify any ASP page as a page object. To do so, you use the PageObject design-time control.

Note   Page objects are implemented using script stored in the Script Library. Do not alter the contents of the library, or page objects might not work properly.

To specify a page as an object

1. Create or open an .asp file in the HTML editor.
   
   
2. Enable the scripting object model for the page. For details, see The Scripting Object Model.

   Make sure that you have set options to view controls graphically. From the View menu, choose View Controls Graphically. To set this option as the default, use the HTML node of the Options dialog box.

3. From the Design-Time Controls tab of the Toolbox, drag a PageObject control onto your page. You can drag the control anywhere on the page, although it must be inside the framework of the scripting object model blocks.
   
   
4. In the Name box on the PageObject control, type a name for the page object. This will be the name that you can use to reference the object in script.

The name you give your page object is registered in your Microsoft^® Visual InterDev™ project so that it is available to any other page. Even if you move the page to another location, its page object name remains the same.

Exporting Procedures as Methods

One of the primary benefits of using page objects is that you can expose your application's tasks as methods that you can easily call from script. Doing so greatly simplifies the organization of your code and eliminates the time and effort required to transfer variables between pages, dispatch to the correct routine, and so on.

Page objects support two types of methods:

• Navigate methods are called by a client page that wants to jump to the ASP page and run a procedure there, and then perhaps jump somewhere else. A common use for navigate methods is to process a form.
  
  
• Execute methods are called by a client page that wants to use remote scripting to execute a script function. A common use for execute methods is to validate a user-entered value by looking it up in a database, or to perform a database query to populate a control on a page.

All page objects have a default method called show( ), which displays the contents of the page. This is the method that is called after any other methods on the page have been processed.

To create a method for a page object

1. If the page does not already have one, add a PageObject control to the page and give the PageObject control a name.
   
   
2. Write the procedures (functions or subroutines) in a script block that has the attribute RUNAT=SERVER. The procedure can take any number of parameters, but all are passed by value.

   For example, the following function creates a query string:

   <SCRIPT LANGUAGE="VBScript" RUNAT="Server">
   Sub ListEmployees(sortOrder)
      sqlText = "SELECT lname, fname FROM Employees"
      sqlText = sqlText & " ORDER BY " & sortOrder
      DoQuery(sqlText)
   End sub
   </SCRIPT>
   

   Note   Parameters are converted to strings when you call a page object method so that they can be successfully passed across the Web. In your page object scripts, you should convert parameter values to the appropriate data type as required.

3. Right-click the PageObject control, and then choose Properties to display the Property Pages dialog box.
   
   
4. Determine whether the method will be available via navigation or execution. Then in the list under either Navigate methods or Execute methods, find the first blank line. From the drop-down list, select the procedure that you want to expose as a method.

Note   It is possible to expose the same method as both a navigate and execute method. However, the method's underlying procedure must be written to accommodate both types of calls.

Defining Properties for a Page Object

Page objects allow you to expose properties, which are essentially global variables. You can scope a property to three levels: page, session, and application.

• Page-scope properties make a property available to scripts anywhere on the page until you navigate to another page.
  
  
• Session-scope properties are available to any page you navigate to in your project. Session values use IIS session variables to store values.
  
  
• Application-scope properties are available to any user of your application. Application values use IIS application variables to store values.

You also specify whether properties are available in client scripts, server scripts, or both. If you specify a property as a client property, you can further specify that it be either read/write or just read-only. Server properties are always read/write.

To create a property for a page object

1. If the page does not already have one, add a PageObject control to the page and give the PageObject control a name.
   
   
2. Right-click the PageObject control, choose Properties to display the Property Pages dialog box, and then choose the Properties tab.
   
   
3. In the Name column, find the first blank line, and then enter the name of the property you want to create.
   
   
4. Select the characteristics for the new property from the remaining columns:
   • Lifetime   Select whether the property will be available until the page is exited, or as a session or application value.
     
     
   • Client   Select whether the property will be read-only or read/write in client script. If you choose None, the property will not be available in client script.
     
     
   • Server   Select Read/Write to make the property available in server script, or None if it will not be available.

To make properties accessible to your scripts, page objects implement get( ) and set( ) methods for them. For example, if you define a property called Color, you can read its value using the method getColor( ) and set it using the method setColor( ). For more details, see "Accessing Page Object Properties" below.

Referencing Other Pages

You can call methods and use properties on the current page using the default page object name of thisPage. However, if you want to access the methods or properties of another page object, you must first create a reference to that page on the current page.

To reference another page object

1. If the page does not already have one, add a PageObject control to the page and give the PageObject control a name. If your scripting target is Server, the scripting object model must be enabled for the page.
   
   
2. Right-click the PageObject control, choose Properties to display the Property Pages dialog box, and then choose the References tab.
   
   
3. In the Name column, click the three-dot button to display the Create URL dialog box.
   
   
4. Select the .asp file that you want to reference as a page object. Enter options for how the page object should be called, and then click OK. For assistance with the options, press F1 in the Create URL dialog box.

Calling Page Object Methods

You can call methods on page objects in two ways: by navigation and by execution. You call a method by navigation when you are finished with one page and want to jump to another page and process script there. This is similar in HTML scripting to navigating to a URL: a one-way jump, except that using a page object saves the current page's state before navigating. For example, you might collect query parameters from the user on one page, and then jump to another page where you actually create and execute the query.

In contrast, calling methods by execution is similar to a familiar object-oriented method call — you call script somewhere else that performs a task and then returns. However, methods called by execution run asynchronously. The page that calls the method remains in the browser and the user can continue to work with it.

You can call methods by execution only if you are running client script and the method to be called is on a server page. For example, while the user is filling in the form, a client script might call a method on a server page to perform a database lookup.

To call a page object method

1. Create a reference on the current page to the page object you want to use. For details, see Referencing Other Pages above.
   
   
2. In your script, call the page object method using one of these types of calls:

   pageObject.navigate.methodName(parameters)
   pageObject.execute.methodName(parameters)
   

   Where:

   • pageObject is a reference you created earlier to a page object.
     
     
   • navigate and execute are child objects of the page object that determine how the method call will be processed.
     
     
   • methodName is the name of the method on pageObject that you want to call.
     
     
   • parameters is a list of parameters you are passing to the method. All parameters are passed by value.

   Note   Parameters are converted to strings when you call a page object method so that they can be successfully passed across the Web. In your page object scripts, you should convert parameter values to the appropriate data type as required.

The following script shows some simple form processing. When the user clicks a List Now button on the client page, the onclick handler for the button extracts the values of a list box on the page, and then calls a method on the page object poListEmployees for processing. In this instance, the user information is passed as a parameter to the page object's CreateList method.

<SCRIPT LANGUAGE="VBScript">
Sub btnListNow_onclick()
   department = lstDept.gettext()
   poListEmployees.navigate.CreateList(department)
End Sub
</SCRIPT>

Accessing Page Object Properties

When you define a property for a page object, the scripting object model creates a get method and a set method that you use to access the property. For example, if you have defined a property called UserName, you can read the value of the property using the method getUserName, and set it using setUserName, as shown in the following example:

newUser = PageObj1.Navigate.getUserName()
PageObj1.Navigate.setUserName(txtUserName.Value)

When working with properties, you need to be aware of their lifetime. If you have defined the property's lifetime as "page," for example, you can get and set its value only until you leave the page and display another one. (Calling the same page again to execute a method retains property values scoped to the page.) However, after you navigate to another page, the property is reset.