- CFML Reference User Guide
- ColdFusion functions
- ColdFusion functions by category
- Functions a-b
- Abs
- ACos
- AddSOAPRequestHeader
- AddSOAPResponseHeader
- AjaxLink
- AjaxOnLoad
- ApplicationStop
- ArrayAppend
- ArrayAvg
- ArrayClear
- ArrayContains
- ArrayContainsNoCase
- ArrayDelete
- ArrayDeleteAt
- ArrayDeleteNoCase
- ArrayEach
- ArrayFilter
- ArrayFind
- ArrayFindAll
- ArrayFindAllNoCase
- ArrayFindNoCase
- ArrayInsertAt
- ArrayIsDefined
- ArrayIsEmpty
- ArrayLen
- ArrayMap
- ArrayMax
- ArrayMin
- ArrayNew
- ArrayPrepend
- ArrayReduce
- ArrayResize
- ArraySet
- ArraySetMetadata
- ArraySlice
- ArraySort
- ArraySum
- ArraySwap
- ArrayToList
- Asc
- ASin
- Atn
- AuthenticatedContext
- AuthenticatedUser
- BinaryDecode
- BinaryEncode
- BitAnd
- BitMaskClear
- BitMaskRead
- BitMaskSet
- BitNot
- BitOr
- BitSHLN
- BitSHRN
- BitXor
- BooleanFormat
- Abs
- Functions-c-d
- CacheGet
- CacheGetAllIds
- CacheGetMetadata
- CacheGetProperties
- CacheGetSession
- CacheIdExists
- CachePut
- CacheRegionExists
- CacheRegionNew
- CacheRegionRemove
- CacheRemove
- CacheRemoveAll
- CacheSetProperties
- CallStackDump
- CallStackGet
- CanDeSerialize
- Canonicalize
- CanSerialize
- Ceiling
- CharsetDecode
- CharsetEncode
- Chr
- CJustify
- Compare
- CompareNoCase
- Cos
- CreateDate
- CreateDateTime
- CreateObject
- CreateObject: .NET object
- CreateObject: COM object
- CreateObject: component object
- CreateObject: CORBA object
- CreateObject: Java or EJB object
- CreateObject: web service object
- CreateODBCDate
- CreateODBCDateTime
- CreateODBCTime
- CreateSignedJWT
- CreateEncryptedJWT
- CreateTime
- CreateTimeSpan
- CreateUUID
- CSRFGenerateToken
- CSRFVerifyToken
- DateAdd
- DateCompare
- DateConvert
- DateDiff
- DateFormat
- DatePart
- DateTimeFormat
- Day
- DayOfWeek
- DayOfWeekAsString
- DayOfYear
- DaysInMonth
- DaysInYear
- DE
- DecimalFormat
- DecodeForHTML
- DecodeFromURL
- DecrementValue
- Decrypt
- DecryptBinary
- DeleteClientVariable
- Deserialize
- DeserializeJSON
- DeserializeXML
- DirectoryCopy
- DirectoryCreate
- DirectoryDelete
- DirectoryExists
- DirectoryList
- DirectoryRename
- DollarFormat
- DotNetToCFType
- Duplicate
- Functions-e-g
- EncodeForCSS
- EncodeForDN
- EncodeForHTML
- EncodeForHTMLAttribute
- EncodeForJavaScript
- EncodeForLDAP
- EncodeForURL
- EncodeForXML
- EncodeForXMLAttribute
- EncodeForXpath
- Encrypt
- EncryptBinary
- EntityDelete
- EntityLoad
- EntityLoadByExample
- EntityLoadByPK
- EntityMerge
- EntityNew
- EntityReload
- EntitySave
- EntityToQuery
- Evaluate
- Exp
- ExpandPath
- FileClose
- FileCopy
- FileDelete
- FileExists
- FileGetMimeType
- FileIsEOF
- FileMove
- FileOpen
- FileRead
- FileReadBinary
- FileReadLine
- FileSeek
- FileSetAccessMode
- FileSetAttribute
- FileSetLastModified
- FileSkipBytes
- FileUpload
- FileUploadAll
- FileWrite
- FileWriteLine
- Find
- FindNoCase
- FindOneOf
- FirstDayOfMonth
- Fix
- Floor
- FormatBaseN
- GeneratePBKDFKey
- GenerateSecretKey
- GetApplicationMetadata
- GetAuthUser
- GetBaseTagData
- GetBaseTagList
- GetBaseTemplatePath
- GetClientVariablesList
- GetComponentMetaData
- GetContextRoot
- GetCPUUsage
- GetCurrentTemplatePath
- GetDirectoryFromPath
- GetEncoding
- GetException
- GetFileFromPath
- GetFileInfo
- GetFreeSpace
- GetFunctionCalledName
- GetFunctionList
- GetGatewayHelper
- GetHttpRequestData
- GetHttpTimeString
- GetK2ServerDocCount
- GetK2ServerDocCountLimit
- GetLocale
- GetLocaleDisplayName
- GetLocalHostIP
- GetMetaData
- GetMetricData
- GetPageContext
- GetPrinterInfo
- GetPrinterList
- GetProfileSections
- GetProfileString
- GetReadableImageFormats
- GetSafeHTML
- GetSAMLAuthRequest
- GetSAMLLogoutRequest
- GenerateSAMLSPMetadata
- GetSOAPRequest
- GetSOAPRequestHeader
- GetSOAPResponse
- GetSOAPResponseHeader
- GetSystemFreeMemory
- GetSystemTotalMemory
- GetTempDirectory
- GetTempFile
- GetTemplatePath
- GetTickCount
- GetTimeZoneInfo
- GetToken
- GetTotalSpace
- GetUserRoles
- GetVFSMetaData
- GetWriteableImageFormats
- Functions-h-im
- Hash
- HMac
- Hour
- HQLMethods
- HTMLCodeFormat
- HTMLEditFormat
- IIf
- ImageAddBorder
- ImageBlur
- ImageClearRect
- ImageCopy
- ImageCreateCaptcha
- ImageCrop
- ImageDrawArc
- ImageDrawBeveledRect
- ImageDrawCubicCurve
- ImageDrawLine
- ImageDrawLines
- ImageDrawOval
- ImageDrawPoint
- ImageDrawQuadraticCurve
- ImageDrawRect
- ImageDrawRoundRect
- ImageDrawText
- ImageFlip
- ImageGetBlob
- ImageGetBufferedImage
- ImageGetEXIFMetadata
- ImageGetEXIFTag
- ImageGetHeight
- ImageGetIPTCMetadata
- ImageGetIPTCTag
- ImageGetMetadata
- ImageGetWidth
- ImageGrayscale
- ImageInfo
- ImageMakeColorTransparent
- ImageMakeTranslucent
- ImageNegative
- ImageNew
- ImageOverlay
- ImagePaste
- ImageRead
- ImageReadBase64
- ImageResize
- ImageRotate
- ImageRotateDrawingAxis
- ImageScaleToFit
- ImageSetAntialiasing
- ImageSetBackgroundColor
- ImageSetDrawingColor
- ImageSetDrawingStroke
- ImageSetDrawingTransparency
- ImageSharpen
- ImageShear
- ImageShearDrawingAxis
- ImageTranslate
- ImageTranslateDrawingAxis
- ImageWrite
- ImageWriteBase64
- ImageXORDrawingMode
- Functions-in-k
- IncrementValue
- InputBaseN
- Insert
- Int
- InvalidateOauthAccesstoken
- Invoke
- InitSAMLAuthRequest
- InitSAMLLogoutRequest
- InvokeCFClientFunction
- IsArray
- IsAuthenticated
- IsAuthorized
- IsBinary
- IsBoolean
- IsClosure
- IsCustomFunction
- IsDate
- IsDateObject
- IsDDX
- IsDebugMode
- IsDefined
- IsImage
- IsImageFile
- IsInstanceOf
- IsIPv6
- IsJSON
- IsK2ServerABroker
- IsK2ServerDocCountExceeded
- IsK2ServerOnline
- IsLeapYear
- IsLocalHost
- IsNull
- IsNumeric
- IsNumericDate
- IsObject
- isOnline
- IsPDFArchive
- IsPDFFile
- IsPDFObject
- IsProtected
- IsQuery
- isSamlLogoutResponse
- isSafeHTML
- IsSimpleValue
- IsSOAPRequest
- IsSpreadsheetFile
- IsSpreadsheetObject
- IsStruct
- IsUserInAnyRole
- IsUserInRole
- IsUserLoggedIn
- IsValid
- IsValidOauthAccesstoken
- IsWDDX
- IsXML
- IsXmlAttribute
- IsXmlDoc
- IsXmlElem
- IsXmlNode
- IsXmlRoot
- JavaCast
- JSStringFormat
- Functions-l
- LCase
- Left
- Len
- ListAppend
- ListChangeDelims
- ListContains
- ListContainsNoCase
- ListDeleteAt
- ListEach
- ListFilter
- ListFind
- ListFindNoCase
- ListFirst
- ListGetAt
- ListInsertAt
- ListLast
- ListLen
- ListMap
- ListPrepend
- ListQualify
- ListReduce
- ListRemoveDuplicates
- ListRest
- ListSetAt
- ListSort
- ListToArray
- ListValueCount
- ListValueCountNoCase
- LJustify
- Location
- Log
- Log10
- LSCurrencyFormat
- LSDateFormat
- LSDateTimeFormat
- LSEuroCurrencyFormat
- LSIsCurrency
- LSIsDate
- LSIsNumeric
- LSNumberFormat
- LSParseCurrency
- LSParseDateTime
- LSParseEuroCurrency
- LSParseNumber
- LSTimeFormat
- LTrim
- Functions-m-r
- Max
- Mid
- Min
- Minute
- Month
- MonthAsString
- Now
- NumberFormat
- ObjectEquals
- ObjectLoad
- ObjectSave
- OnWSAuthenticate
- ORMClearSession
- ORMCloseAllSessions
- ORMCloseSession
- ORMEvictCollection
- ORMEvictEntity
- ORMEvictQueries
- ORMExecuteQuery
- ORMFlush
- ORMFlushall
- ORMGetSession
- ORMGetSessionFactory
- ORMIndex
- ORMIndexPurge
- ORMReload
- ORMSearch
- ORMSearchOffline
- ParagraphFormat
- ParameterExists
- ParseDateTime
- Pi
- PrecisionEvaluate
- ProcessSAMLResponse
- ProcessSAMLLogoutRequest
- Quarter
- PreserveSingleQuotes
- QueryAddColumn
- QueryAddRow
- QueryConvertForGrid
- QueryExecute
- QueryFilter
- QueryGetResult
- QueryGetRow
- QueryKeyExists
- QueryMap
- QueryNew
- QueryReduce
- QuerySetCell
- QuotedValueList
- QueryEach
- Rand
- Randomize
- RandRange
- ReEscape
- REFind
- REFindNoCase
- ReleaseComObject
- REMatch
- REMatchNoCase
- RemoveCachedQuery
- RemoveChars
- RepeatString
- Replace
- ReplaceList
- ReplaceNoCase
- REReplace
- REReplaceNoCase
- RestDeleteApplication
- RestSetResponse
- RestInitApplication
- Reverse
- Right
- RJustify
- Round
- RTrim
- Functions-s
- Second
- SendGatewayMessage
- SendSAMLLogoutResponse
- Serialize
- SerializeJSON
- SerializeXML
- SessionInvalidate
- SessionRotate
- SessionGetMetaData
- SessionInvalidate
- SessionRotate
- SetDay
- SetEncoding
- SetHour
- SetLocale
- SetMonth
- SetProfileString
- SetVariable
- SetYear
- Sgn
- Sin
- Sleep
- SpanExcluding
- SpanIncluding
- SpreadsheetAddAutoFilter
- SpreadsheetAddColumn
- SpreadsheetAddFreezePane
- SpreadsheetAddImage
- SpreadsheetAddInfo
- SpreadsheetAddPageBreaks
- SpreadsheetAddRow
- SpreadsheetAddRows
- SpreadsheetAddSplitPane
- SpreadsheetCreateSheet
- SpreadsheetDeleteColumn
- SpreadsheetDeleteColumns
- SpreadsheetDeleteRow
- SpreadsheetDeleteRows
- SpreadsheetFormatCell
- SpreadsheetFormatColumn
- SpreadsheetFormatCellRange
- SpreadsheetFormatColumn
- SpreadsheetFormatColumns
- SpreadsheetFormatRow
- SpreadsheetFormatRows
- SpreadsheetGetCellComment
- SpreadsheetGetCellFormula
- SpreadsheetGetCellValue
- SpreadsheetGetColumnCount
- SpreadsheetInfo
- SpreadsheetMergeCells
- SpreadsheetNew
- SpreadsheetRead
- SpreadsheetReadBinary
- SpreadsheetRemoveSheet
- SpreadsheetSetActiveSheet
- SpreadsheetSetActiveSheetNumber
- SpreadsheetSetCellComment
- SpreadsheetSetCellFormula
- SpreadsheetSetCellValue
- SpreadsheetSetColumnWidth
- SpreadsheetSetFooter
- SpreadsheetSetHeader
- SpreadsheetSetRowHeight
- SpreadsheetShiftColumns
- SpreadsheetShiftRows
- SpreadsheetWrite
- Sqr
- StripCR
- StructAppend
- StructClear
- StructCopy
- StructCount
- StructDelete
- StructEach
- StructFilter
- StructFind
- StructFindKey
- StructFindValue
- StructGet
- StructGetMetadata
- StructInsert
- StructIsEmpty
- StructKeyArray
- StructKeyExists
- StructKeyList
- StructMap
- StructNew
- StructReduce
- StructSetMetadata
- StructSort
- StructToSorted
- StructUpdate
- StoreSetMetadata
- StoreGetACL
- StoreGetMetadata
- StoreAddACL
- StoreSetACL
- Functions-t-z
- Tan
- ThreadJoin
- ThreadTerminate
- Throw
- TimeFormat
- ToBase64
- ToBinary
- ToScript
- ToString
- Trace
- Transactionandconcurrency
- TransactionCommit
- TransactionRollback
- TransactionSetSavePoint
- Trim
- UCase
- URLDecode
- URLEncodedFormat
- URLSessionFormat
- Val
- ValueList
- VerifyClient
- Week
- Wrap
- WriteDump
- WriteLog
- WriteOutput
- WSGetAllChannels
- WSGetSubscribers
- WSPublish
- WSSendMessage
- XmlChildPos
- XmlElemNew
- XmlFormat
- XmlGetNodeType
- XmlNew
- XmlParse
- XmlSearch
- XmlTransform
- XmlValidate
- Year
- YesNoFormat
- ColdFusion Tags
- ColdFusion tag summary
- ColdFusion tags by category
- Application framework tags
- Communications tags
- Database manipulation tags
- Data output tags
- Debugging tags
- Exception handling tags
- Extensibility tags
- File management tags
- Flow-control tags
- Forms tags
- Internet Protocol tags
- Page processing tags
- Security tags
- Variable manipulation tags
- Other tags
- Tags a-b
- Tags c
- Tags f
- cffeed
- cffile
- cffile action = "append"
- cffile action = "copy"
- cffile action = "delete"
- cffile action = "move"
- cffile action = "read"
- cffile action = "readBinary"
- cffile action = "rename"
- cffile action = "upload"
- cffile action = "uploadAll"
- cffile action = "write"
- cffileupload
- cffinally
- cfflush
- cfform
- cfformgroup
- cfformitem
- cfftp
- cfftp: Connection: file and directory operations
- cfftp: Opening and closing FTP server connections
- cfftp : Opening and closing secure FTP server connections
- cfftp action = "listDir"
- cffunction
- Tags g-h
- Tags i
- Tags j-l
- cfjava
- cflayout
- cflayoutarea
- cfldap
- cflocation
- cflock
- cflog
- cflogin
- cfloginuser
- cflogout
- cfloop
- cfloop : conditional loop
- cfloop : index loop
- cfloop : looping over a COM collection or structure
- cfloop : looping over a date or time range
- cfloop : looping over a list, a file, or an array
- cfloop : looping over a query
- Tags m-o
- cfmail
- cfmailparam
- cfmailpart
- cfmap
- cfmapitem
- cfmediaplayer
- cfmenu
- cfmenuitem
- cfmessagebox
- cfmodule
- cfNTauthenticate
- cfoauth
- cfobject
- cfobject: .NET object
- cfobject: COM object
- cfobject: component object
- cfobject: CORBA object
- cfobject: Java or EJB object
- cfobject: web service object
- cfobjectcache
- cfoutput
- Tags p-q
- Tags r-s
- Tags t
- Tags u-z
- CFML Reference
- Reserved words and variables
- Ajax JavaScript functions
- Ajax JavaScript functions
- Function summary Ajax
- ColdFusion.Ajax.submitForm
- ColdFusion.Autosuggest.getAutosuggestObject
- ColdFusion.Layout.enableSourceBind
- ColdFusion.MessageBox.getMessageBoxObject
- ColdFusion.ProgressBar.getProgressBarObject
- ColdFusion.MessageBox.isMessageBoxDefined
- JavaScriptFunctionsinColdFusion9Update1
- ColdFusion ActionScript functions
- ColdFusion mobile functions
- Application.cfc reference
- Script functions implemented as CFCs
- ColdFusion Flash Form style reference
- Styles valid for all controls
- Styles for cfform
- Styles for cfformgroup with horizontal or vertical type attributes
- Styles for box-style cfformgroup elements
- Styles for cfformgroup with accordion type attribute
- Styles for cfformgroup with tabnavigator type attribute
- Styles for cfformitem with hrule or vrule type attributes
- Styles for cfinput with radio, checkbox, button, image, or submit type attributes
- Styles for cftextarea tag and cfinput with text, password, or hidden type attributes
- Styles for cfselect with size attribute value of 1
- Styles for cfselect with size attribute value greater than 1
- Styles for cfcalendar tag and cfinput with dateField type attribute
- Styles for the cfgrid tag
- Styles for the cftree tag
- ColdFusion Flash Form Style Reference
- ColdFusion event gateway reference
- ColdFusion Event Gateway reference
- addEvent
- CFEvent
- CFEventclass
- Constructor
- Gateway development interfaces and classes
- getStatus
- setCFCPath
- setCFCMethod
- getOriginatorID
- getLogger
- getBuddyList
- getBuddyInfo
- IM gateway message sending commands
- IM Gateway GatewayHelper class methods
- onIncomingMessage
- onIMServerMessage
- onBuddyStatus
- onAddBuddyResponse
- onAddBuddyRequest
- IM Gateway CFC incoming message methods
- IM gateway methods and commands
- CFML CFEvent structure
- warn
- info
- setOriginatorID
- data command
- submit Multi command
- submit command
- setGatewayType
- setGatewayID
- setData
- setCFCListeners
- outgoingMessage
- getStatusTimeStamp
- numberOfMessagesReceived
- numberOfMessagesSent
- removeBuddy
- removeDeny
- removePermit
- setNickName
- setPermitMode
- setStatus
- SMS Gateway CFEvent structure and commands
- SMS Gateway incoming message CFEvent structure
- getStatusAsString
- getProtocolName
- getPermitMode
- getPermitList
- getNickName
- getName
- getDenyList
- getCustomAwayMessage
- getQueueSize
- getMaxQueueSize
- getHelper
- getGatewayType
- getGatewayServices
- getGatewayID_1
- getGatewayID
- getData
- getCFCTimeout
- setCFCTimeout
- getCFCPath
- getCFCMethod
- GatewayServices class
- Gateway interface
- GatewayHelper interface
- addPermit
- addDeny
- addBuddy
- error
- debug
- Logger class
- stop
- start
- CFML event gateway SendGatewayMessage data parameter
- restart
- fatal
- SMS gateway message sending commands
- ColdFusion C++ CFX Reference
- ColdFusion Java CFX reference
- WDDX JavaScript Objects
- Cloud services
- ColdFusion and GCP Storage
- ColdFusion and GCP Firestore
- ColdFusion and GCP PubSub
- ColdFusion and Amazon S3
- ColdFusion and DynamoDB
- ColdFusion and Amazon SQS
- ColdFusion and Amazon SNS
- ColdFusion and MongoDB
- ColdFusion and Azure Blob
- ColdFusion and Azure Service Bus
- Multi-cloud storage services
- Multi-cloud RDS databases
- ColdFusion and Azure Cosmos DB
Description
Constructs 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.
Category
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.
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 also
cfapplet, 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
History
ColdFusion 11:
- Removed the attribute passthrough.
ColdFusion 8:
- Added support for binding in HTML format forms, including the bind, bindAttribute, and bindOnLoad, and onBindError attributes.
- Added support for tool tips in HTML format forms, including the sourceForTooltip attribute.
ColdFusion MX 7:
- When populating a cfselect tag with a query when the database field has spaces instead of a value, the error processing of the cfform tag required field is not triggered as it was in ColdFusion MX 6.1.
- 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.
Attributes that are marked as Flash only are not handled by the skins provided with ColdFusion. They are, however, included in the generated XML.
Attribute |
Req/Opt;Format |
Default |
Description |
---|---|---|---|
name |
Required;All |
|
Name of the select form element. |
bind |
Optional; HTML |
|
A bind expression that dynamically sets an attribute of the control. For details, see Usage. |
bindAttribute |
Optional;HTML |
Populate the options |
Specifies the HTML tag attribute whose value is set by the bind attribute. You can only specify attributes in the browser's HTML DOM tree, not ColdFusion-specific attributes. |
bindOnLoad |
Optional;HTML |
no |
A Boolean value that specifies whether to execute the bind attribute expression when first loading the form. Ignored if there is no bind 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. |
editable |
Optional; Flash |
no |
Boolean value specifying whether you can edit the contents of 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. |
group |
Optional; HTML and XML |
|
Query column to use to group the items in the drop-down list into a two-level hierarchical list. |
height |
Optional; Flash |
|
The height of the control, in pixels. |
id |
Optional;HTML |
Value of name attribute |
The HTML ID of the control. |
label |
Optional;Flash and XML |
|
Label to put next to the control on a Flash or XML-format form. |
message |
Optional;All |
|
Message to display if required = "yes" and no selection is made. |
multiple |
Optional;All |
no |
|
onBindError |
Optional;HTML |
See Description |
The name of a JavaScript function to execute if evaluating a bind expression results in an error. The function must take two attributes: an HTTP status code and a message. (The status code is1 if the error is not an HTTP error.)If you omit this attribute, and specified a global error handler (by using the ColdFusion.setGlobalErrorHandler function), it displays the error message; otherwise a default error pop-up appears. |
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. |
onError |
Optional;HTML and XML |
|
Custom JavaScript function to execute if validation fails. |
onKeyDown |
Optional;All |
|
JavaScript (HTML/XML) or ActionScript (Flash) to run when the user presses a keyboard key in the control. |
onKeyUp |
Optional;All |
|
JavaScript (HTML/XML) or ActionScript (Flash) to run when the user releases a keyboard key in the control. |
onMouseDown |
Optional;All |
|
JavaScript (HTML/XML) or ActionScript (Flash) to run when the user releases a mouse button in the control. |
onMouseUp |
Optional;All |
|
JavaScript (HTML/XML) or ActionScript (Flash) to run when the user presses a mouse button in the control. |
query |
Optional;All |
|
Name of query to populate drop-down list. |
queryPosition |
Optional;All |
above |
If you populate the options list with a query and use HTML option child tags to specify additional entries, this attribute determines the location of the items from the query relative to the items from the option tags:
|
required |
Optional;All |
no |
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=" " (notice the space character between the quotation marks). This workaround applies only for Flash forms and not for HTML forms or XML forms.
|
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 tag preserveData attribute can override this value. |
size |
Optional;All |
1 |
Number of entries to display at one time. The default value displays a drop-down list. Any other value displays a list box with size number of entries visible at one time. |
sourceForTooltip |
Optional; HTML |
|
The URL of a page to display as a tool tip. The page can include CFML and HTML markup to control the tip contents and format, and the tip can include images. |
style |
Optional;All |
|
In HTML or XML format forms, ColdFusion passes the style attribute to the browser or XML. |
tooltip |
Optional; Flash, HTML |
|
Text to display when the mouse pointer hovers over the control. The text can include HTML markup. |
value |
Optional;All |
|
Query column to use for the value of each list element. Used with the query attribute. |
visible |
Optional; Flash |
yes |
Boolean value that specifies whether to show the control. The display reserves empty space for an invisible control. |
width |
Optional; Flash |
|
The width of the control, in pixels. |
Usage
For 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:
- A two-dimensional array, where the first element in each array row is the option value and the second element in the row is the text to display in the option list.
- If the bind specifies a CFC function, a query, or, if the bind specifies a URL, a JSON representation of a query. The query must include columns whose names are the values of the cfselect tag value and display attributes. Although you can return additional columns, you cannot use them in your client-side code. When you call a CFC function, you do not have to convert the query to JSON format yourself; ColdFusion automatically does the conversion.
To use this format, specify a value attribute. If you omit the display attribute, you must have only a single column in the query that contains the values; the values are also used as the displayed text.
For detailed information on binding, see Binding data to form fields in the Developing ColdFusion Applications. For more information, see the cfform tag entry.
Example
Example 1: Without data bindingThe 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 bindingThe 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 BindFcns 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>