When an HTML or CFML form contains a list of check boxes with the same name or a multiple-selection list box (that is, a box in which users can select multiple items from the list), the user's entries are made available as a comma-delimited list with the selected values. These lists can be useful for a wide range of input types.

When you place a series of check boxes with the same name in a form, the variable that is created contains a comma-delimited list of values. The values can be either numeric values or alphanumeric strings. These two types of values are treated slightly differently.

Suppose you want a user to select one or more departments using check boxes. You then query the database to retrieve detailed information on the selected departments. The code for a simple set of check boxes that lets the user select departments looks like the following:

The user sees the name of the department, but the value attribute of each check box is a number that corresponds to the underlying database primary key for the department's record. If the user checks the Marketing and Sales items, the value of the SelectedDepts form field is 2,4 and you use the SelectedDepts value in the following SQL statement:

The ColdFusion server sends the following statement to the database:

To search for a database field that contains string values (instead of numeric), modify the checkbox and  cfquery  syntax to make sure that the string values are sent to the data source in single-quotation marks ('). The first example searched for department information based on a numeric primary key field called Dept_ID. Suppose, instead, that the primary key is a database field called Dept_Name that contains string values. In that case, your code for check boxes should look like the following:

If the user checked Marketing and Sales, the value of the SelectedDepts form field would be the list Marketing,Sales and you use the following SQL statement:

In SQL, all strings must be surrounded in single-quotation marks. The  ListQualify  function returns a list with the specified qualifying character (here, a single-quotation mark) around each item in the list.  If you select the second and fourth check boxes in the form, the following statement gets sent to the database:

A multiple-selection list box is defined by a select or cfselect tag with a multiple or multipe="yes" attribute and a size attribute value greater than 1. ColdFusion treats the result when a user selects multiple choices from a multiple-selection list box like the results of selecting multiple check boxes. The data made available to your page from any multiple-selection list box is a comma-delimited list of the entries selected by the user; for example, a list box could contain the four entries: Training, Marketing, HR, and Sales. If the user selects Marketing and Sales, the form field variable value is Marketing, Sales. You can use multiple-selection lists to search a database in the same way that you use check boxes.

Suppose you want the user to select departments from a multiple-selection list box. The query retrieves detailed information on the selected departments, as follows:

If the user selects the Marketing and Sales items, the value of the SelectDepts form field is 2,4. If this parameter is used in the following SQL statement:

The following statement is sent to the database:

Suppose you want the user to select departments from a multiple-selection list box. The database search field is a string field. The query retrieves detailed information on the selected departments, as follows:

If the user selects the Marketing and Sales items, the SelectDepts form field value is Marketing,Sales. Just as you did when using check boxes to search database fields containing string values, use the ColdFusion  ListQualify  function with multiple-selection list boxes:

The following statement is sent to the database: