Visual InterDev

Article
07/12/2006

One of the primary benefits of using the scripting object model and design-time controls is the ease of writing scripts that define your application's behavior. The scripting object model makes your Web pages work like forms in Microsoft^® Visual Basic^® or Microsoft^® Access. After dragging design-time controls onto the page, you can use familiar scripting techniques to set their properties and write handlers for events.

However, there are some differences between working with the scripting object model and working with other environments. In the sections that follow, you will find information about how to write script for script objects, including information about where you need to be aware of differences from other environments.

Note If you are writing ASP pages that use the scripting object model, you can set options that help you find errors and trace events. For details, see Debugging Script Objects in ASP Pages.

Writing Script Appropriate for the Target Platform

The target platform specifies where scripts run, and therefore dictates what your scripts can do. When the target platform is server, you can use the scripting object model and the ASP programming model, including Microsoft^® Internet Information Server (IIS) objects. Conversely, if your target platform is client, the scripting object model extends the document object model provided by Dynamic HTML (DHTML).

As you write script, you must be clear where it will run, so that you do not attempt procedures that are not appropriate for the context. For example, if your target platform is server, do not try to display messages directly to the user with functions like MsgBox or with the alert method. Even if the functions would work properly (generally, they result in an error), they would display the message on the server rather than to the user.

Changing Target Platforms

If the target platform is server, the RUNAT attribute of the script block will be set to SERVER. If the target platform is client, there is no RUNAT attribute.

If you change target platforms for a page, you must manually add or remove the RUNAT attribute of affected script blocks. For example, if you initially added design-time controls to a page when the target platform was set to client, a script block might look like this:

<SCRIPT LANGUAGE="VBScript">

If you then change the target platform to server, you must add a RUNAT attribute, as in this example:

<SCRIPT LANGUAGE="VBScript" RUNAT=SERVER>

This might not be the only adjustment required. Other platform-specific features to be aware of include:

Client script can display messages to the user. If you switch platforms to server, you must remove or replace MsgBox or alert calls.
Client script can reference objects from the DHTML object model, including window, document, and others. If your script uses these objects, you must alter it when changing to the server platform.
Server script must be written in the default page language (the language specified by the @ LANGUAGE=attribute at the top of the page) or must include a LANGUAGE attribute in the <SCRIPT> block.
Server script cannot access return values for certain calls, such as the onkeyup event.

Testing Script Objects

Test your page in the right place. Quick View in the HTML editor runs locally, so it does not process server script. Therefore, if your target platform is server, no script objects will appear in Quick View. Instead, use the browser to view the page from the Web server.

To test using the browser

In the Project Explorer, right-click the name of the file to test, and then choose View in Browser.

Referencing Script Objects and Properties

In your script, you can reference a script object using the name that you assigned to it when you created the design-time control. You read and write most properties as usual, by adding their name onto the object reference with a dot (.).

For example, if you have dragged a Textbox design-time control onto the page and named it txtName, you can read its current contents by getting the value of its value property, as in the following:

<SCRIPT LANGUAGE="JAVASCRIPT">
function getLName
{
   fname = txtName.value;
}
</SCRIPT>

Note Object and property names are case-sensitive in JScript™ and JavaScript.

By default, when you type in the name of a script object followed by a dot (.), the IntelliSense^® popup will display all the properties and methods appropriate for the script object you are working with.

When the scripting object model is enabled, you can reference the current page using the object name thisPage, or if you have specified it as a page object, by its page object name. For example, the following statement sets the value of the current page's cancelEvent property:

thisPage.cancelEvent = True

Note The thisPage object does not appear in the Script Outline window or IntelliSense drop-down unless you add a PageObject design-time control to the page. However, the thisPage object is available at run time and you can write scripts against it even if you have not used a PageObject control.

Some values are accessible as pairs of methods: a get method to get the property's value, and a set method to write it. For example, you can check the state of a Checkbox script object by calling its getChecked method, and set it using the setChecked method. The following example illustrates this type of property:

Function toggleCheckBox
   If checkbox1.getChecked() then
      checkbox1.setChecked(0)
   Else
      checkbox1.setChecked(1)
   End if
End Function

For a list of properties supported by each script object, see Script Object Model Properties.

Calling Methods and Functions

You call methods for script objects the way you do with any object. For example, if you have dragged a Listbox design-time control onto the page, you can populate it by calling its addItem method, as in the following script:

