Form Groups

Generate groups of check boxes and radio buttons by passing a query, array, or struct as an argument called options.

Author

Project Home

http://github.com/clearcrystalmedia/Form-Groups

Description

This plugin provides you with 3 additional form helpers: checkBoxTagGroup(), radioButtonGroup(), and radioButtonTagGroup(). With these new helpers, you can generate groups of check boxes and radio buttons by passing a query, array, or struct as an argument called options. This behavior is similar to Wheels select() and selectTag() helpers.

Bonus Bug Fix

This plugin also fixes a bug involving the checkBoxTag() helper in Wheels 1.0. The bug is recorded in issue 342 in the Wheels bug tracker. Basically the bug can cause multiple check boxes on the same page to share the same HTML id.

Usage/Examples

Optional Fieldset and Legend

All 3 group helpers have an argument called isFieldset that defaults to true. When set to true, you should provide the matching legend argument as well. Then the helpers will wrap your form group with an HTML fieldset and legend.

So this example…

#radioButtonGroup(legend="Eye Color", objectName="customer", property="eyeColor", options=eyeColors, textField="color", valueField="id")#

…would produce markup similar to this:

<fieldset>
    <legend>Eye Color</legend>
    <label for="customer-eyeColor-1">Blue <input type="radio" id="customer-eyeColor-1" name="customer[eyeColor]" value="1" /></label>
    <label for="customer-eyeColor-4">Brown <input type="radio" id="customer-eyeColor-4" name="customer[eyeColor]" value="4" /></label>
    <label for="customer-eyeColor-3">Green <input type="radio" id="customer-eyeColor-3" name="customer[eyeColor]" value="3" /></label>
    <label for="customer-eyeColor-2">Hazel <input type="radio" id="customer-eyeColor-2" name="customer[eyeColor]" value="2" /></label>
</fieldset>

Like with the Wheels select() form helper, passing textField and valueField specifies which fields in options to use as the display text and radio button value, respectively.

Here is documentation for the fieldset and legend arguments that are common to all 3 helpers:

Argument	Type	Required	Default	Description
`isFieldset`	boolean	`false`	`true`	Whether or not to wrap the group in HTML `fieldset` tags.
`legend`	string	`false`	`[empty string]`	HTML legend to show. Recommended if `isFieldset` is set to `true`.
`fieldsetId`	string	`false`	`[empty string]`	`id` attribute to add to `fieldset` tag.
`fieldsetClass`	string	`false`	`[empty string]`	`class` attribute to add to `fieldset` tag.
`legendId`	string	`false`	`[empty string]`	`id` attribute to add to `legend` tag.
`legendClass`	string	`false`	`[empty string]`	`class` attribute to add to `legend` tag.

Radio Button Groups

You can show a group of radio buttons either bound to a model object or as standalone tags with names and values.

Bind to Objects with `radioButtonGroup()`

Like other form helpers standard to Wheels, radio button groups can be bound directly to a model by using radioButtonGroup(). You pass in an objectName, property, and a query, array, or object for options.

Here is another example, this time passing a struct for options:

<cfset colors = {"1"="Blue", "4"="Brown", "3"="Green", "2"="Hazel"}>
#radioButtonGroup(legend="Eye Color", objectName="customer", property="eyeColor", options=colors)#

Note that you do not need to provide arguments for textField and valueField when the value of options is a struct. The helpers will use the structs keys as values and the associated struct values as display text.

Just Show the Tags with `radioButtonTagGroup()`

This is similar to the "Tag" helpers found in Wheels as well. Sometimes you need to show a group of radio buttons that aren't bound to an object. Perhaps you're buidling a search form that doesn't tie to a database table.

With radioButtonTagGroup(), you pass in a name, value, and the value that should be checked instead of the model object properties.

Here is an example search form based on Google Deutschland (if it were implemented with Wheels instead):

#textFieldTag(name="q", value=params.q)#
#submitTag(name="btn", value="Google-Suche")#
#submitTag(name="btn", value="Auf gut Gl&##252;ck!")#
#radioButtonTagGroup(legend="Suche:", name="meta", options={lr="Das Web", lang_de="Seiten auf Deutsch", cr="Seiten aus Deutschland"}, checked="lr", fieldsetClass="search-options", labelPlacement="after")#

That example would produce HTML markup similar to this:

<input type="text" name="q" value="" />
<input type="submit" name="btn" value="Google-Suche" />
<input type="submit" name="btn" value="Auf gut Gl&#252;ck!" />
<fieldset class="search-options">
    <legend>Suche:</legend>
    <input id="meta-lr" type="radio" name="meta" value="lr" checked="checked" /><label for="meta-lr">Das Web</label>
    <input id="meta-lang_de" type="radio" name="meta" value="lang_de" /><label for="meta-lang_de">Seiten auf Deutsch</label>
    <input id="meta-cr" type="radio" name="meta" value="cr" /><label for="meta-cr">Seiten aus Deutschland</label>
