iConsole Search Definition Reference Guide › Search Definition › Multi-Select List Parameters

Multi-Select List Parameters

Parameters with type="list" used in conjunction with multiple="true" can be rendered in several different ways. Prior to version 12.5 the list was displayed as a drop-down list that allowed more than one selection. However, this provides challenges for accessibility so when requires="12.5" is specified the list is rendered either as a set of checkboxes (when there are 4 or fewer items) or as a ‘shuttle’ control which shows two lists with buttons to move items between the ‘available’ and ‘selected’ lists. The default behavior can be overridden if desired; when a list contains more than 4 items it can be rendered as a set of checkboxes by specifying attrs="shuttle:false" and the converse is true for rendering small lists as a ‘shuttle’.

Lists can be specified with or without values and this affects the value passed to the SP.

When no values are specified for the list items, such as the following example:

<parameter name="lstX" type="list" multiple="true" argpos="1" >
  <option>One</option>
  <option>Two</option>
  <option>Three</option>
  <option>Four</option>
</parameter>

If the user selects a single value, the index of the item is passed to the stored procedure as an integer. For example, if the user selects 'Two' the value passed is 2.

But what happens if the user selects multiple values? So that a single integer value can still be passed to the stored procedure, the selected values are used to set bits in the integer (bitmap) and the value is made negative to indicate that it's a multiple selection. For example, if the user selects 'Two' (bit 2 = 2) and 'Four' (bit 4 = 8) the value passed is -10.

Since the value passed to the stored procedure is a 64 bit integer, this means that a maximum of 63 items may be included in this kind of multi-select list.

When (from version 4.7 onwards) the list options are given explicit values to be passed to the stored procedure. In order to avoid being mistaken for the first form, the option values must all be non-numeric.

<parameter name="lstY" type="list" multiple="true" argpos="1" >
  <option value="one">One</option>
  <option value="two">Two</option>
  <option value="three">Three</option>
  <option value="four">Four</option>
</parameter>

If the user selects a single value, the option value is passed to the stored procedure as a string. For example, if the user selects 'Two' the value passed is 'two'.

If the user selects multiple values these are passed as a comma-separated list. For example, if the user selects 'Two' and 'Four' the value passed is 'two,four'.

Note: If a comma-separated list of values is required even when some or all of the values are numeric (or default index values are used) this can be achieved by adding the attribute attrs="text" to the list parameter definition.