You can determine the way your application responds to user events and changes in data by using the Connection Builder to make connections between components. See "Connecting Components."

The behavior of components is often determined by the values of their properties. Because the Inspector's property value cell provides only limited editing capability, custom property editors are available to edit more complex values.

• JavaScript components have properties whose value can or should be a JavaScript expression, which is evaluated at run time. When a property value is a JavaScript expression, the value is preceded by an equal-sign (=) in the Inspector. When a property can have an expression as a value, the equal-sign button at the right of the value cell gives you access to the Expression Editor, which you can use to create JavaScript code for the value. See "Creating JavaScript Expressions."
• Many database-access components have an SQL Query property whose value you must set to a valid SQL select statement. Use the SQL Builder to create SQL code for these properties. See "Creating SQL Queries."

Finally, if you want to specify behavior that does not fall into any other category, you can add JavaScript code directly to your application using special code components. See "Adding Code to an Application."

Connecting Components

From the point of view of the programmer, an event handler function is called when a click event occurs, and responds by invoking another method that downloads new data and updates the table. From the point of view of the user, however, clicking the button updates the table. The button component and the table component are connected through the click event.

The key elements of any interaction are the source event and the action. The source event is the originator of the action; it determines when to execute the code. You can add conditions to an interaction just as you would add an if statement in code. The action specifies what to do when the condition is satisfied.

One of the most powerful features in Visual JavaScript is the ability to specify interactions at a high level, between components. Using the Connection Builder you can easily and quickly create connections, or interactions, between components, thereby specifying the behavior of your application without actually writing any code at all. Visual JavaScript automatically generates client-side JavaScript code for the specified relationship

NOTE: The Connection Builder makes only client-side connections. Because the connections are implemented in client-side JavaScript, the end-user of an application that contains connections must use a JavaScript-enabled browser.

Connection Types

• Property connections
A property connection listens for a property change event in the source component. In response to the event, it changes a specified property in the target component. To support this type of connection, the source component must have a property <name> change event. Property connections are often made to the Value property of a component.
• Direct connections
For a direct connection, you need only specify the trigger event and the target component. The target component is automatically updated appropriately when the trigger event occurs. This type of connection is used to connect Java and JavaScript components, such as some of the built-in data-display and database cursor components.
To support a direct connection, the source and target components must share an event/listener interface. Among the default components provided with Visual JavaScript, the Java Client Cursor and JS Client Cursor have tableChange and/or rowChange events, which you can connect directly to client-side Java tables and forms. When these events occur, the connected tables and forms are automatically populated with the current data in the cursor.
• Event connections
An event connection listens for a specified event in the source component. In response to the event, it can perform one or more actions specified in a handler script. You can use the Script Builder to generate an event handler that calls methods in a target component, or sets specified properties, or both. Alternatively, or in addition, you can specify arbitrary JavaScript code to be executed in response to the event.

Specifying Connections

Figure 5.1    The Connection Builder

• From the Source Event list, choose the particular user event to which the source component should respond. The default event type is the one most often used for the type of component, such as a click event for a button. You can choose any event that is defined in the source component.
• From the drop-down list of connection types, select the type of the connection. Only those connection types appropriate to the source component and event are shown, and the most common type for the component is selected by default.
The type of connection you can specify depends on the source event. For example, if the source is a propertyChange, tableChange, or rowChange event, you can specify a direct or event connection. If the source is a property name change event, you can specify a property or event connection.

When you have made your choices, click Apply to create the connection. When you click Done, the Connection Builder disappears. If the current specification has not yet been applied, the information is discarded.

When a connection is applied, Visual JavaScript generates client-side JavaScript code in the body of the page containing the source component. The code is run when that page is loaded, and in some cases, when the trigger event occurs.

Specifying a Direct Connection

Figure 5.2    The Connection Builder building a direct connection

For a direct connection, the name of the target component is all you need to specify. Everything else is automatic.

For direct and property connection types, a check box (initially, unchecked) lets you specify whether the connection should be two-way. In a two-way connection, each component acts as both source and target, just as if you had specified a second connection with the source and target reversed.

Specifying a Property Connection

Figure 5.3    The Connection Builder building a property connection

For a property connection, you must select the property to be set in the target component. This is most commonly the Value property, which is selected by default if present.

For direct and property connection types, a check box (initially, unchecked) lets you specify whether the connection should be two-way. In a two-way connection, each component acts as both source and target, just as if you had specified a second connection with the source and target reversed.

Specifying an Event Connection

Figure 5.4    The Connection Builder building an event connection

Figure 5.5    The Script Builder

1. Click Script Builder in the Connection Builder.

2. Choose a target component from the Component drop-down list. This is a component with a method to be called or a property to be set in response to the source event; for example, a cursor component containing a method to be called. (Note that the list of target components includes the standard client-side JavaScript runtime objects window and document.)

