CFSELECT |
Description Constructs a drop-down list box form control. Used within a cfform tag. You can populate the list from a query, or by using the HTML option tag.
Category Forms tags
Syntax
    <cfselect
       name = "name"
    label = "label"
    style = "style specification"
       size = "integer"
       required = "yes" or "no"
       message = "text"
       onError = "text"
       multiple = "yes" or "no"
       query = "queryname"
       value = "text"
       display = "text">
       group = "query column name
       queryPosition = "above" or "below"
       selected = "value or list"
    onKeyUp = "JavaScript or ActionScript"
    onKeyDown = "JavaScript or ActionScript"
    onMouseUp = "JavaScript or ActionScript"
    onMouseDown = "JavaScript or ActionScript"
    onChange = "JavaScript or ActionScript"
    onClick = "JavaScript or ActionScript"
    visible = "Yes" or "No"
    enabled = "Yes" or "No"
    tooltip = "tip text"
    height = "number of pixels" Flash only
    width = "number of pixels" Flash only
    >
    zero or more HTML option tags
    </cfselect>
See also cfapplet, cfcalendar, cfform, cfformgroup, cfformitem, cfgrid, cfinput, cfslider, cftextarea, cftree; Chapter 26, "Introduction to Retrieving and Formatting Data," in ColdFusion MX Developer's Guide
History ColdFusion MX 7:

- Added support for specifying multiple values to the selected attribute.
- Deprecated the passthrough attribute. The tag now supports all HTML select tag attributes directly.
- Added on-prefixed attributes.
- Added enabled, group, height, label, queryPosition, tooltip, visible, and width attributes.

The following table lists attributes that ColdFusion uses directly. The tag also supports all HTML select tag attributes that are not on this list, and passes them directly to the browser.

Note: | Attributes that are marked as Flash only are not handled by the skins provided with ColdFusion MX. They are, however, included in the generated XML.

Note: | Attributes that are marked as Flash only are not handled by the skins provided with ColdFusion MX. They are, however, included in the generated XML.

Usage This tag requires an end tag and can include HTML option and optgroup child tags. To ensure that a selected list box item persists across postbacks, use the cfform preserveData attribute with a list generated from a query. (This strategy works only with data that is populated from a query.)

If the cfform preserveData attribute is true and the form posts back to the same page, and if the control is populated by a query, the posted selection(s) for the cfselect control are used instead of the Selected attribute. For controls that are populated with regular HTML option tags, the developer must dynamically add the Selected attribute to the appropriate option tag(s).

The group option generates a query using SQL GROUP BY syntax and places the value column entries from each group in an indented list under the group column's field value. This option generates an HTML optgroup tag for each entry in the group column.

Close each HTML option tag in the cfselect tag body with a </option> end tag. If you do not do so, and you specify queryPosition="below", the first item from the query might not appear in the list.

For this tag to work properly. the browser must be JavaScript-enabled.

For more information, see the cfform tag entry.

