HELP!
© XpertRule

Accessing Object List Value Properties

List type Objects have an extra set of system properties associated with the List values. The developer can also add their own user defined properties.

Get the number of List Values

To scan list value properties often requires knowing how many values are defined in the List Object which is returned by the nValues Object property

For example:

 if (#Grade.nValues == 1){
   xpertrule.message("Only one list value in this question");
 }

An alternative way of getting the number of list values:

 if (#Grade.value().length == 1){
   xpertrule.message("Only one list value in this question");
 }

Accessing an array of List Values Properties

Each list value has a number of system properties as well as any user defined properties which can be accessed via an array as follows:

 var valArr = #Grade.value();

Note that the array of JavaScript Objects returned by the above are values of the following JavaScript Object:

{
    aName: string /*The internal name of the value*/
    selected: boolean /*Has this value been selected*/
    valid: boolean /*Is this value valid i.e.*/
    visible: boolean /*Is this value visible in dialog controls*/
    [User defined Value Property Name]: the type defined by the developer (Numeric or Text)  /*User defined list value property*/
}
The order of the values in the list value(index) corresponds to the order in which the list values are defined.

Accessing the Selected Value's Properties of a List Object

You can access the properties of the selected list value (assuming one has been selected) by specifying the value index of 0:

 xpertrule.message(#Grade.value(0).aName + " : " + #Grade.value(0).displaytext);
If no value is currently selected, the function returns null. If multiple list values are selected (i.e. the question is a Multi-Select List) the function returns an Array of value objects

Accessing a Specified Value's Properties

You can access any given list value's Object by specifying the value's index:

 var dirVal = #Grade.value(1); // the JavaScript Object for the first value in the list
 xpertrule.message(dirVal.aName); // display the first list value

To access a user defined list value property called "displaytext":

if (#Grade.value(1).displaytext === '') {
    #Grade.value(1).displaytext = "Big Boss"; // set the displaytext property of the first value in the list
}

To display the name and "displaytext" of each value in a list Object called "Grade":

var loop;
for (loop = 1; loop <= #Grade.value().length; loop = loop + 1) {   
  xpertrule.message(#Grade.value(loop).aName + " : " + #Grade.value(loop).displaytext);
}

Using the inst Object property

Another way to access List Value properties is via the Object's inst method. This has the benefit of allowing the developer to write code that can handle different list value properties by passing the property name as a string parameter.

For example if displaytext of the first list value is empty then set it to a value:

if (#Grade.inst("displaytext", 1) === '') {
    #Grade.inst("displaytext", 1, "Big Boss"); set the displaytext property of the first value in the list
}

Or, to get the list value property of the currently selected List value (assuming one has been selected):

xpertrule.message(#Grade.inst("displaytext"));

Notes

The .inst method can be called with 1, 2 or 3 parameters:

  • .inst(object list value property name) Get the value of the specified object list value property for the SELECTED value. If the object is a multi-select List, the return value will be an ARRAY instead of a single value.
  • .inst(object list value property name, value index) Get the value of the specified object list value property. Setting it to 0 gets the property of the selected value.
  • .inst(object list value property name, value index,new value) Set the value of the specified value property for specified list value.
If setting a new value, the TYPE of the new value must match the list property type. (see Object Properties for more details)

The following examples shows 3 methods that return the current runtime value for an Object:
  • xpertrule.message(#MyList.value(0).aName);
  • xpertrule.message(#MyList.inst("aName"));
  • xpertrule.message(#MyList.val());
The .value() & .inst() methods only apply to List type Objects whereas the .val() method applies to all Object types

On This Page