3. Choose the kind of action to be taken: Call Method or Set Property.
   • If you choose Call Method, choose from the list of methods in the target component. Select the desired method and click Add Action, or double-click the desired method.
   • If you choose Set Property, choose from the list of properties in the target component. Select the desired property and click Set Property, or double-click the desired property.

4. A dialog box appears in which you can specify the value to which the chosen property is to be set, or the parameters to pass to the chosen method. When you have made the required specifications, click OK to add the chosen action to the script.

5. If you want, you can add additional statements to the event handler script in the same way. You can choose another method or property in the same component, or choose another target component.

6. When the script is complete, click OK to return to the Connection Builder. The script you have built appears in the script handler field, where you can edit it if you wish.

• When you examine a component in the Inspector, the Event section shows you how many connections exist for each event of that component. Click the ellipsis (...) next to an event to bring up the Connection Builder and examine the connections for that event.
• Select the source component in the Page Editor, then invoke the Connection Builder by choosing Connection Builder from the Tools menu. The connections for the first event in the selected component are listed as existing connections. You can choose a different source event to see its existing connections.
• When the Connection Builder is active, simply select the source component in the Page Editor. The connections for the first event in that component are listed as existing connections. You can choose a different source event to see its existing connections.

• Change the target component.
• Change the target property or event handler.
• Change a one-way property or direct connection to be two-way connection, or vice-versa.

NOTE: The source component in the Connection Builder is always the currently selected component. If you select another component in the Page Editor while you are in the process of modifying a connection, a dialog box warns you that the currently displayed connection information will be discarded if you change the source component. If you choose to continue (that is, change the source component), the connection you were modifying reverts to its most recently applied state. §

In the Inspector, a property that can have an expression value has an equal-sign (=) button on the right side. A value that is currently specified by an expression also has an equal-sign at the left side of the value cell. You can enter a JavaScript expression directly into the value cell in the Inspector by prefacing the value with an equal-sign and enclosing any string values in quotes, as in this example:

= "User entered: " + Text1.Value 

Figure 5.6    The Expression Editor

• For server-side components (and for components with server-side code, such as the JS Client Cursor), available objects include the component itself, other server-side objects on the same page, and standard server-side JavaScript objects, such as the request object.
• For client-side components, available objects include the component itself, other client-side objects on the same page, and standard client-side JavaScript objects, such as the window and document objects.

Follow these steps to build an expression:

1. Type directly into the text box at the bottom of the window. Enclose string values in quotes, and enter numbers and operators directly.

2. Double-click a property in the right-hand list to add a JavaScript property accessor expression to the text box. For example, if you select the request object and double-click the _name property, request._name appears in the text box at the cursor location. At run time, this expression is evaluated to derive the value of the property.

3. Use the plus operator (+) between strings to concatenate them, or to concatenate expressions and strings. (Between numbers, the plus operator indicates addition.) You can also use any other built-in JavaScript functions or operators to create a valid JavaScript expression.

4. When the expression is correct in the text box, click Set Value.

   Tip The values submitted by a form are passed as parameters to the associated page via the request object. When you have interactively connected an HTML form to the current page (as described in "Connecting a Form to a Page" on page 94), you can see and access these runtime values in the Expression Editor when you are setting the value of a server component property. §

Important If you are using Enterprise Server 2.x, you must use Application Manager to install the following file to your web server before attempting to use the SQL Query Builder: install dir/serverJS/metadata2.web. See the Release Notes for instructions on installing this application. §

• LiveWire Cursor
• Java Client Cursor
• JS Client Cursor
• Simple Server Table

Figure 5.7    Inspecting a SQL Query property in the JavaScript Client Cursor component

Figure 5.8    The SQL Query Builder custom property editor

1. Select the Database tab to specify the data source you will be using. You must identify a data source before you can build an SQL statement that selects particular tables and columns.

2. Select a data source from the drop-down list. This list shows data sources that have already been identified. If the data source you want to use is not listed, click Create to add it, then select it from the list.
   Note: When you identify a data source, the DBPool property of the component you are editing is set. If a DBPool component for the data source is found on the globals.html page, it is used. Otherwise, a new DBPool component is created on the globals.html page. For compatibility with earlier releases, you also have the option of using the DBPool already specified in the DBPool property. §

3. Select the Query tab to specify the SQL query. The Query tab is shown in Figure 5.9.

   Figure 5.9    The Query tab of the SQL Query Builder

   

The text box near the bottom holds the query you are building. The clauses appear separately in their own boxes and are automatically added to the query.

There are a number of options for building queries:

• You can make a query that selects all of the columns of a particular table by double-clicking the table name.
• You can add columns to a Select clause by double-clicking the column name.
• You can use the buttons along the bottom of the window to specify particular clauses using the values selected in the lists. New specifications are added to existing ones.
• You can enter text for any clause directly into the box for that clause. When you press Enter, the specified clauses are added to the query.
• You can type directly into the query text box to edit the query.

