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.
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.
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:
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 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.
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.
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 Script Outline Window.
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:
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 DHMTL 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 adviseTextbox1 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)
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
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
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>
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:
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
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 Number1 and Number2, 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 Label1 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>