Using Script Functions as Event Handlers

In this section:

One of the components in a WebFOCUS Maintain project is a script. A script contains stand-alone functions, written in either JavaScript or VBScript for execution on the client. The script code can either be embedded in your form or you can use a pointer within the form to a script file located on a web server.

Why use scripts? JavaScript and VBScript functions can perform local validation, that is, they can validate user interaction on a form without having to return to the server.

For example, JavaScript and VBScript functions can do the following, all without connecting to the server:

Of course, this validation can be done with the Maintain language, but using JavaScript or VBScript is an optimization that saves you a trip back to the server.


Top of page

x
About JavaScript and VBScript

JavaScript is a small, object-based scripting language that you can use to create functions that can be embedded in HTML pages. When you execute your application, your browser will interpret the code and perform the actions required.

VBScript is similar to JavaScript, except that it is only supported in Microsoft Internet Explorer. All of our examples will use JavaScript. However, you can use VBScript to perform similar functions.

This help system document will show how to use several JavaScript functions. However, it is not a complete guide to JavaScript.

Tip: JavaScript and VBScript are case-sensitive. Make sure you are using the correct capitalization, especially when referring to controls in a form or to Maintain functions.


Top of page

x
Using Script Functions in Your Project

How to:

There are two ways to write JavaScript and VBScript functions:



x
Procedure: How to Write a JavaScript or VBScript Function in the Event Handler Editor
  1. Open the Event Handler editor.
  2. Select a control and an event from the drop-down lists.
  3. Click the JavaScript JavaScript button button or VBScript VBScript button button.

    Type the code for your function in the box.

When the event occurs (for example, a button being clicked), the browser will execute the function.



x
Procedure: How to Assign a JavaScript or VBScript Function in a Script Library to an Event

If you code a function in a script library, you must then assign this function to an event (for more on script libraries, see Managing Script Libraries).

  1. Create the script library and code the function in it.
  2. Open the Event Handler editor.
  3. Select a control and an event from the drop-down lists.
  4. Click the JavaScript JavaScript button button or VBScript VBScript button button.
  5. Enter the name of the JavaScript or VBScript function that you would like to call in the box using the following syntax:
    function(parameters);
  6. Drag the script library that contains the function from the Explorer to the open form in which you are using it. (This is the Object Explorer, not the MDE Project Explorer.) This ensures that WebFOCUS Maintain includes the script only in the page that is using it. Select either to Embed script or Link script. Note that linked scripts must be assigned a web server location during the deployment phase.

Tip: If you do not see your script files listed for your project in the Explorer, you may need to add a filter for the file type. You can do this from the Edit Filters tab in the properties sheet for the project.

When the event occurs (for example, a button being clicked), the browser will execute the function.


Top of page

x
Using Script Functions For Validation

How to:

When you create a function to perform local validation, the function generally performs three tasks:

Tip: JavaScript and VBScript are case-sensitive. Make sure you are using the correct capitalization, especially when referring to controls in a form or to Maintain functions.



x
Syntax: How to Use the JavaScript Alert Function

The JavaScript alert function displays a pop-up window with an OK button. The syntax is

alert("text");

where:

text

Is informational text that is displayed in the pop-up window. You can enter a variable name here as well (omit the quotation marks).

Note: We are providing the syntax for this function here, but see your JavaScript documentation for a complete description of this language.



x
Syntax: How to Use the JavaScript Confirm Function

The JavaScript confirm function displays a pop-up window with a question and OK and Cancel buttons. If the end user clicks OK, the function returns TRUE. If the end user clicks Cancel, it returns FALSE. The syntax is

value = confirm("text");

where:

value

Is the name of the variable set to either TRUE or FALSE, depending on what the end user clicks.

text

Is the text of the question you are asking the user. It should be a yes or no question. You can enter a variable name here as well (omit the quotation marks).

Note: We are providing the syntax for this function here, but see your JavaScript documentation for a complete description of this language.



x
Syntax: How to Use the JavaScript Prompt Function

The JavaScript prompt function displays a pop-up window with a message, an edit box, and an OK button. The function returns the value the end user enters in the text box. The syntax is

value = prompt("text"[, defaultvalue]);

where:

value

Is the name of the variable to contain the value the end user enters in the edit box.

text

Is the text that appears in the pop-up window. You can enter a variable name here as well (omit the quotation marks).

defaultvalue

Is an optional parameter that places a default value in the text box.

Note: We are providing the syntax for this function here, but see your JavaScript documentation for a complete description of this language.



x
Syntax: How to Use the IWCTrigger Function to Call a Maintain Function From Your Script Handler

The syntax for the IWCTrigger function is

