View comments | RSS feed

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"
enabled = "yes" or "no"
visible = "yes" or "no"
tooltip = "tip text"
height = "number of pixels" Flash only
width = "number of pixels" Flash only
editable="yes" or "no" 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:

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.

Attribute Req/Opt; Format Default Description

name

Required;

All

 

Name of the select form element.

label

Optional;

Flash and XML

 

Label to put next to the control on a Flash or XML-format form.

style

Optional;

All

 

In HTML or XML format forms, ColdFusion passes the style attribute to the browser or XML.

In Flash format, must be a style specification in CSS format, with the same syntax and contents as used in Macromedia Flex for the corresponding Flash element.

size

Optional;

All

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;

All

No
  • Yes: a list element must be selected when the 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. You can work around this issue: format forms by having an initial option tag with value=" " (note the space character between the quotation marks).

  • No

message

Optional;

All

 

Message to display if required = "Yes" and no selection is made.

onError

Optional;

HTML and XML

 

Custom JavaScript function to execute if validation fails.

multiple

Optional;

All

No
  • Yes: allows selecting multiple elements in drop-down list.
  • No

query

Optional;

All

 

Name of query to populate drop-down list.

value

Optional;

All

 

Query column to use for the value of each list element. Used with the query attribute.

display

Optional;

All

Value of value attribute

Query column to use for the display label of each list element. Used with the query attribute.

group

Optional; HTML and XML

 

Query column to use to group the items in the drop-down list into a two-level hierarchical list.

queryPosition

Optional;

All

above

If you populate the options list with a query and use HTML option child tags to specify additional entries, determines the location of the items from the query relative to the items from the option tags:

  • above: puts the query items above the options items.
  • below: puts the query items below the options items.

selected

Optional;

All

 

One or more option values to preselect in the selection list. To specify multiple values, use a comma-delimited list. This attribute applies only if selection list items are generated from a query. The cfform preservedata attribute value can override this value.

onKeyUp

Optional;

All

 

JavaScript (HTML/XML) or ActionScript (Flash) to run when the user releases a keyboard key in the control.

onKeyDown

Optional;

All

 

JavaScript (HTML/XML) or ActionScript (Flash) ActionScript to run when the user presses a keyboard key in the control.

onMouseUp

Optional;

All

 

JavaScript (HTML/XML) or ActionScript (Flash) to run when the user presses a mouse button in the control.

onMouseDown

Optional;

All

 

JavaScript (HTML/XML) or ActionScript (Flash) to run when the user releases a mouse button in the control.

onChange

Optional;

All

 

JavaScript (HTML/XML) or ActionScript (Flash) to run when the control changes due to user action.

onClick

Optional; HTML and XML

 

JavaScript to run when the user clicks the control.

enabled

Optional; Flash

Yes

Boolean value specifying whether the control is enabled. A disabled control appears in light gray. The inverse of the disabled attribute.

visible

Optional; Flash

Yes

Boolean value specifying whether to show the control. Space that would be occupied by an invisible control is blank.

tooltip

Optional; Flash

 

Text to display when the mouse pointer hovers over the control.

height

Optional; Flash

 

The height of the control, in pixels.

width

Optional; Flash

 

The width of the control, in pixels.

editable

Optional; Flash

No

Boolean value specifying whether you can edit the contents of the control.

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>

ColdFusion 9 | ColdFusion 8 | ColdFusion MX 7 | ColdFusion MX 6.1 | ColdFusion MX | Forums | Developer Center | KnowledgeBase | Bug Reporting

Version 7

Comments


gorberto said on Feb 17, 2005 at 1:26 AM :
To pass items between cfselect , cftree, cfgrid you have to use a bit of Actionscript. Here is what I did: I have large a tree (three nodes depth), the user selects the node, next using Actionscript I pass this selection to another select by putting some Actionscript code in the onChange event handler

onChange="_root.select_name.addItem(tree_name.selectedNode.getProperty('data').display,tree_name.selectedNode.getProperty('data').value);"

As cfselect becomes listBox component of Flash, we can manipulate it using various predefined methods like addittem(dispy, value)

I hope this helps!
jrunrandy said on Mar 14, 2005 at 2:06 PM :
FYI, Mike Kaminsky posted an interesting comment on resolving cfselect problems on the following page:

http://livedocs.macromedia.com/coldfusion/5.0/CFML_Reference/Tags91.htm
bgadget said on Apr 7, 2005 at 1:35 PM :
The sample on the CFSelect page for the <option> tags of:
<option value = "thevalue">Hello
If you have to use value="thevalue" NOT value = "thevalue" or the value clause is ignored.
seancoyne said on May 25, 2005 at 12:38 PM :
the attribute editable="yes" is missing from the documentation. This will allow a select box that also accepts user input.
sloan2b said on Jun 23, 2005 at 9:22 AM :
Documentation should state that the size has to be greater than 1 for the multi select to work in flash. It would be a nice feature to allow multiple selects in a drop down list.
ipaul said on Jul 1, 2005 at 8:21 AM :
The required tag value=" " as shown below only appears to function correctly with FLASH, but does not work with HTML.

Referring to this:
You can work around this issue: format forms by having an initial option tag with value=" " (note the space character between the quotation marks)."
apaleja said on Jul 20, 2005 at 12:11 PM :
It is possible use required = 'yes' in a cfselect statement with a little javascripting code to accompany it.

By default, a cfselect and select input type will have whatever is displayed selected. However, using the code below you can 'unselect' the default selection and then the required='yes' cf validation will kick in...

<script language="JavaScript"><!--
document.formName.selectName.selectedIndex=-1;
//--></script>

Cheers!
AjasHadi said on Mar 5, 2008 at 7:52 AM :
Ok, I have tested this with many different scenarios and here are the results.

1. The validation works only if you have size attribute of cfselect set to a value greater than 1.

Here is my code that works

<cfselect name="sec_question" required="yes" message="You must select a security question to reset your password." size="2">
<option value="1">What is your mother's maiden name?</option>
<option value="2">In what city were you born?</option>
<option value="3">What is the title of your favorite book?</option>
<option value="4">What is your favorite pet's name?</option>

</cfselect>

2. Here are some observations

a. I didnt require selected="" attribute inside cfselect

b. I didnt require <option value=" ">Please select a value </option> i.e. with a space or without space(either way, I tried and it didnt work)

So try this and I am sure you wont be dissapointed. It took me a while to figure it out and I tried different options before I succeeded.
halL said on Mar 6, 2008 at 10:38 AM :
AjasHadi is correct, that if you set a size>=2 the required validation works and does not need any other tricks.
However, this does not solve the issue for those who want size=1, which is common.
In that case, the Note in the required attribute description saying you can use value=" " is correct for Flash format forms only.
This technique does not work for HTML or XML forms, as ipaul noted.
I tried the technique mentioned by apaleja does not seem to work for me, but I may be missing something (and I did change formName and selectName the cfform and cfselect name values.
coolbtk said on Dec 4, 2008 at 12:41 AM :
not sure if this page is still being looked at by adobe admins, but i just
noticed that the descriptions for onMouseDown and onMouseUp are
reversed. not a big deal, because they are pretty self-explanatory, but
better to have the correct descriptions...
No screen name said on Dec 16, 2008 at 12:28 PM :
Try putting the javascript after the form field in question. That seemed to work for me, where it didn't work before the form field.

 

RSS feed | Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/coldfusion/7/htmldocs/00000331.htm