CheckboxListComponent

Introduction

CheckboxListComponent is a Monorail view component that renders a checkbox list. Two parameters are required: source and target. "source" contains the data to populate the checkbox list items. "target" is the name of the object that contains the selected values. The data source may consist of primitives such as enums or can be objects of a complex type. The list can be be displayed in a vertical or horizontal orientation, and in multiple columns. By default CheckboxListComponent splits label values that are "Pascal Case." For example "InProcess" will be displayed as "In Process".

Parameters

CheckboxListComponent takes the following parameters:

NOTE: The columns parameter only affects the appearance of vertical checkbox lists.

Sections

CheckboxListComponent can have the following sections:

• containterStart
• containerEnd
• itemStart
• itemEnd

By default, the container is a div element. Be default, the item is a div element if vertical, span element if horizontal.

NOTE: If you specify a containerStart section, the style, cssClass and toolTip parameters will be ignored.

A Simple Example

In the controller:

private IList<Status> selectedStatuses = new List<Status>();
selectedStatuses.Add(Status.InProcess);
selectedStatuses.Add(Status.Billed);

PropertyBag["statuses"] = Enum.GetValues(typeof(Status));
PropertyBag["selectedStatuses"] = selectedStatuses;

In the view:

#component(CheckboxList with "target=selectedStatuses" "source=$statuses")

The above will render a vertical checkbox list of all statuses, with "In Process" and "Billed" checked.

Example Using A Complex Type

In the controller:

private IList<Color> colors = new List<Color>();
colors.Add(new Color("Red", "ff0000"));
colors.Add(new Color("Blue", "0000ff"));
colors.Add(new Color("Green", "008000"));

private IList<Color> selectedColors = new List<Color>();
selectedColors.Add(colors[1]);

PropertyBag["colors"] = colors;
PropertyBag["selectedColors"] = selectedColors;

In the view

#component(CheckboxList with "target=selectedColors" "source=$colors" "displayMember=Name", "valueMember=Code" "horizontal=true")

The above will render a horizontal checkbox list of "Red" "Blue" and "Green" with "Blue" checked.

Styling The CheckboxList

You can style the checkbox list using css classes, style parameters and/or sections.

Here is an example of css styles:

.verticalCheckboxList
{
	height:100px;
	border: solid 1px gray;
	overflow-y: scroll;
	overflow-x: hidden;
}

.verticalCheckboxList div,
{
	padding: 3px 0;
}

.verticalCheckboxList label
{
	color:blue;
}

The first style block shown above affects the list's outer container. The second controls the items (checkbox and label). The third controls only the checkbox labels. To style checkbox items for horizontal lists, use "span" instead of "div."

The outer container and the labels use some inline styles by default. You may override these by specifying the corresponding parameters. This can be useful for exceptions. For example, you might have a certain type of checkbox list for which you want a consistent appearance throughout the application. However, you might want one instance to vary slightly. Inline styles override css classes, so by specifying these parameters you can easily make slight variations to individual instances.

You can also use sections to control appearance by using styles or even changing the type of container.

NOTE: overflow-x and overflow-y provide the control of scrolling that you would typically want in a checkbox list.  Please note, however, that they are non-standard; they are proposed for CSS3.   However, they have been tested to work fairly well in most popular browsers.

More Info

For examples, take a look at the sample website here:

http://svn.castleproject.org:8080/svn/castlecontrib/viewcomponents/trunk