cfselect

Description

Used inside cfform, cfselect lets you construct a drop-down list box form control. You can populate the drop-down list box from a query, or using the option tag. Use option elements to populate lists. The syntax for the option tag is the same as for its HTML counterpart.

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>

Attributes

Attribute

Description

name
Required. Name of the form you are creating.

size
Optional. Number of entries in the drop-down list.

required
Optional. Yes or No. If Yes, a list element must be selected when the form is submitted, and the size of the drop-down list must be at least two. Default is No.

message
Optional. Message that displays if required = "Yes" and no selection is made.

onError
Optional. The name of a valid JavaScript function to execute in the event of a failed validation.

multiple
Optional. Yes or No. Yes permits selection of multiple elements in the drop-down list box. The default is No.

query
Optional. Name of the query to be used to populate the drop-down list box.

selected
Optional. A value matching at least one entry in value to preselect the entry in the drop-down list box.

value
Optional. The query column value for the list element. Used with the query attribute.

display
Optional. The query column displayed. Defaults to the value of value. Used with the query attribute.

passThrough
Optional. HTML attributes that are not explicitly supported by cfselect. If you specify an attribute and its value, the attribute and its value are passed to the HTML code that is generated for the cfselect tag.

Attribute	Description
name	Required. Name of the form you are creating.
size	Optional. Number of entries in the drop-down list.
required	Optional. Yes or No. If Yes, a list element must be selected when the form is submitted, and the size of the drop-down list must be at least two. Default is No.
message	Optional. Message that displays if `required` = "Yes" and no selection is made.
onError	Optional. The name of a valid JavaScript function to execute in the event of a failed validation.
multiple	Optional. Yes or No. Yes permits selection of multiple elements in the drop-down list box. The default is No.
query	Optional. Name of the query to be used to populate the drop-down list box.
selected	Optional. A value matching at least one entry in `value` to preselect the entry in the drop-down list box.
value	Optional. The query column value for the list element. Used with the `query` attribute.
display	Optional. The query column displayed. Defaults to the value of `value`. Used with the `query` attribute.
passThrough	Optional. HTML attributes that are not explicitly supported by `cfselect`. If you specify an attribute and its value, the attribute and its value are passed to the HTML code that is generated for the `cfselect` tag.

Usage

Note

The cfselect tag requires the client to download a Java applet. This takes time, so using cfselect may be slightly slower than using a select element within an HTML form tag. For cfselect to work properly, browsers must be Java-enabled.

You can add standard and dynamic HTML form tag attributes and their values to the cfselect tag with the passThrough attribute. These attributes and values are passed directly through ColdFusion to the browser in creating a form.

If you specify a value in quotation marks, you must escape the quotation marks by doubling them; for example,

passThrough = "readonly = " "YES " " "

cfselect supports the JavaScript onClick event in the same manner as the HTML input tag:

<cfselect name = "dept"

  message = "You must select a department name"
  query = "get_dept_list"
  value = "dept_name"
  onClick = "JavaScript_function">

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 the results of the query. In addition, cfgrid is
used to show an alternate means of displaying the same 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 lastname 
     <cfif #employeeNames# is not ""> = '#employeeNames#'</cfif>
</cfquery>

<html>
<head>
<title>
cfselect Example
</title>
</head>

<body>

<H3>cfselect Example</H3>

<!--- Use cfform when using other cfinput tools --->
<cfform action = "cfselect.cfm" method = "POST" enableCAB = "Yes">

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