JavaScript

{dialog.object}setValue Method

Syntax

{dialog.Object}.setValue(name, value [, honorChangeEvent])

Arguments

namestring

The UX Control ID. For multi-value controls, a '[]' must be included after the control ID. For example, 'CHECKBOX_1[]'

valueAny Type Array

The value to set in the control. Depending on the control, this may be a single value or an array.

honorChangeEventboolean

Default = true. Causes the onChange event for the control to fire when the value is set. This includes watch events for client-side expressions (show/hide, enable/disable, calculated fields, etc) that reference the control as well as flags the field as dirty in the UX Component. If you don't want client-side events to be triggered, set the honorChangeEvent argument to false.

Description

Set the value of a control in the UX Component.

Discussion 

The setValue() method can be used to set the value of a control in a UX Component.

Unlike standard Javascript techniques to set the value of a control, the .setValue() method sets the control's state in the UX Object to be dirty (in the same way that the control becomes dirty if the user types a value into the control).

Example 

Set value in 'LASTNAME' field.

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

Repeating Sections 

If the field you want to set is in a Repeating Section, use 'name:rownumber' for the field name, otherwise the row with focus will be updated.

This example sets the value in 'LASTNAME' field in the 3rd row of a Repeating Section.

{dialog.object}.setValue('LASTNAME:3','Smith');

Multi-value Controls 

Checkbox and Multi-value Dropdownbox Controls that can have more than one value are set using array syntax. For example, assume that 'FAVORITECOLOR' is a checkbox control that can have multiple selections and you would like to set the value to 'alpha', 'beta', and 'gamma'. The example below will set the value:

{dialog.Object}.setValue('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.

List Fields 

Field values in a List control are set using a special syntax:

list::name_of_list::field_name::logical_row_number

where

  • name_of_list is the List control's ID.
  • field_name is the field in the list to update.
  • logical_row_number the row to update.

If you omit the row number, the field in the selected row is updated.

// Update City field in logical row 1 (second row of list):
{dialog.object}.setValue("list::LIST1::City::1","Athens");

// Update City field in current list row:
{dialog.object}.setValue("list::LIST1::City","Madrid");

See Also