<SCRIPT LANGUAGE="VBSCRIPT">
Function LoadListBox()
   ListBox1.additem "Paris"
   ListBox1.additem "London"
   ListBox1.additem "Cairo"
End Function
</SCRIPT>

Note Method names are case-sensitive in JScript™ and JavaScript.

You can also call a method to run script on a different ASP page. For details, see Extending the Scripting Object Model Across Pages.

For a list of methods supported by each script object, see Script Object Model Methods.

Responding to Script Object Events

Each script object can generate a predetermined (or implicit) set of events. For example, the script object for a Button design-time control can generate a click event, and the script object for a Textbox design-time control can generate an onchange event.

Note You can also extend the set of events that an object can respond to so that it can make use of any events that the browser generates. For details, see "Extending Events for an Object" below.

To write a handler for a script object, create a procedure using the object's name and the event to handle. You can write event handlers in any scripting language supported by the browsers used for your application.

For example, if you create a button called btnDisplay, you can write a handler for its onclick event that might look like this in VBScript:

<SCRIPT LANGUAGE="VBSCRIPT">
Sub btnDisplay_onclick()
   Textbox1.value = "Button has been clicked"
End Sub
</SCRIPT>

Tip Use the Script Outline window to create event handlers. In the Script Outline window, expand the node for the object you are working with, and then double-click the name of the event you want to write a handler for. For details, see .

For a list of events supported by each script object, see Script Object Model Events.

Note Script object events occur only in response to a user action, not in response to programmatic changes. For example, if a user selects an item in a Listbox script object, the onchange event is fired. However, if you change the selection using a script statement, no event is fired.

An important feature of design-time controls is that you write event handlers for script objects in either client or server script, according to the target scripting platform. When a user clicks a button, the event actually occurs on the client. However, if your target scripting platform is server, you write a handler in server script that responds to that event as if it had occurred on the server.

In reality, if your scripting platform is server, the scripting object model wraps your page in a form. To process events in server script, the scripting object model performs a round trip to the server.

First, the event is captured and that, along with information such as other script object values, is sent as part of the post. Then at the server, an additional scripting object model procedure determines that it is processing an event and calls your event handler. When the server script is finished, the refreshed page is sent back to the browser. A similar round trip is performed for every event processed in server script.

For the most part, this process is invisible to the user and to your scripts, with these exceptions:

Processing events in server script is slower than doing so in client script, because it involves a round trip to the server.
You must be aware of where the event handler script is running, so that you do not attempt procedures that do not work on the server or on the client. For details, see Creating Forms with Design-Time Controls.

Extending Events for an Object

Each scripting object has a predetermined, or implicit, set of events that it can respond to. However, you might want to take advantage of other events that the browser generates and use them with your script objects.

Most typically, if you are using design-time controls and your target scripting platform is client, you might want to take advantage of the events available in the DHTML document object model. For example, the Textbox script object supports an implicit onchange event that you can write handlers for. However, on the client you might also want to write events for the onkeypress event and others.

You can extend the set of events available to an object by advising for an event, or registering the object to be notified when the event occurs. After you have advised for an event, you can write event handlers for that event (for that object) as you would for any other event. You can cancel event notification by unadvising for the event.

Each object supports an advise method that allows you to register a specific event. When you advise, you specify the name of the event and the name of a function that will be called when the event occurs — in effect, the name of the event handler for the event.

Tip In general, advising for events is practical only when your scripting target platform is client. If your platform is server and you advise for an event such as onkeypress, you will cause a round trip to the server each time the event occurs (in this case, with each keystroke).

You can advise and unadvise for an event at any time. A common time to do so is when a page is loaded. For client scripting targets, you create a handler for the window object's onload event and call the advise method there.

The following example shows how you would advise at page initialization time to have a DHTML onkeypress event sent to the text box called Textbox1. When the onkeypress event fires for Textbox1, it will call the function checkkeys. The result of the advise method is an advise object called objAdviseTextbox1 that you can use later if you need to unadvise for the event.

<SCRIPT LANGUAGE="VBScript">
Function window_onload()
   objAdviseTextbox1 = Textbox1.advise("onkeypress", "checkkeys()")
End function
</SCRIPT>

