CheckBoxList(For) - A missing MVC extension

Check out official website with live examples and documentation:

mvccbl.com

Latest Version (for .NET 4.0 or 4.5 and MVC4)

Install via NuGet Package Manager Console:

Install-Package MvcCheckBoxList

This version has few breaking changes, so if something doesn't work after update, check documentation.

Download binary (MvcCheckBoxList.dll)

Download MvcCheckBoxList.zip

Download sample MVC project with extension's stable source code

Introduction
Using the code

Given we have...
Base overloads
Basic settings
Advanced Settings

Live Examples
History
Contributors

Introduction

One of the cool features of Microsoft MVC web development framework since its inception, was its rich Html helpers library. It provided helpers to create most common html controls like text boxes, drop down lists, text areas, etc. It is done by simply typing Html.<smth> on the MVC view page.

Its all been good and easily customizable, until developers been eventually reaching one blank spot... That spot was a creation of a checkbox lists. There was none, and there is no any control to handle that functionality as of now.

To create a checkbox list a developer would have to use a combination of FOR or FOREACH cycle and some html <input> along with it.

While not being a hard thing to do, it could possibly become pretty time consuming. Especially when project was getting bigger and fatter with a whole bunch of repetitive code lying around. And think about adding some advanced functionality and layout. For example, when we want to disable some checkboxes, while at the same time being able to POST it back to your controller, and on top of that, putting it into the <table>, it would become quite bigger than before.

But what if we would want to put it into several columns? It would require even more customization. And would get even bigger. This little extension intends to simplify this task while making it more inline with general MVC workflow.

This plugin is just an extension of MVC class 'HtmlHelper', which is used for all Html helpers on MVC views. Since there is no supported CheckBoxList extension built into MVC, this plugin adds it.

Using the code

All examples below are shown using MVC + Razor view engine. Examples will demonstrate recommended real-world scenario of using this extension.

Given we have...

Base class City:

public class City {
  public int Id { get; set; }           // Integer value of a checkbox
  public string Name { get; set; }      // String name of a checkbox
  public object Tags { get; set; }      // Object of html tags to be applied to checkbox, e.g.: 'new { tagName = "tagValue" }'
  public bool IsSelected { get; set; }  // Boolean value to select a checkbox on the list
}

And we use CitiesViewModel view model on our view:

public class CitiesViewModel {
  public IList<City> AvailableCities { get; set; }
  public IList<City> SelectedCities { get; set; }
  public PostedCities PostedCities { get; set; }
}

// Helper class to make posting back selected values easier
public class PostedCities {
  public string[] CityIDs { get; set; }
}

And our controller accepts class PostedCities:

public ActionResult Examples(PostedCities postedCities) {
  return View(/* Create View Model */);
}

Source: documentation > Given we have...

Base Overloads

Now we can create a control on the view, first - keep in mind base checkbox list call structure:

@Html.CheckBoxList("LIST_NAME", 
                   model => model.LIST_DATA, 
                   entity => entity.VALUE, 
                   entity => entity.NAME, 
                   model => model.SELECTED_VALUES) // or entity => entity.IS_CHECKED

Or with strongly-typed name:

@Html.CheckBoxListFor(model => model.LIST_NAME, 
                      model => model.LIST_DATA, 
                      entity => entity.VALUE, 
                      entity => entity.NAME, 
                      model => model.SELECTED_VALUES) // or entity => entity.IS_CHECKED

So in our example it'll look like this:

@Html.CheckBoxListFor(model => model.PostedCities.CityIDs, 
                      model => model.AvailableCities, 
                      entity => entity.Id, 
                      entity => entity.Name, 
                      model => model.SelectedCities)

Or if using boolean selector:

@Html.CheckBoxListFor(model => model.PostedCities.CityIDs, 
                      model => model.AvailableCities, 
                      entity => entity.Id, 
                      entity => entity.Name, 
                      entity => entity.IsSelected)

where entity.IsSelected is a boolean value from database,

And another way to use boolean selector:

@Html.CheckBoxListFor(model => model.PostedCities.CityIDs, 
                      model => model.AvailableCities, 
                      entity => entity.Id, 
                      entity => entity.Name, 
                      entity => selectedIds.Contains(x.Id))

where selectedIds.Contains(x.Id) returns bool if item Id matches the list.

Source: documentation > Base Overloads.

Basic Settings:

Since five base properties (see previous section) don't change, only extra ones will be shown, so placeholder ... means usage of five base properties. You might need to add this reference to your view first (namespace for Position enum and others):

@using MvcCheckBoxList.Model

