by Ken Henderson
Today, you'll learn to create and enhance IntraBuilder scripts, methods, and events. These are the specific tasks you'll cover today:
The IntraBuilder Script Editor enables you to edit forms and reports as JavaScript code. (JavaScript is IntraBuilder's native language.) It also enables you to write your own JavaScript methods and event handler code. You can think of the Script Editor as a behind-the-scenes view of the IntraBuilder development environment.
You can invoke the Script Editor by right-clicking a form or report in the IntraBuilder Explorer and selecting Edit as Script from the shortcut menu, as illustrated by Figure 6.1.
Figure 6.1 : Edit forms and reports using the Script Editor.
Editing forms and reports as scripts is a good way to learn IntraBuilder's underlying language, JavaScript. JavaScript was designed by Netscape as an object-oriented, platform-independent programming language. All a user needs to access IntraBuilder apps written in JavaScript is a browser that supports HTML 2.0. Regardless of whether the user is a UNIX, Mac, or PC user, JavaScript-based IntraBuilder apps will run just fine in any HTML 2.0 compatible browser.
Unlike most scripting languages, JavaScript is case-sensitive, so you'll have to be careful when keying scripts manually. In structure, JavaScript is reminiscent of C++, but it is easier and safer than either C++ or JavaScript's big brother, Java. It also includes a number of advanced features such as a dynamic object model and support for automatic type conversion. IntraBuilder builds on the JavaScript language definition and has enhanced it to support literal arrays, exception handling, and code blocks.
Note the syntax highlighting and other programmer's editor amenities of the IntraBuilder Script Editor. The editor supports two base keyboard layouts: the IntraBuilder set and the Brief set. It also supports a number of user-configurable features such as indent/outdent, editor font attributes, smart tabs, and undo. You can configure these settings by using the Editor Properties dialog box. To bring up the dialog, right-click the Editor and select Editor Properties from the shortcut menu. Figure 6.2 shows some of the settings you can configure.
Figure 6.2 : Use the Editor Properties dialog box to customize the Script Editor.
| NOTE |
One of the niftier features of the Script Editor is its support for dragging and dropping text. Drag-and-drop support enables you to drag a selected area of text to another location within a file. Think of it as an automated cut and paste operation. The text is moved from its original location to wherever you decide to drop it. |
You also might have noticed that the Script Editor defaults to a monotype (fixed pitch) font. Monotype fonts lend themselves more readily than variable pitch fonts when working with source code. Symbols and numbers also are generally easier read when all characters are the same size.
If you want to run a script from the Script Editor, you can use any one of these three methods:
Any of these methods will run the report or form just as though you'd double-clicked it in the IntraBuilder Explorer.
Click the Close button now to return to the IntraBuilder Explorer.
IntraBuilder also includes a handy script entry pad for testing JavaScript expressions, inspecting the environment, and generally giving you a behind-the-scenes look at what's going on in IntraBuilder. It's similar to the JavaScript typein prompt that appears when you enter javascript: in Netscape Navigator's Location entry box. You can access IntraBuilder system variables, display JavaScript expression results, and execute JavaScript commands.
Bring up the Script Pad now by selecting View|Script Pad. You should see a double-paned dialog box. By default, the top pane is the input pane and the bottom pane is the results pane, as shown in Figure 6.3.
Figure 6.3 : Activate the IntraBuilder Script Pad by using the View|Script Pad menu option.
Let's try a couple of expressions to see how the Script Pad works. Type the following statements into the Script Pad's top pane:
_sys.scriptOut.clear() ;
_sys.scriptOut.writeln("Hello World!") ;
Your output should resemble that shown in Figure 6.4.
Figure 6.4 : Use the Script Pad to execute JavaScript code.
Now, let's change the expression a bit to show off JavaScript's automatic type conversion. Enter the following statements:
_sys.scriptOut.clear() ; _sys.scriptOut.writeln( "2 + 2 = " + 4 ) ;
Figure 6.5 shows what you should see.
Figure 6.5 : Check JavaScript's implicit type conversion in your Script Pad expressions.
You can change the appearance of the Script Pad by using its Properties dialog box. As with the other facilities in IntraBuilder, the Script Pad Properties dialog can be accessed by using its shortcut menu. Right-click the Script Pad to pop up the shortcut menu. From the shortcut menu, you can either bring up the Script Pad property sheet or clear the results window. Figure 6.6 shows the Script Pad property sheet.
Figure 6.6 : Customizing the Script Pad by using its Properties dialog.
In addition to keying in your own JavaScript, you also can use the Script Pad to watch what's going on in the rest of IntraBuilder. Actions you take in the IntraBuilder Explorer are echoed to the Script Pad as JavaScript statements. To see how this works, arrange your screen so that the Script Pad and the IntraBuilder Explorer are both visible and double-click a report or form in the IntraBuilder Explorer to run it. You should see the appropriate JavaScript run method called in the Script Pad, as shown in Figure 6.7.
Figure 6.7 : Use the Script Pad to learn JavaScript statements.
If you look closely at the JavaScript statement that appears in the Script Pad when you open a form, you can see that a method of the _sys object executes. Any time you navigate or execute commands within the IntraBuilder IDE, you're actually calling methods of the _sys object. Beyond merely acting as the basis for IntraBuilder IDE, the _sys object also can be used in JavaScript functions that you write. I'll show you how in the sections that follow.
The _sys object is a global object that represents the current instance of the IntraBuilder Designer or IntraBuilder Agent. It's created automatically when IntraBuilder starts. You can access it and its methods and properties from the Script Pad and from within JavaScript functions. For example, when you wrote JavaScript earlier that sent text to the Script Pad, you referenced the _sys object when you called the _sys.scriptOut.writeln() method. To check out what's available to you in the _sys object, type this into the Script Pad:
inspect(_sys)
Figure 6.8 shows what you should see.
Figure 6.8 : The properties and methods of the _sys object appear in the Inspector.
Because you can access the _sys object's properties and methods from within JavaScript code, use them to help debug scripts. For example, you could use the Script Pad to see when a given form or report is loaded, or what the value of a particular variable is at runtime. In this sense, the Script Pad functions similarly to the "watch window" you often see in debuggers. Figure 6.9 illustrates the use of the _sys object's writeln() method, which sends output to the Script Pad while an application is running.
Figure 6.9 : Tracking events by sending messages to the Script Pad.
| TIP |
In either the Script Pad or your JavaScript code, you can use the ? in place of the _sys.scriptOut.write() method. In the Script Pad, ? places its output on a new line just like _sys.scriptOut.writeln(). You can also use clear in place of _sys.scriptOut.clear(). |
Listing 6.1 shows a form with writeln() methods embedded to show when events fire.
Listing 6.1. The WATCH form.
1: // {End Header} Do not remove this comment//
2: // Generated on 01/20/97
3: //
4: var f = new watchForm();
5: f.open();
6: class watchForm extends Form {
7: with (this) {
8: onServerLoad = class::Form_onServerLoad;
9: height = 10;
10: left = 0;
11: top = 0;
12: width = 40;
13: }
14:
15: with (this.button1 = new Button(this)){
16: onServerClick = class::button1_onServerClick;
17: left = 2;
18: top = 2;
19: width = 12;
20: text = "Button1";
21: }
22:
23: with (this.button2 = new Button(this)){
24: onServerClick = class::button2_onServerClick;
25: left = 20;
26: top = 2;
27: width = 12;
28: text = "Button2";
29: }
30:
31: function button1_onServerClick()
32: {
33: _sys.scriptOut.writeln("button1_onServerClick()") ;
34: }
35:
36: function button2_onServerClick()
37: {
38: _sys.scriptOut.writeln("button2_onServerClick()") ;
39: }
40:
41: function Form_onServerLoad()
42: {
43: _sys.scriptOut.clear() ;
44: _sys.scriptOut.writeln("Form_onServerLoad()") ;
45: }
46:
47: }
The WATCH form is a simple form with two buttons and three event handlers. Lines 8, 16, and 24 assign methods to events. When you run the form, the first event to fire is the form's
onServerLoad event. Lines 41 through 45 define a method that clears the results pane and prints the function name.
After the form opens, you can click the buttons to fire onServerClick events. Lines 31 through 34 define a method for the first button's onServerClick event. Line 33 prints the method name in the results pane. A similar method is defined on lines 36 through 39 for the second button.
You use the Method Editor to write code that responds to events
in IntraBuilder applications. These events can be server-side
or client-side events. Server-side events (and their associated
method code) are processed entirely on the server. Client-side
events require the user to have a browser that supports JavaScript.
Both Netscape Navigator and Microsoft Internet Explorer support
JavaScript. Microsoft refers to its implementation of JavaScript
as JScript. Table 6.1 summarizes some of IntraBuilder's events.
| Object | Event | Server-Side/Client-Side |
| Button | onClick | Client |
| Button | onServerClick | Server |
| JavaApplet | onServerLoad | Server |
| Text | onBlur | Client |
| Rowset | (all events) | Server |
Usually, you create a new method by clicking the tool button to the right of an event on the Events page of the Inspector. You can, however, open the Method Editor without creating a new method by using either of the following methods:
If you open the Method Editor this way and the form already has methods attached to it, the first method will be displayed. If the form has no methods attached to it, the form Header section opens. Figure 6.10 shows an onServerClick method loaded into the Method Editor. See Day 20, "Mastering Object-Oriented Programming," for more information on the Header section.
Figure 6.10 : Edit and link methods using the Method Editor.
If you want to open the Method Editor and create a new method, follow these steps:
Following these steps creates a new method and links it to the selected event. The Method Editor is then opened (or made active), and you can key in your new method.
Note that you don't have to write every method from scratch. To link a method that already exists to an event, follow these steps:
The top line of the Method Editor dialog box displays the events to which a method is linked. When a method is linked to multiple events, the Method Editor displays them one after another, separated by commas.
You'll find the facilities provided by the Method menu helpful when working with methods. You can use the options on this menu to create a new method or remove or verify an existing one. Verifying a method simply compiles it so that you can detect any errors before you attempt to run its host form or report. The Method menu also offers commands related to linking methods with events. As an alternative to the steps listed earlier today, use Method|Event options to link and unlink events and methods. These commands function the same regardless of whether you access them by using the Method menu or by using the Method Editor's shortcut menu.
Selecting the Method|New Method option creates a JavaScript definition for a new method in the Method Editor like this:
function Method()
{
// {Export} This comment causes this function body to be sent to the client
}
Clicking the Remove Method option removes the selected method and all references to it from the current script.
Choosing Verify Method compiles the method, instantly revealing any syntax errors. Figure 6.13 shows the Compilation Status dialog box, which displays when you verify a method.
Figure 6.13 : Verifying a method causes it to be compiled and immediately shows any syntax errors.
If you select the Edit Event option for the Method Editor shortcut menu, the Edit Event dialog box enables you to modify events in the right pane associated with objects in the left pane. The event you select is loaded into the Method Editor so that you can edit it.
The Link Event option displays a dialog box that enables you to link the current method with an object from the left pane and one of its events in the right pane. As I mentioned earlier today, after you link a method to an event, the event is listed next to the method name at the top of the Method Editor dialog box.
The Unlink Events menu option enables you to view the events linked to a particular method and unlink any or all of them. When you unlink an event from a method, the link is removed from the list of links to the right of the method name at the top of the Method Editor. Figure 6.14 shows the Unlink Events dialog box.
Figure 6.14 : The Unlink Events dialog box enables you to manage a method's linked events easily.
As you might guess, server-side events and methods are run on IntraBuilder Agents. Applications that are completely server-based require only that users have browsers that support HTML 2.0. Client-side events, on the other hand, require browsers that support JavaScript, such as Netscape Navigator, Netscape Communicator, and Microsoft Internet Explorer.
In order to ensure that your IntraBuilder applications are accessible to the broadest number of users, your applications should be primarily server-based. You should then supplement your server-side logic with client-based code where necessary. This helps achieve a nice balance between the various tiers that make up your applications. It also helps ensure that your applications are as compatible with as many browsers as possible and as functional on the client-side as possible.
The trade-off you have to consider is this: Even though locating events on the server makes your applications more accessible, they are somewhat less functional than apps that include client-side event processing. Nowhere is this more evident than in data validation events. Server-side data validation does not occur until a form is submitted to the server. Client-side validation, by contrast, can happen on a field-by-field basis. This way, users can be made aware of data validation errors as they occur.
Though it might seem otherwise, the answer here is not to pick one approach over the other. Rather, you should place as much of your code as possible on your Web server and augment it with client-side JavaScript where necessary. With data validation events, this means validating your data in both places-the idea being that the server-based validation will act as a safety net for those client browsers that do not support JavaScript. For those browsers that do support JavaScript, the validation will be handled at the client and will be more functional and more user-friendly.
Browsers support JavaScript through HTML tags. These tags consist of the <script> and </script> identifiers. Although browsers default to using JavaScript, the script tag allows for other scripting languages such as VBScript. Scripts are embedded between the two tags like so:
<script language = "JavaScript">
function button1_onClick()
{
history.back() ;
}
</script>
Your JavaScript functions are placed between the two tags. Because browsers that don't support JavaScript will display the functions as plain text (ignoring the <script> tags), it's a good idea to embed JavaScript inside HTML comments. When you link methods to client-side events, IntraBuilder automatically streams out the appropriate tags and comments as shown here:
<script language = "JavaScript">
<!--
function button1_onClick()
{
history.back() ;
}
//-->
</script>
In this chapter you learned to edit IntraBuilder scripts and event code using the Script Editor and Script Pad. You learned how to inspect IntraBuilder's internals in detail and to tweak IntraBuilder applications using JavaScript. Specifically, you learned how to use the Script Editor to edit JavaScript code, how to use the Script Pad to see exactly how the IntraBuilder Explorer behaves, and how to use the Method Editor to edit and link methods and events. You discovered the purpose of the _sys object and ways that you can utilize it, and you examined the difference between client- and server-side JavaScript and the advantages of each, as well as how to embed client-side JavaScript without worrying about browsers that don't support it.
| Q: | How do I write client-side functions that are not directly linked to client-side events? |
| A: | IntraBuilder exports any functions that contain the following comment line. Exported functions appear in the HTML pages that the IntraBuilder Server sends out to a browser. // {Export} This comment causes this function body to be sent |
| Q: | How do I send messages to the Script Pad from within my JavaScript code? |
| A: | You can use _sys.scriptOut.writeln() to send messages to the Script Pad from within JavaScript code. |
| Q: | How do I link a given method to more than one event? |
| A: | With the method loaded in the Method Editor, right-click the method and select Link Event from the menu. In the ensuing dialog box, choose the object and event to which you want to link the method and click OK. |
The Workshop section provides questions and exercises to help you get a better feel for the material you learned today. Try to answer the questions and at least think about the exercises before moving on to tomorrow's lesson. You'll find the answers to the questions in Appendix A, "Answers to Quiz Questions."
