Parent | Child | Previous | Next
 
JavaScript

{grid.object}setValue Method

Syntax

{grid.Object}.setValue(part, name, row, value [, honorChangeEvent]);

{grid.Object}.setValue(part, name, value [, honorChangeEvent]);

Arguments

partstring

'G' , 'D' or 'S' (Grid, Detail View or Search part). Must be UPPERCASE.

namestring

The control to set the value. The name must be UPPERCASE. For example, 'STATE' or 'FIRST_NAME'.

If specifying multiple values for a control, such as a checkbox, append '[]' to the name. For example, 'COLORS[]'.

rownumber

Required if part has been set to 'G'. The row number in the grid to update. If part has been set to 'S' or 'D', row should be omitted. New rows are specified as a negative number (e.g. -1, -2, etc.)

valueAny Type array of values

The value to set in the control. If the control can have multiple values, specify the value as an array of values. For example, ['green','blue','orange'].

honorChangeEventboolean

Default = true. If true, watch events (such as calculated expressions or client-side show/hide expressions) that reference the field will be triggered. If false, watch events will not be triggered.

Description

Set the value of a control in the Grid, Search or Detail View part.

Discussion

Part is 'G' , 'D' or 'S' (Grid, Detail View or Search part). Row is only needed for Grid part. For new record rows, row is negative. By default honorChangeEvent is true. This causes the onChange event for the control to fire when the value is set.

The 'name' and 'part' parameters MUST be all UPPERCASE.

Also, unlike standard JavaScript techniques to set the value of a control, the .setValue() method sets the control's state in the Grid Object to be dirty (in the same way that the control becomes dirty if the user types a value into the control). This will set the row to become dirty and the Submit button to become enabled. For checkbox and Multi-value Dropdownbox Controls - See the example for information on how to set the value of a multi-valued control (e.g. Checkbox or multi-line Dropdownbox).

You cannot use this method for a field in the Search Part that has been configured as a 'Range' search. See "Setting the Value of a 'range' Field in the Search Part" below for more information

Examples

Set value in 'LASTNAME' field from the Grid part, row 4. Note that field name must be uppercase.

{grid.object}.setValue('G','LASTNAME',4,'Smith');

Set value in 'LASTNAME' field from the Grid part, 'current row'. Note that field name must be uppercase.

{grid.object}.setValue('G','LASTNAME',{grid.rowNumber},'Smith');

Setting the value in 'COLORS' checkbox field from the Grid part, 'current row'. Note that brackets [] are appended to the field name and that the value is an array. This will set the value of the 'COLORS' field to 'blue' and 'red':

{grid.object}.setValue('G','COLORS[]',{grid.rowNumber},['blue','red']);

Setting the value for the 'LASTNAME' field in the Search part. Note that row number has been omitted.

{grid.object}.setValue('S','LASTNAME','Smith');

Setting the value for the 'LASTNAME' field in the Detail View part. Note that row number has been omitted.

{grid.object}.setValue('D','LASTNAME','Smith');

Set the value in 'FAVORITECOLOR' in the Search part. Assume that 'FAVORITECOLOR' is a multi-valued field (e.g. a Checkbox control or a Dropdown control configured to allow multiple values):

{grid.Object}.setValue('S','FAVAORITECOLOR[]',['alpha','beta','gamma']);

Notice that the fieldname has a trailing [] - to indicate that it is an array of values, and the values you want to set are passed in in the form of a JavaScript array.

Setting the Value of a 'range' Field in the Search Part

You can't use .setValue() to set the value of 'range' fields in the Search Part. You have to use the $() and low-level JavaScript functions instead:

// Get a pointer to the "from" control for STARTDATE:
var startDateEle = $('{grid.componentName}.S.STARTDATE');
startDateEle.value = '12/1/2010';

// Get a pointer to the "to" control for STARTDATE:
var endDateEle = $('{grid.componentName}.S._TO.STARTDATE');
endDateEle.value = '12/31/2010';

Example: Multiple Values in the Search Part

The Search Part allows you to define the initial value of each control in the Search Part. However, in the case of a multi-valued controls, such as a Checkbox control, you might want to set the initial value of the control to two or more checked values. You can do this by specifying some JavaScript in the client-side onSearchRender event. Use the .setValue() method and pass in an array of the initial selections. For example:

{grid.object}.setValue('S','COLOR[]',['Red','Green']);

See Also