Watch events

IN THIS PAGE

Watch Event JavaScript
Helper Functions
- How Helper Functions Convert to Javascript
Videos

Description

Execute custom JavaScript when a Grid control's value changes, is shown, or disabled with watch events.

Discussion

Watch events are executed whenever a value in a 'watched' control in the Detail View is changed. You can add your own watch events using the Watch events property to dynamically execute JavaScript to set properties of elements in a Grid when the value of a 'watched' control changes.

Watch events can be added to any control in Grid component for the following events:

When the chosen event is triggered for the selected controls, the JavaScript for the watch event will be executed.

Watch Event Type: Description
Calculated field: Executes code when the control's value is re-computed using a calculated expression.
Show/Hide controls: Executes code when controls are shown or hidden.
Enable controls: Executes code when controls are enabled or disabled.
Other: Executes code when the value for one or more watched fields changes.

Watch Event JavaScript

Your JavaScript for the watch event will have access to the data.rowNumber variable. data.rowNumber is the row number for the row for the control that triggered the watch event. The row number will be a positive value for existing rows and negative for new record rows.

You can use any JavaScript in the watch event as well as several Helper Functions that simplify writing JavaScript for a watch event.

var qty = {grid.object}.getValue('D','QUANTITY',data.rowNumber);
var price = {grid.object}.getValue('D','PRICE',data.rowNumber);

var total = price * qty;

{grid.object}.setValue('D','SUBTOTAL',data.rowNumber,total);

Helper Functions

Helper functions simplify the Javascript that you have to write in the Watch Events. For example, the previous JavaScript example could be rewritten to use the *gv() and *sv() helper functions, greatly simplifying the code:

var qty = *gv('QUANTITY');
var price = *gv('PRICE');

var total = qty * price;

*sv('SUBTOTAL',total);

The following helper functions can be used when creating the watch event:

Function: Description
*gvn(): Get a value from a control and convert it to a javascript number variable so that you can perform arithmetic operations on the value. Example: *gvn('quantity')
*gvl(): Get a value from a control and convert it to a javascript logical variable so that you can perform logical operations on the value. Example: *gvl('ismarried')
*gvd(): Get a value from a control and convert it to a javascript date variable so that you can perform date operations on the value. Example: *gvl('ismarried')
*gv(): Get a value from a control as a javascript string variable. Example: *gv('description')
*sv(): Set the value of a control to the value in a javascript variable. Example: *sv('total',computedTotal)
*svs(): Set the value of a control to the value in a javascript variable. Uses the ._setValue()method, so it enforces client-side formatting rules and sets the control as dirty. Can only be used for controls in a Grid or Detail Part row. Example: *svs('total',computedTotal)
*sa(): Set a property of a control to the value in a javascript variable. Example: *sa('quantity','style.color',computedColor)
*ac(): Add a class name to a control. Example: *ac('quantity','errorQuantity')
*rc(): Remove a class name from a control. Example: *rc('quantity','errorQuantity')
*gs(): Gets the CSS style for an element. Example: var style = *gs('quantity')
*ss(): Sets the CSS style for an element. Example: *ss('quantity','color:red;')
*$(): Get a pointer to a control in the Grid. Example: var ele = *$('quantity')
*setDisplay(): Shows or hides an object and its related label, and 'smart-field' button. Example: *setDisplay('DATEOFBIRTH','none');

The helper functions must all be converted to real Javascript before the Watch Event is executed. Alpha Anywhere will do this for you. If desired, however, you can manually convert the helper functions to JavaScript using the Convert Helper Functions to Javascript link.

How Helper Functions Convert to Javascript

Helper functions are converted to JavaScript before the watch event is executed. Alpha Anywhere does this for you by replacing the helper function with it's JavaScript equivalent. For example:

var qty = *gv('quantity');

This code would be converted into the following JavaScript:

var qty = {grid.object}._getValue('D','QUANTITY',data.rowNumber);

You do not need to use helper functions in your watch event.

Videos

User Defined Watch Event

A user defined watch event allows you to define JavaScript code that is executed when the value in a 'watched' field in the Grid component changes. In this video, we show how the label on the 'state' field can be changed to 'State' if the country is 'USA' and to 'Province' for all other countries.

Watch Video