Parent | Child | Previous | Next
 
JavaScript

listObj.setValue Method

Syntax

listObj.setValue(value, [flagFireChangeEvent]);

Arguments

valueAny Type JSON Object

The value you want to set. Can also be a JSON object for advanced use cases. See examples below.

A List's value is based on the 'Return value' property specified in the List Builder.
flagFireChangeEventboolean

Default value is true. A true/false value indicating whether or not the change event should be triggered. If false, the change event will not fire.

Description

Set the value of the List.

Discussion

Sets the value of the List causing the corresponding row(s) in the List to be selected. The value of a List is based on the setting in the List Builder for the List's 'Return value' property.

In the case of List that uses client-side grouping, you can also select rows based on group names. For example, select all of the rows for records in the 'California' group.

In the example below, the List value is set to 'ALFKI'.

var listObj = {dialog.object}.getControl('LIST1');
if (listObj) {
    listObj.setValue('ALFKI');
}
The List's 'Return Value' property must be set to 'CustomerId' since 'ALFKI' is a CustomerId 'value'

When the value is set, the change event is fired. When the change event is fired, watch events are triggered. Watch events are created for calculated fields and show/hide events based on the value of the List, as well the logic that updates the dirty state for the List. You can also add your own watch events. To prevent the change event from executing, you can pass in an optional second parameter to setValue(). The second parameter defines whether or not the change event should be fired. If false is passed in, the change event and subsequently watch events are not executed:

//Set value and do not fire the change event:
listObj.setValue('ALFKI',false);
You can also set the value of a List using the generic {dialog.object}.setValue() method. The .setValue() method for the List is convenient if you already have a pointer to the List control.

Example: Selecting Multiple Rows

An object can be passed in instead of a single value to select rows in the List. This method can be used to select multiple rows in Lists with multi-selection enabled. For example, to select all rows, pass ina object with the property select set to 'all':

//Select all rows in a List (that has been configured to allows multiple selections)
var options = {};
options.select = 'all';
listObj.setValue(options);

The group option can be used to select rows that contain the same value. For example, you can select all rows with the value of 'CA' or 'MA' as follows:

//Select all rows in the 'CA' and 'MA' groups (de-selecting any existing rows)
var options = {};
options.select = 'group';
options.groups = ['CA','MA'];
options.additive = false;
listObj.setValue(options);

The additive property defines whether or not the matching rows should be added to the current selection. For example, the following will add all rows in the 'NY' group to the existing selected rows in the List:

//Select all rows in the 'NY' group (keeping any existing selections)
var options = {};
options.select = 'group';
options.groups = ['NY'];
options.additive = true;
listObj.setValue(options);

Example: Selecting Rows with List Virtualization

If List 'virtualization' is enabled, you can select all of the rows on a current page of records as follows:

//In a List that has 'virtualization' turned on, select all rows in the current 'page' of records:
var options = {};
options.select = 'view';
options.additive = false;
listObj.setValue(options);

Example: Add Value to Current Selection

The select: 'add' property can be usd to set the select row(s) in a List. If the List control is configured to allow multiple selection, the following code will select multiple rows:

// Select rows with a value of 'Smith' or 'Jones'
listObj.setValue({select: 'add', value : ['Smith','Jones']});

Example: Remove Value from Current Selection

Rows in a List can be deselected by passing in the select: 'remove' option when using setValue(). For example, the following code will deselect multiple rows:

// Deselect rows with a value of 'Smith' or 'Jones'
listObj.setValue({select: 'remove', value: ['Smith','Jones']});

Example: Toggle Selected State of Items in the Value Array

You can toggle the selected state of the specified rows using select: 'toggle'. For example, the following will toggle the selected state for the rows 'Smith' and 'Jones':

// Toggle the selected rows if they have a value of 'Smith' or 'Jones'
listObj.setValue({select: 'toggle', value: ['Smith','Jones']});

Example: Select Matching Rows

If select: 'match' is specified, rows can be selected dynamically using a function. The function is specified with the match parameter. The value of the row and the data in the row will be passed to the function. The function must return a true or false value. If it returns true, the row will be selected. For example:

// Select rows that match the criteria specified by the function
var value = {};
value.select = 'match';
value.match = function(value, data) function(value,data) {
    //value and data for the current row
    if(data.Country == 'USA') return true;
    else return false;
};

listObj.setValue(value);

Example: Adding Rows to the Existing Selection

The additive: true option will add the matching rows to the set of existing selected rows. For example:

// Add rows that match the criteria specified by the function
var value = {};
value.additive = true; // add matching rows to existing selected rows
value.select = 'match';
value.match = function(value, data) function(value,data) {
    //value and data for the current row
    if(data.Country == 'UK') return true;
    else return false;
};

listObj.setValue(value);

See Also