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"
       required = "Yes" or "No"
       message = "text"
       onError = "text"
       size = "integer"
       multiple = "Yes" or "No"
       query = "queryname"
       selected = "column_value"
       value = "text"
       display = "text"
       passThrough = "HTML_attributes">
    </cfselect>

See also
cfapplet, cfform, cfgrid, cfinput, cfgridcolumn, cfgridrow, cfgridupdate, cfslider, cftextinput, cftree, cftreeitem

In addition to the listed attributes, you can use the following HTML attributes in the cfform tag without using the passThrough attribute. The tag does not use these attributes, but includes them in the HTML of the form tag that it generates and returns to the browser:

- class
- id
- onBlur
- onChange
- onClick
- onDblclick
- onFocus
- style
- tabIndex

Usage
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).
For this tag to work properly. the browser must be JavaScript-enabled.
To add other HTML <input> tag attributes and values to this tag, use the passThrough attribute. They are passed through to the select tag that ColdFusion generates for the cfselect control when creating a form. The supported HTML attributes are: CLASS, ID, MAXLENGTH, MESSAGE, ONBLUR, ONCHANGE, ONCLICK, ONDBLCLICK, ONFOCUS, SIZE, STYLE, and TABINDEX.

If you put a value in quotation marks, you must escape them; for example:

    passThrough = "readonly = " "yes " " "

For more information, see the cfform tag entry.
This tag requires an end tag.

Example

    <!--- This example shows the use of cftree, cfselect and cfgrid in a cfform.
    The query takes a list of employees, and uses cftree and cfselect to
    display results of query. cfgrid is used to show an alternate means
    of displaying the data --->
    <!--- set a default for the employeeNames variable --->
    <cfparam name = "employeeNames" default = "">
    <!--- if an employee name has been passed from the form, set employeeNames
    variable to this value --->
    <cfif IsDefined("form.employeeNames") is not "False">
       <cfset employeeNames = form.employeeNames>
    </cfif>

    <!--- query the datasource to find the employee information--->
    <cfquery name = "GetEmployees" dataSource = "cfsnippets">
       SELECT Emp_ID, FirstName, LastName, EMail, Phone, Department
       FROM   Employees
       WHERE 0=0
          <cfif employeeNames is not "">
             AND LastName = '#employeeNames#'
          </cfif>
    </cfquery>

    <h3>cfselect Example</h3>
    <!--- Use cfform when using other cfinput tools --->
    <cfform action = "cfselect.cfm">

    <!--- Use cfselect to present the contents of the query by column --->
    <h3>cfselect Presentation of Data</h3>
    <h4>Click on an employee's last name and hit "see information for this
    employee"
       to see expanded information.</h4>
    <cfselect name = "EmployeeNames"
       message = "Select an Employee Name"
    size = "#getEmployees.recordcount#"
    query = "GetEmployees" value = "LastName"
    required = "No">
    <option value = "">Select All
    </cfselect>

    <input type="Submit"
       name="" value="see information for this employee">
    <!--- showing the use of cftree ------------------------------------------>
    <!--- use cftree for an expanded presentation of the data Loop through the
          query to create each branch of the CFTREE ----------------------------->
    <h3>cftree Presentation of Data</h3>
    <h4>Click on the folders to "drill down" and reveal information.</h4> <p>
       <cftree name="SeeEmployees"
          height="150" width="240" font="Arial Narrow" bold="No"
          italic="No" border="Yes" hscroll="Yes" vscroll="Yes"
          required="No" completepath="No" appendkey="Yes" highlighthref="Yes">
       <cfloop query="GetEmployees">
          <cftreeitem value="#Emp_ID#" parent="SeeEmployees" expand="No">
          <cftreeitem value="#LastName#" display="Name" parent="#Emp_ID#"
             queryasroot="No" expand="No">
          <cftreeitem value="#LastName#, #FirstName#" parent="#LastName#"
             expand="No" queryasroot="No">
          <cftreeitem value="#Department#" display="Department" parent="#Emp_ID#"
             queryasroot="No" expand="No">
          <cftreeitem value="#Department#" parent="#Department#"
             expand="No" queryasroot="No">
          <cftreeitem value="#Phone#" display="Phone" parent="#Emp_ID#"
             queryasroot="No" expand="No">
          <cftreeitem value="#Phone#" parent="#Phone#"
             expand="No" queryasroot="No">
          <cftreeitem value="#Email#" display="Email" parent="#Emp_ID#"
             queryasroot="No" expand="No">
          <cftreeitem value="#Email#" parent="#Email#"
             expand="No" queryasroot="No">
       </cfloop>
    </cftree>
    <!----- You can also use CFGRID for a more comprehensive, quicker view at
       the data ---------------------------------------------------------------->
    <h3>CFGRID Presentation of Data</h3>
    <cfgrid name="SampleGrid"
       width="600" query="GetEmployees" insert="No" delete="No"
       sort="No" font="Verdana" bold="No" italic="No" appendkey="No"
       highlighthref="No" griddataalign="LEFT" gridlines="Yes"
       rowheaders="No" rowheaderalign="LEFT" rowheaderitalic="No"
       rowheaderbold="No" colheaders="Yes" colheaderalign="CENTER"
       colheaderitalic="No" colheaderbold="No" bgcolor="Teal"
       selectmode="BROWSE" picturebar="No">
       <cfgridcolumn name="LastName"
          header="Last Name" headeralign="LEFT" dataalign="LEFT"
          bold="No" italic="No" select="Yes" display="Yes" headerbold="No"
          headeritalic="No">
       <cfgridcolumn name="FirstName"
          header="First Name" headeralign="LEFT" dataalign="LEFT"
          fontsize="2" bold="No" italic="No" select="No" display="Yes"
          headerbold="No" headeritalic="No">
       <cfgridcolumn name="Email"
          header="Email" headeralign="LEFT" dataalign="LEFT" bold="No"
          italic="No" select="No" display="Yes" headerbold="No"
          headeritalic="No">
       <cfgridcolumn name="Phone"
          header="Phone" headeralign="LEFT" dataalign="LEFT" bold="No"
          italic="Yes" select="No" display="Yes" headerbold="No" headeritalic="No">
       <cfgridcolumn name="Department"
          header="Department" headeralign="LEFT" dataalign="LEFT" bold="Yes"
          italic="No" select="No" display="Yes" headerbold="No" headeritalic="No">
       <cfgridcolumn name="Emp_ID" header="ID" headeralign="LEFT" dataalign="LEFT"
          width="40" bold="No" italic="No" select="No" display="Yes" headerbold="No"
          headeritalic="No">
    </cfgrid>
    </cfform>

NAME |
| Required
Name of the select form element

SIZE |
| Optional
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

Default value: "No"

- Yes: a list element must be selected when 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.

- No

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

ONERROR |
| Optional
Custom JavaScript function to execute if validation fails

MULTIPLE |
| Optional

Default value: "No"

- Yes: allow selecting multiple elements in drop-down list
- No

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

SELECTED |
| Optional
A list of option values to preselect in the selection list. This attribute applies only if list items are generated from a query. The cfform preservedata attribute value can override this value.

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

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

PASSTHROUGH |
| Optional

Passes one or more arbitrary attribute-value pairs to the HTML code that is generated for the tag. You can use either of the following formats to include the quotation marks around the attribute value:

passthrough="ID=""myID"""

passthrough='ID="myID"'

The second format, which surrounds all the attribute-value pairs to be passed through in single quotation marks is clearer, particularly when you pass multiple HTML attributes.