This extension is no longer supported, meaning no new versions are being developed or planned to be released, if you still like to use it or modify it, source code is available on GitHub.
Check the official website for the live examples and documentation:
Latest Version (for .NET 4.0 or 4.5 and MVC4)
Install via NuGet Package Manager Console:
Install-Package MvcCheckBoxList
Download sample MVC project with extension's stable source code
Contents
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; }
public string Name { get; set; }
public object Tags { get; set; }
public bool IsSelected { get; set; }
}
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; }
}
public class PostedCities {
public string[] CityIDs { get; set; }
}
And our controller accepts class PostedCities:
public ActionResult Examples(PostedCities postedCities) {
return View();
}
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 with strongly-typed name:
@Html.CheckBoxListFor(model => model.LIST_NAME,
model => model.LIST_DATA,
entity => entity.VALUE,
entity => entity.NAME,
model => model.SELECTED_VALUES)
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" })
Or get Tags object from database:
@Html.CheckBoxListFor( ... , x => x.Tags)
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" })
Or get Tags object from database:
@Html.CheckBoxListFor( ... , htmlListInfo, x => x.Tags })
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: 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
- v.1.0
Contributors