IWCTrigger("functionname"[, "parameter"]

where:

functionname

Is the name of the Maintain function you are calling.

Note: Scripts are case-sensitive, so you must specify the name using the same uppercase and lowercase letters that you used to name the function in the Maintain procedure.

parameter

Is an optional parameter that you can pass to the Maintain function.

The called function can retrieve this parameter using the following syntax

formname.Triggervalue

where:

formname

Is the name of the form.

Note:



Example: Validating End User Input With JavaScript

Suppose you have an application that prompts an end user to enter a numerical value (in the OrderNo edit field) and click a Submit button. The application then executes a Maintain function called DoProcess. The Click event in the Submit Button is assigned to the Maintain function DoProcess.

The name of the form is OrderStatus and the name of the edit box into which the end user enters a number is OrderNo.

OrderStatus example image

However, before executing DoProcess, you want the Submit button to execute a JavaScript function (called test_it) that will test the value in OrderNo. The value in OrderNo must not be blank, and can only contain the digits from 0 to 9.

Create a new JavaScript library by right-clicking the project folder in the Explorer, clicking New in the shortcut menu, and then clicking Project file. In the Create a New File dialog box, give your JavaScript library a name.

Then open the JavaScript library and enter the code for the test_it function in your script library.

Here is the JavaScript code for test_it:

   function test_it()
    {
    okay=1 
1.  fldvalue=document.OrderStatus.OrderNo.value
2.  if (fldvalue == '')
     alert("Please enter some data!");
    else
     { 
3.   for(var i=0;i<fldvalue.length;i++)
        {
        var ch=fldvalue.substring(i,i+1) 
4.      if (ch<"0" || "9"<ch)
           { 
5.         if (ch != ".")
              {
               okay=0
               alert("Please enter only numeric data!");
               break
              }
           }
        } 
6.   if (okay==1)
         IWCTrigger("DoProcess")
     }
  }
  1. This line of code sets fldvalue to be the value of OrderNo on OrderStatus on this HTML document.
  2. The first if test checks to see if fldvalue is blank. If so, it pops up a dialog box saying, “Please enter some data!”
  3. If fldvalue is not blank, then test_it enters a for loop that lasts for the length of fldvalue.
  4. Within the for loop, test_it tests each character in fldvalue.
  5. If test_it finds a character that is less than 0 or greater than 9 and that character is not a decimal, then it sets okay to 0, alerts the user to “Please enter only numeric data!” and breaks out of the for loop.
  6. The last if statement just checks to see if test_it has gotten through all of the for loop with okay still equal to 1, in which case it can execute DoProcess (using IWCTrigger).

With the function complete, you must now to assign it to the Submit button in place of DoProcess. See Executing a JavaScript Function From a Button.



Example: Executing a JavaScript Function From a Button

In Validating End User Input With JavaScript, you started with an application that prompts an end user to enter a numerical value (in the OrderNo edit field) and click a Submit button. The application then executes a Maintain function called DoProcess. (The Click event in the Submit Button is assigned to a Maintain function called DoProcess.)

You created a JavaScript function named test_it that tested the value in OrderNo to make sure it was numeric. With the script complete, you must now assign it to the Submit button in place of DoProcess.

OrderStatus example image

  1. Open the OrderStatus form.
  2. Drag Script1 from the Explorer to the open OrderStatus form. This ensures that WebFOCUS Maintain includes this script only in OrderStatus.
  3. Open the Event Handler editor for the form OrderStatus.
  4. From the list of controls on the form, select SubmitButton.
  5. From the list of events that could happen to that control, select Click.
  6. Click the JavaScript button to indicate that clicking SubmitButton would execute a JavaScript.
  7. Type test_it( ); in the box.

OrderStatus example image

Now, when end users executing this application click the Submit button, their browsers execute the test_it function.


Top of page

x
Using Script Functions With HTML Tables

How to:

There is a special case when an end user executes a JavaScript function by clicking an HTML Table. In this case, you can use code in your function to identify the row number, column number, or value of the cell clicked by the end user.



x
Syntax: How to Determine Row Number, Column Number, or Cell Value When an HTML Table Is Clicked Using a Script

If your function is executed by an end user clicking on an HTML Table, then you can use special syntax in your function to determine what part of the HTML table the end user clicked.

If you want to determine the row number, use:

document.formname.tablename_ClickRow.value

The header row returns 0, and the first data row returns 1.

If you want to determine the column number, use:

document.formname.tablename_ClickColumn.value

If you want to determine the contents (text) of the cell, use:

document.formname.tablename_Value.value

Top of page

x
Using Script Functions to Turn Secure Sockets Layer On and Off

You also use JavaScript functions to turn a Secure Sockets Layer on and off (which you might use when you want to perform private communications, such as transmitting credit card information for E-commerce applications).


Top of page

x
Using Script Functions to Make Controls Visible

How to:

You can use script functions to dynamically make a control visible.



x
Syntax: How to Make a Control Visible
document.Forname.Controlname.style.visibility="visible";

where:

Formname

Is the name of your form.

Controlname

Is the name of your control.


Top of page

x
Managing Script Libraries

How to:

You manage script libraries in the Explorer. However, you must set up the Explorer to view script files first. For more information, see How to View New File Types in the Explorer. (The default extension for JavaScript files is .js; the default extension for VBScript files is .vbs.)

Then, from the Explorer, you can:



x
Procedure: How to Edit a Script Library
  1. Right-click the script library.
  2. In the shortcut menu, click Edit source.

WebFOCUS Maintain opens the Script Editor where you can make changes to your script library. See Using Script Functions in Your Project for more information.

Your next step is to associate your script library with a form. See How to Associate a Script Library With a Form.



x
Procedure: How to Associate a Script Library With a Form

To ensure that a form will contain the script functions it uses, you can associate the script library with the form.

  1. In the Explorer, select the script library.
  2. Drag the script library to the open form (in the Form Editor). Make sure you drag the script library to an empty space on the form (not on top of a control).

Your last step is to assign the functions you have coded in your script library to events. See How to Assign a JavaScript or VBScript Function in a Script Library to an Event.


Top of page

x
Running and Debugging JavaScript and VBScript Functions

WebFOCUS Maintain can parse the syntax of your script functions to see if they are correct. If WebFOCUS Maintain discovers incorrect syntax, you will see an exclamation mark in the left margin next to the incorrect line of syntax and an error message in the General tab of the Output window. You can double-click the line in the Output window to open the script to the offending line.

Keep in mind that JavaScript and VBScript are case-sensitive, so one common cause of errors is referring to functions or controls by the correct name, but in the wrong case.


WebFOCUS