`select()`

Description

Builds and returns a string containing a select form control based on the supplied objectName and property. Note: Pass any additional arguments like class, rel, and id, and the generated tag will also include those values as HTML attributes.

Function Syntax

select(objectName, property [, association, position, options, includeBlank, valueField, textField, label, labelPlacement, prepend, append, prependToLabel, appendToLabel, errorElement, errorClass ])

Parameters

Parameter	Type	Required	Default	Description
`objectName`	`any`	Yes		The variable name of the object to build the form control for.
`property`	`string`	Yes		The name of the property to use in the form control.
`association`	`string`	No		The name of the association that the property is located on. Used for building nested forms that work with nested properties. If you are building a form with deep nesting, simply pass in a list to the nested object, and Wheels will figure it out.
`position`	`string`	No		The position used when referencing a `hasMany` relationship in the `association` argument. Used for building nested forms that work with nested properties. If you are building a form with deep nestings, simply pass in a list of positions, and Wheels will figure it out.
`options`	`any`	Yes		A collection to populate the select form control with. Can be a query recordset or an array of objects.
`includeBlank`	`any`	No	`false`	Whether to include a blank option in the select form control. Pass `true` to include a blank line or a string that should represent what display text should appear for the empty value (for example, "- Select One -").
`valueField`	`string`	No		The column or property to use for the value of each list element. Used only when a query or array of objects has been supplied in the `options` argument.
`textField`	`string`	No		The column or property to use for the value of each list element that the end user will see. Used only when a query or array of objects has been supplied in the `options` argument.
`label`	`string`	No	`useDefaultLabel`	The label text to use in the form control.
`labelPlacement`	`string`	No	`around`	Whether to place the label `before`, `after`, or wrapped `around` the form control.
`prepend`	`string`	No		String to prepend to the form control. Useful to wrap the form control with HTML tags.
`append`	`string`	No		String to append to the form control. Useful to wrap the form control with HTML tags.
`prependToLabel`	`string`	No		String to prepend to the form control's `label`. Useful to wrap the form control with HTML tags.
`appendToLabel`	`string`	No		String to append to the form control's `label`. Useful to wrap the form control with HTML tags.
`errorElement`	`string`	No	`span`	HTML tag to wrap the form control with when the object contains errors.
`errorClass`	`string`	No	`fieldWithErrors`	The class name of the HTML tag that wraps the form control when there are errors.

Examples

<!--- Example 1: Basic `select` field with `label` and required `objectName` and `property` arguments --->
<!--- - Controller code --->
<cfset authors = model("author").findAll()>

<!--- - View code --->
<cfoutput>
    <p>#select(objectName="book", property="authorId", options=authors)#</p>
</cfoutput>

<!--- Example 2: Shows `select` fields for selecting order statuses for all shipments provided by the `orders` association and nested properties --->
<!--- - Controller code --->
<cfset shipment = model("shipment").findByKey(key=params.key, where="shipments.statusId=#application.NEW_STATUS_ID#", include="order")>
<cfset statuses = model("status").findAll(order="name")>

<!--- - View code --->
<cfoutput>
    <cfloop from="1" to="#ArrayLen(shipments.orders)#" index="i">
        #select(label="Order ##shipments.orders[i].orderNum#", objectName="shipment", association="orders", position=i, property="statusId", options=statuses)#
    </cfloop>
</cfoutput>