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

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> 

View comments in LiveDocs