CFML Reference

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

Attributes

Attribute	Req/Opt	Default	Description
name	Required		Name of the select form element
size	Optional		Number of entries in drop-down list.
required	Optional	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	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		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"""

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> 

Copyright © 2002, Macromedia Inc. All rights reserved.

Comments