ColdFusion 9.0 Resources |
cfselectDescriptionConstructs a drop-down list box form control. Used in a cfform tag. You can populate the list from a query, or by using the HTML option tag. Syntax<cfselect name="name" bind="bind expression" bindAttribute="attribute name" bindOnLoad="yes|no" display="text" editable="yes|no" enabled="yes|no" group="query column name" height="number of pixels" id="HTML id" label="label" message="text" multiple="yes|no" onBindError="JavaScript function name" onChange="JavaScript or ActionScript" onClick="JavaScript function name" onError="JavaScript" onKeyDown="JavaScript or ActionScript" onKeyUp="JavaScript or ActionScript" onMouseDown="JavaScript or ActionScript" onMouseUp="JavaScript or ActionScript" query="query name" queryPosition="above|below" required="yes|no" selected="value or list" size="integer" sourceForTooltip="URL" style="style specification" tooltip="text" value="text" visible="yes|no" width="number of pixels"> zero or more HTML option tags </cfselect> Some attributes apply to only specific display formats. For details see the Attributes table. Note: You can specify this tag’s attributes
in an attributeCollection attribute whose value
is a structure. Specify the structure name in the attributeCollection attribute
and use the tag’s attribute names as structure keys.
See alsocfapplet, cfcalendar, cfform, cfformgroup, cfformitem, cfgrid, cfinput, cfslider, cftextarea, cftree; Introduction to Retrieving and Formatting Data and Using Ajax User Interface Components and Features in the Developing ColdFusion Applications HistoryColdFusion 8:
ColdFusion MX 7:
AttributesThe 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. They are, however,
included in the generated XML.
UsageFor this tag to work properly. the browser must have JavaScript enabled. 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 tag 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 yes and the form posts back to the same page, and if the control is populated by a query, the posted selections 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 tags. The group option generates a query by 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. The bind attribute lets you set cfselect attributes dynamically. Often, it is used to dynamically create the options list based on values that the user enters in the form. For example, you can use the bind attribute to create a Cities option list based on the user’s selection from a States cfselect control. When you use a bind attribute to populate the selection list, the function or URL that returns the selection values must return one of the following:
For detailed information on binding, see Binding data to form fields in the Developing ColdFusion Applications. For more information, see the cfform tag entry. ExampleExample 1: Without data binding 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 e-mail 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. ---> <h3>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> Example 2: With data binding The following example uses binding to fill in the options list of the Cities control only after the user selects a state. (In this example, only two states, California and New Jersey, have city entries.) The CFML page is the simplest part of the example. It consists of the following lines: <html> <head> </head> <body> <cfform name="mycfform"> <!--- The States selector. The bindonload attribute is required to fill the selector. ---> <cfselect name="state" bind="cfc:bindFcns.getstates()" bindonload="true"> <option name="0">--state--</option> </cfselect> <cfselect name="city" bind="cfc:bindFcns.getcities({state})"> <option name="0">--city--</option> </cfselect> </cfform> </body> </html> The BinFcns CFC has three functions: getstates, to get the states; getcities, to get the cities; and an internal getXmlData function that parses an XML file to get the state and city information. The following examples shows the CFC: <cfcomponent> <cffunction name="getXmlData" output="true"> <cfset var xmlData = ""> <cffile action="read" file="#expandpath('.')#\states.xml" variable="xmlData"> <cfset xmlData = XmlParse(xmlData)> <cfreturn xmlData> </cffunction> <cffunction name="getstates" access="remote"> <cfset state = arraynew(2)> <cfset xmlData = getXmlData()> <cfset numStates = 0> <cfset state[1][1] = "0"> <cfset state[1][2] = "--state--"> <cfset numStates = ArrayLen(xmlData.states.XmlChildren)> <cfloop from="1" to="#numStates#" index="j"> <cfset state[j+1][1] = ltrim(xmlData.states.state[j].XmlAttributes.abr)> <cfset state[j+1][2] = ltrim(xmlData.states.state[j].name.xmlText)> </cfloop> <cfreturn state> </cffunction> <cffunction name="getcities" access="remote"> <cfargument name="state" required="yes"> <cfset var city = arraynew(2)> <cfset var xmlData = getXmlData()> <cfset var numStates = 0> <cfset var numCities = 0> <cflog text="In getcities"> <cfset city[1][1] = "0"> <cfset city[1][2] = "--city--"> <cftry> <cfset numStates = ArrayLen(xmlData.states.XmlChildren)> <cfloop from="1" to="#numStates#" index="j"> <cfif xmlData.states.state[j].XmlAttributes.abr eq state> <cfset numCities = ArrayLen(xmlData.states.state[j].cities.XmlChildren)> <cfloop from="1" to="#numCities#" index="k"> <cfset city[k+1][1] = ltrim(xmlData.states.state[j].cities.city[k].XmlAttributes.name)> <cfset city[k+1][2] = ltrim(xmlData.states.state[j].cities.city[k].XmlAttributes.name)> </cfloop> <cfbreak> </cfif> </cfloop> <cfcatch type="any"> <!--- Do nothing. ---> </cfcatch> </cftry> <cfreturn city> </cffunction> </cfcomponent> The states.xml file has the following code. To keep the code short, only two states have cities, and only four states are listed. <states> <state abr="NJ"> <name>New Jersey</name> <cities> <city name="Edison" /> <city name="Rahway" /> <city name="Atlantic City" /> <city name="Hoboken" /> <city name="Jersey City" /> <city name="Newark" /> <city name="Trenton" /> <city name="Union City" /> </cities> </state> <state abr="CA"> <name>California</name> <cities> <city name="Anaheim" /> <city name="Beverly Hills" /> <city name="Elk Grove" /> <city name="Fairfield" /> <city name="Fremont" /> <city name="Indian Wells" /> <city name="Long Beach" /> </cities> </state> <state abr="ME"> <name>Maine</name> </state> <state abr="MA"> <name>Massachusetts</name> </state> </states> |