NOTE: The SQL expression is stored in the SQL Query property as a string value. If you want to include any quoted strings in the expression, you must use the backslash (\) escape character before internal quote marks, as in this example:

"SELECT ITEM_NUM \"Product ID\", DESCRIPTION \"Product Description\" FROM ITEM_MASTER" 

For example, when you submit a form, the target document can reference the form values using a JavaScript expression as follows:

var myVar = request.myVal; 

"SELECT myFirstColumn, mySecondColumn FROM myTableWHERE myFirstColumn =
'" + request.myVal + "' " 

See "Creating Forms to Display Data" for more information on connecting form elements so that they display data from a database.

When you call the submit method of an HTML Form component, the values of all the elements on the form are collected and sent as parameters to the URL that is the value of the Form's Action property. The Form's Method property determines if the parameters are sent in the same transmission (GET) or in a separate transmission (PUT).

You can place a Submit Button component on the form to make it easy for users to apply values they have specified. The Submit Button component is a specialized HTML button that, when clicked, calls the containing form's submit method. The label of the button is, by default, Submit. You can change the label by inspecting the component and setting the Button Label property.

You can connect an HTML Form component to another page so that when the form is submitted, the connected page is loaded and the values of the form's elements are passed as parameters to that page. The connected page can contain server-side processing components, such as the Database Form Handler, that use the parameters submitted with the form.

See "Creating Forms to Display Data" for more information on passing values to a database using the Database Form Handler component.

Connecting a Form to a Page

You can also connect a Form component to another page in the same project interactively, using drag and drop. Follow these steps to do so:

1. Display both the page containing the Form and the target page in Page Editor windows. Arrange the windows so that you can see both pages at once, with the page containing the Form on the right.

2. Click on the connection box in the upper-right corner of the Form component.

3. Hold down the button and move the cursor. The cursor changes to the "plug" icon to indicate that you are in connection mode.

4. Drag the connection cursor to a blank area on the target page, making sure that no component is selected. Release the button.

At runtime, the request object has a property for each value, named for the form element whose value is being passed, preceded by an underscore--for example, _Text1.

NOTE: If you have connected the form to the page interactively (by dragging and dropping the plug icon) you can use the Expression Editor to access the runtime properties of the request object that contain the form values. If you have connected the form to the page by setting the Action property directly, however, these value-access properties do not appear on the request object until run time. To access them from the action page, you must type in the generated property names. §

When you have connected the form to a target page by dragging the connection plug from the form to the page, you can see the value-passing properties of the request object in the Expression Editor. (Note that this is not the case when you specify the URL of the target page directly in the Action property of the form.) When you edit a JavaScript-valued property of a component on the target page, the Expression Editor allows you to retrieve the form values from the request object.

Follow these steps to retrieve form values:

1. Display the target page in the Page Editor.

2. Display the server component (such as Database Form Handler or Send Mail from Server) in the Inspector.

3. Select a property that should use one of the values submitted with the form. This must be a JavaScript-valued property, as indicated by the equal-sign (=).

4. Click the equal-sign (=) to bring up the Expression Editor.

5. In the Expression Editor, click the request object. Its properties appear in the right-hand list. If you have connected the form and page interactively, the list includes the runtime properties with the names of the form elements (such as _Text1).

6. Double-click a property name. The JavaScript that accesses the value is placed in the Expression text box.
   Note that the runtime properties appear in the list only if the form has been connected to this page interactively. If the form has not yet been connected, or if you made the connection by setting the form's Action property directly, type the property accessor directly into the Expression text box--for example, request._Text1.

7. You can edit the expression if you wish. For example, you can double-click another property and place a plus sign between the two accessors to concatenate the values, or concatenate property values to strings.

8. Click Set Value to enter the completed expression as the value of the property you are editing.

Adding Code to an Application

• Some properties can have values that are fragments of JavaScript code. These code fragments are evaluated at run time to derive the property value. These values are called expressions, and you can edit them using the Expression Editor. See "Creating JavaScript Expressions."
• When you specify an event connection, Visual JavaScript generates an event handler in client-side JavaScript code. You can see and edit the code that is generated in the bottom section of the Connection Builder, which is a text editor.

• The Client Script component contains client-side JavaScript code.
• The Server Script component contains server-side JavaScript code.

For the Client Script component you can specify, in the Source File property, a file containing JavaScript code. This code is run when the page is loaded. If you specify a source file, the JavaScript Code property is not considered.

You can use script components to modularize your application logic as it becomes more complex. They can, for example, contain initialization or helper functions that you can call in the code fragments that you specify with the Script Builder and Expression Builder, making these code fragments more manageable.

Last Updated: 11/06/97 13:24:52