Example The following example lets you select one or more employee names from a list of all employees, grouped by departments, and displays the selected names and the employee's email addresses. It includes an option to get data for all employees.
    <!--- Get the employee names from the database. --->
    <!--- Use SQL to create a Name field with first and last names. --->
    <cfquery name = "GetAllEmployees" dataSource = "cfdocexamples"
          cachedwithin="#createTimeSpan(0,1,0,0)#">
       SELECT Emp_ID, EMail, Phone, Department, FirstName, LastName, FirstName +' '
          +lastName as Name
       FROM   Employees
       GROUP BY Department, Emp_ID, EMail, Phone, FirstName, LastName, FirstName
    </cfquery>

    <h2>cfselect Example</h2>
    <!-- The cfif statement is true if the form was submitted.
       Show the selected names. --->
    <cfif IsDefined("form.employeeid")>
       <!--- The form was submitted. --->
       <h4>You Selected the following employees</h3>
       <cfif form.employeeid IS "">
          <!--- Select All option was selected. Show all employees. --->
          <cfoutput query="GetAllEmployees">
             #name#<br>
             Email: #email#<br><br>
          </cfoutput>
       <cfelse>
          <!--- Use a query of queries to get the data for the selected users.
             Form.employeeid is a comma-delimited list of selected employee IDs. --->
          <cfquery name = "GetSelectedEmployees" dbtype="query">
             SELECT Emp_ID, EMail, Phone, Department, FirstName, LastName, FirstName
                +' ' +lastName as Name
             FROM   GetAllEmployees
             WHERE Emp_ID in (#form.employeeid#)
          </cfquery>
          <!--- Display the names and e-mail addresses from the query. --->
          <cfoutput query="GetSelectedEmployees">
             #firstName# #lastName#<br>
             Email: #email#<br>
             <br>
          </cfoutput>
       </cfif>
    </cfif>

    <!--- The cfform tag posts back to the current page. --->
    <h3>Select one or more employees</h3>
    <cfform action = "#CGI.SCRIPT_NAME#">
       <!--- Use cfselect to present the query's LastName column, grouped by
    department.
          Allow Multiple selections.--->
       <cfselect
          name = "employeeid"
          size = "15"
          multiple="yes"
          required = "Yes"
          message = "Select one or more employee names"
          query = "GetAllEmployees"
          group="Department"
          display ="name"
          value ="emp_id"
          queryPosition="Below">
          <!--- Add an option to select all employees. --->
          <option value = "">Select All</option>
       </cfselect><br><br>
       <input type="Submit">
    </cfform>

NAME |
| Required;
| All
Name of the select form element.

LABEL |
| Optional;
| Flash and XML
Label to put next to the control on a Flash or XML-format form.

STYLE |
| Optional;
| All
In HTML or XML format forms, ColdFusion passes the style attribute to the browser or XML. In Flash format, must be a style specification in CSS format, with the same syntax and contents as used in Macromedia Flex for the corresponding Flash element.

SIZE |
| Optional;
| All
Default value: "1" Number of entries to display at one time. The default, 1, displays a drop-down list. Any other value displays a list box with size number of entries visible at one time.

REQUIRED |
| Optional;
| All
Default value: "No"

- Yes: a list element must be selected when the form is submitted.

Note: This attribute has no effect if you omit the size attribute or set it to 1, because the browser always submits the displayed item. You can work around this issue: format forms by having an initial option tag with value=" " (note the space character between the quotation marks).

- No

MESSAGE |
| Optional;
| All
Message to display if required = "Yes" and no selection is made.

ONERROR |
| Optional;
| HTML and XML
Custom JavaScript function to execute if validation fails.

MULTIPLE |
| Optional;
| All
Default value: "No"

- Yes: allows selecting multiple elements in drop-down list.
- No

QUERY |
| Optional;
| All
Name of query to populate drop-down list.

VALUE |
| Optional;
| All
Query column to use for the value of each list element. Used with the query attribute.

DISPLAY |
| Optional;
| All
Default value: "Value of value attribute" Query column to use for the display label of each list element. Used with the query attribute.

GROUP |
| Optional; HTML and XML
Query column to use to group the items in the drop-down list into a two-level hierarchical list.

QUERYPOSITION |
| Optional;
| All
Default value: "above" If you populate the options list with a query and use HTML option child tags to specify additional entries, determines the location of the items from the query relative to the items from the option tags:

- above: puts the query items above the options items.
- below: puts the query items below the options items.

SELECTED |
| Optional;
| All
One or more option values to preselect in the selection list. To specify multiple values, use a comma-delimited list. This attribute applies only if selection list items are generated from a query. The cfform preservedata attribute value can override this value.

ONKEYUP |
| Optional;
| All
Default value: "JavaScript (HTML/XML) or ActionScript (Flash) to run when the user releases a keyboard key in the control."

ONKEYDOWN |
| Optional;
| All
Default value: "JavaScript (HTML/XML) or ActionScript (Flash) ActionScript to run when the user presses a keyboard key in the control."

ONMOUSEUP |
| Optional;
| All
Default value: "JavaScript (HTML/XML) or ActionScript (Flash) to run when the user presses a mouse button in the control."

ONMOUSEDOWN |
| Optional;
| All
Default value: "JavaScript (HTML/XML) or ActionScript (Flash) to run when the user releases a mouse button in the control."

ONCHANGE |
| Optional;
| All
Default value: "JavaScript (HTML/XML) or ActionScript (Flash) to run when the control changes due to user action."

ONCLICK |
| Optional; HTML and XML
Default value: "JavaScript to run when the user clicks the control."

ENABLED |
| Optional; Flash
Default value: "Yes" Default value: "Boolean value specifying whether the control is enabled. A disabled control appears in light gray. The inverse of the disabled attribute."

VISIBLE |
| Optional; Flash
Default value: "Yes" Default value: "Boolean value specifying whether to show the control. Space that would be occupied by an invisible control is blank."

TOOLTIP |
| Optional; Flash
Default value: "Text to display when the mouse pointer hovers over the control."

HEIGHT |
| Optional; Flash
| The height of the control, in pixels.

WIDTH |
| Optional; Flash
| The width of the control, in pixels.