1. Set position (direction) of the list:

@Html.CheckBoxListFor( ... , Position.Horizontal)

Position Can be Position.Horizontal, Position.Vertical, Position.Horizontal_RightToLeft, or Position.Vertical_RightToLeft where last two are to reverse checkbox and label for right-to-left languages 2. Set html attributes for both checkbox and label:

@Html.CheckBoxListFor( ... , x => new { @class="class_name" }) // Tags will be applied to all checkbox/label combos

Or get Tags object from database:

@Html.CheckBoxListFor( ... , x => x.Tags) // x.Tags will be applied only to particular checkbox/label combo

3. Set html attributes and position:

@Html.CheckBoxListFor( ... , Position.Horizontal, x => new { @class="class_name" })

4. Set html attributes for all, disabled values, position, and individual html attributes (all attributes will be merged together):

@Html.CheckBoxListFor( ... , x => new { @class="class_name" }, new[] {"3", "5", "7"}, Position.Horizontal, x => x.Tags)

Source: documentation > Basic Settings.

Advanced Settings:

You might need to add this reference to your view first (namespace for HtmlListInfo class and others):

@using MvcCheckBoxList.Model

1. Set custom layout using HtmlListInfo class:

var htmlListInfo = new HtmlListInfo(HtmlTag.table, 2, new { @class="class_name" }, TextLayout.Default, TemplateIsUsed.Yes);

@Html.CheckBoxListFor( ... , htmlListInfo)

There, in HtmlListInfo class, HtmlTag can be HtmlTag.table or HtmlTag.vertical_columns; 2 is a number of columns; TextLayout can be TextLayout.Default or TextLayout.RightToLeft (for right to left languages)

2. Set layout with HtmlListInfo class and set html attributes:

@Html.CheckBoxListFor( ... , htmlListInfo, x => new { tagName = "tagValue" })  // Tags will be applied to all checkbox/label combos

Or get Tags object from database:

@Html.CheckBoxListFor( ... , htmlListInfo, x => x.Tags })  // x.Tags will be applied only to particular checkbox/label combo

3. Set html attributes for all, set layout with HtmlListInfo, set disabled values, and individual html attributes (all attributes will be merged together):

@Html.CheckBoxListFor( ... , new { @class="class_name" }, htmlListInfo, new[] {"3", "5", "7"}, x => x.Tags)

There, x.Tags is a value of type object and should be equal to something similar to this new { tag1 = "value1", tag2="value2" } and represent one or more custom html attributes, and will be applied to both checkbox and label.

Also note that x.Tags is an optional parameter for each available overload. Just add it as a last parameter to @Html.CheckBoxListFor( ... , x => x.Tags) checkbox list call.

Source: documentation > Advanced Settings.

Live Examples

Official website (from source code) has a dedicated live examples section to demonstrate how this extension will work in various real-world scenarios.

Please see this extension in action here: mvccbl.com > Examples.

History

v.1.4.4.4

Adds support for both .NET 4.0 and 4.5

v.1.4.3.0

Added support for right-to-left languages (by flipping the order of checkbox and label)
Removed model-independent functionality

v.1.4.2.3
- Fixed a bug where it requires MVC4 dependency (System.Web.WebPages 2.0.0.0), and doesn't work in MVC3 projects...
v.1.4.2.2
- NuGet package added!
- Additional parameter for both 'CheckBoxList' and 'CheckBoxListFor' - 'htmlAttributesExpr' allows to pass custom html tags from database to be applied to each individual checkbox (see good exaple of this in sample MVC3 project)
- Improved name generation
- Numerous other small fixes...
v.1.3c
- Some minor bug fixes done
- Created a sample MVC3 .NET 4.0 site which comes along with this control, so you can test it first hand!
v.1.3b
- Added function annotations, some code cleanup
v.1.3a
- Instead of plain checkbox name it now creates a label linked to checkbox, so you can also click on the label to select that checkbox! Many thanks to william0565 for idea !
v.1.3
- 'CheckBoxListFor' now generates full name from a lambda expression: e.g.: @Html.CheckBoxListFor(model => model.SomeClass.SubClass .... ) will create a list of checkboxes with 'name="SomeClass.SubClass"', where older version would create only 'name="SubClass"'
v.1.2

You can now create strongly typed checkbox list from your view model!
Added new method 'CheckBoxListFor' to be used with strongly typed approach

v.1.1

Added new option 'HtmlTag.vertical_columns', which allows checkboxes to be arranged inside 4 vertically sorted floating sections
Overload functions cleanup
Overall code cleanup