The function you specify in the advise method works like any event handler. If the event passes parameters, you can get those using the DHTML window object's event method. The following shows the handler for the onkeypress event in the previous example. It examines each keystroke that occurs in the Textbox1 object and copies only the numbers to the object Textbox2.

Function checkkeys()
   character = Chr(window.event.keycode)
   If character >= "0" and character <= "9" then
      Textbox2.value = Textbox2.value & character
   End if
End function

When you no longer need notification of the event, cancel it by calling the object's unadvise method. The unadvise method requires the advise object returned by the advise method as well as the name of the event. The following shows an example of calling unadvise:

Textbox1.unadvise("onkeypress", objAdviseTextbox1)

Trapping Events on the Client

If the target platform for a page is server, event handlers are executed as server script. In some instances, however, you might want to trap the event — handle the event first in client script — before it is passed to the server. For example, you might want to trap a Save button onclick event in client script in order to validate user information before it is sent to the server.

Trapping events is useful only if the target platform is server. If events are being processed on the client already, there is no need to trap the event, as it will not be passed to the server.

To trap an event on the server

Write a JavaScript handler for the current page's onbeforeserverevent event. This event is fired just before the event is forwarded to the server. The syntax of the handler is as follows:
```
function thisPage_onbeforeserverevent( objectName, eventName )
```
The objectName parameter contains the name of the object that fired the event, and the eventName parameter contains the name of the event that is being forwarded to the server.

In your handler, you can cancel the event (prevent if from being forwarded to the server).

To cancel an event on the server

Set the cancelEvent property to true.

The following is an example of how to trap the button click event for a delete button. The script prompts the user to confirm the deletion before proceeding.

<SCRIPT LANGUAGE="Javascript">
function thisPage_onbeforeserverevent( obj, event ){
if (obj=="btnDelete"){
      if(evnt=="onclick"){
         if (confirm("Are you sure you want to Delete?")){
            alert("Deleted per your request");
         }
         else {
            alert("Delete cancelled");
            thisPage.cancelEvent = true;
         }
      }
   }
}
</SCRIPT>

Converting Parameter Values

Some event handlers and methods receive parameters with the event call. If your target scripting platform is server, and if a procedure call is the result of a round trip to the server, parameter data types are converted to strings. A round trip occurs when:

An action on the client (such as a button click) is processed in server script.
Procedure in client script calls a method that is implemented in server script.
You call a page object method on another page. For details, see Extending the Scripting Object Model Across Pages.
A client makes a remote scripting call to an ASP page. For details, see Executing Server Script Remotely.

In any of these cases, the procedure that receives the parameter must convert it to the appropriate data type as necessary. For example, Boolean values are converted to the strings "true" or "false." If you write a procedure that receives a Boolean parameter, you should test it using script such as the following:

Sub TestValue( boolFlag )
   dim flag
   If boolFlag = "true" then
      flag = True
   Else
      flag = False
   End If
   If flag then
      ' processing here
   End If
End Sub

A Script Object Example

The following example shows a complete script block that includes properties, methods, and events. The page is a simple calculator with two text boxes, named txtNumber1 and txtNumber2, into which the user types numbers. The user selects an operator from lstOperators. When the user clicks btnCalculate, the result of the calculation is shown in lblResult as follows:

<SCRIPT RUNAT=SERVER LANGUAGE=VBSCRIPT>
Sub thisPage_onenter()
    If thisPage.firstEntered then
      txtNumber1.value = ""
      txtNumber2.value = ""
      lstOperators.addItem "+", 10
      lstOperators.addItem "-", 20
      lstOperators.addItem "÷", 30
      lstOperators.addItem "x", 40
      lstOperators.selectByValue(10)
   End if
End Sub

Sub btnCalculate_onclick
   Dim Result
   Dim Value1, Value2
   Value1 = CInt(txtNumber1.value)
   Value2 = CInt(txtNumber2.value)
   Select Case CInt(lstOperators.getValue())
   Case 10:
      Result = Value1 + Value2
      Operation = " plus "
   Case 20:
      Result = Value1 - Value2
      Operation = " minus "
   Case 30:
      Result = Value1 / Value2
      Operation = " divided by "
   Case 40:
      Result = Value1 * Value2
      Operation = " times "
   End Select
   lblResult.setCaption(Value1 & Operation & Value2 & " is " & Result)
End Sub
</SCRIPT>

Share via