cfselect

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.

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

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

Attribute	Req/Opt	Default	Description
name	Required		Name of the select form element
size	Optional	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	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	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	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.

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

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.

<!--- 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>

cfselect

View comments on LiveDocs