</fieldset>

Notice that the checked argument in the example above causes the lr value to be checked by default.

Check Box Groups

Because groups of check boxes allow you to select multiple values, this would map to a many-to-many relationship in your model (or you would store the list of IDs in a column in your database table). The nature of a many-to-many relationship dictates that there really is no model to bind the check box group to directly. Accordingly, there is only a "Tag" style helper for check box groups.

Show the Tags with `checkBoxTagGroup()`

The checkBoxTagGroup() helper is similar to radioButtonTagGroup(), except the checked argument accepts a list, query, or array of values that should be checked by default.

Here is an example of a form for editing a developer's preferred CFML engines.

<--- In the controller --->
<cfset allCfmlEngines = model("cfmlEngine").findAll(order="engine")>
<cfset developer = model("developer").findByKey(params.key)>
<--- For this example, developer is tied to cfmlEngine through a join table called preferredCfmlEngines and an association of hasMany(name="preferredCfmlEngines" shortcut="cfmlEngines") --->
<cfset preferredCfmlEngines = developer.cfmlEngines()>

<--- In the view --->
#checkBoxTagGroup(legend="Preferred CFML Engine", name="cfmlEngines", options=allCfmlEngines, checked=preferredCfmlEngines, textField="engine", valueField="id")#

If the database returned that the developer's preferred engines were Railo and OpenBD, here is what the produced markup would look similar to:

<fieldset>
    <legend>Preferred CFML Engines</legend>
    <label for="cfmlEngine-1">ColdFusion<input type="checkbox" id="cfmlEngine-1" name="cfmlEngine" value="1" /></label>
    <label for="cfmlEngine-2">OpenBD<input type="checkbox" id="cfmlEngine-2" name="cfmlEngine" value="2" checked="checked" /></label>
    <label for="cfmlEngine-3">Railo<input type="checkbox" id="cfmlEngine-3" name="cfmlEngine" value="3" checked="checked" /></label>
</fieldset>

Setting Global Defaults

These 3 group helpers are similar to standard Wheels form helpers in that you can also set global defaults for the behavior of the radio buttons and check boxes.

For example, if we wanted to make all labels appear after their respective check boxes and radio buttons, we would set the following global defaults in config/settings.cfm:

#cfset set(functionName="checkBoxTagGroup", labelPlacement="after")>
#cfset set(functionName="radioButtonGroup", labelPlacement="after")>
#cfset set(functionName="radioButtonTagGroup", labelPlacement="after")>

If we wanted to always have them default to not having a fieldset wrapper, we could add to the configurations like so:

#cfset set(functionName="checkBoxTagGroup", isFieldset=false, labelPlacement="after")>
#cfset set(functionName="radioButtonGroup", isFieldset=false, labelPlacement="after")>
#cfset set(functionName="radioButtonTagGroup", isFieldset=false, labelPlacement="after")>

List of Global Defaults

Global defaults can be set for the following form group arguments. Again, they are similar to their counterparts in the standard Wheels form helpers.

valueField
textField
labelPlacement
prependToLabel
appendToLabel
prepend
append

Change Log

Version 0.2—December 1, 2009 Download

Initial release.
Wheels compatibility: 1.0.

Stats

Version

Wheels Compatibility

Downloads

Last Updated

About Plugins

Form Groups

Author

Project Home

Description

Bonus Bug Fix

Usage/Examples

Optional Fieldset and Legend

Radio Button Groups

Bind to Objects with `radioButtonGroup()`

Just Show the Tags with `radioButtonTagGroup()`

Check Box Groups

Show the Tags with `checkBoxTagGroup()`

Setting Global Defaults

List of Global Defaults

Change Log

Version 0.2—December 1, 2009 Download

Stats

Version

Wheels Compatibility

Downloads

Last Updated

About Plugins

Form Groups

Author

Project Home

Description

Bonus Bug Fix

Usage/Examples

Optional Fieldset and Legend

Radio Button Groups

Bind to Objects with radioButtonGroup()

Just Show the Tags with radioButtonTagGroup()

Check Box Groups

Show the Tags with checkBoxTagGroup()

Setting Global Defaults

List of Global Defaults

Change Log

Version 0.2—December 1, 2009 Download

Bind to Objects with `radioButtonGroup()`

Just Show the Tags with `radioButtonTagGroup()`

Show the Tags with `checkBoxTagGroup()`