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

 
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
 

Number of entries in drop-down list.

REQUIRED  
  Optional
 
Default value: "No"
  • Yes: a list element must be selected when form is submitted. Minimum size of select box is 2.
  • 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
 

HTML attribute(s) that are not explicitly supported by cfselect. If you specify an attribute and its value, they are passed to HTML code that is generated for cfselect tag.

For example:

"style=""font-family:courier"""