CheckBoxList
in namespace DotVVM.BusinessPack.Controls
Renders a control that renders a list of check boxes for a collection and allows the user to select some of them.
Usage & Scenarios
Renders a list of CheckBox controls and lets the user to select multiple values.
The values are stored in a collection bound to the SelectedValues
property of the control.
Sample 1: Basic Usage
The DataSource
property specifies a collection of strings. For each item in the collection, a checkbox will be created.
The SelectedValues
property is bound to a collection which contains all values of checkboxes that are checked. The data-binding works in both ways, so you can either read, or modify the collection in the viewmodel and the checkbox states will be synchronized to reflect changes made to the collection.
<bp:CheckBoxList DataSource="{value: Countries}"
SelectedValues="{value: SelectedCountries}" />
using System.Collections.Generic;
using DotVVM.Framework.ViewModel;
namespace DotvvmWeb.Views.Docs.Controls.businesspack.CheckBoxList.sample1
{
public class ViewModel : DotvvmViewModelBase
{
public List<string> Countries { get; set; } = new List<string> {
"Czech Republic", "Slovakia", "United States"
};
public List<string> SelectedCountries { get; set; } = new List<string>();
}
}
Sample 2: Working with Objects
When the DataSource
collection is bound to a collection of objects, you may use the ItemTextBinding
to specify, which property of the object in the collection will be displayed as a text of a particular checkbox control.
The SelectedValues
will contain the objects from the DataSource
collection which are checked.
In order to allow the control to uniquely identify these objects, you need to use the ItemKeyBinding
property to define a property which can work as a key. The key must be unique for all items in the collection, otherwise the control will not work properly.
<bp:CheckBoxList DataSource="{value: Countries}"
SelectedValues="{value: SelectedCountries}"
ItemTextBinding="{value: Name}"
ItemKeyBinding="{value: Id}" />
using System.Collections.Generic;
using DotVVM.Framework.ViewModel;
namespace DotvvmWeb.Views.Docs.Controls.businesspack.CheckBoxList.sample2
{
public class ViewModel : DotvvmViewModelBase
{
public List<Country> Countries { get; set; } = new List<Country> {
new Country { Id = 1, Name = "Czech Republic" },
new Country { Id = 2, Name = "Slovakia" },
new Country { Id = 3, Name = "United States" }
};
public List<Country> SelectedCountries { get; set; } = new List<Country>();
}
}
using System.Collections.Generic;
namespace DotvvmWeb.Views.Docs.Controls.businesspack.CheckBoxList.sample2
{
public class Country
{
public int Id { get; set; }
public string Name { get; set; }
public List<string> Cities { get; set; } = new List<string>();
public bool IsEnabled { get; set; } = true;
public bool IsChecked { get; set; }
}
}
Sample 3: Working with Objects 2
To make the SelectedValues
property contain only some values from the DataSource
objects (like the Id
property of the object), you may use the ItemValueBinding
property.
The SelectedValues
will then contain only the values of the properties specified in the ItemValueBinding
. Provided the values of the properties used as a value are unique, you don't need to specify the ItemKeyBinding
property.
The
ItemKeyBinding
property is required only when the control cannot compare the objects in theDataSource
collection with the objects in theSelectedValues
. If theItemValueBinding
is set and makes theSelectedValues
collection use primitive types that can be compared, theItemKeyBinding
property is not needed. Similarly, if theDataSource
collection contains only primitive values (string
,int
etc.), theItemKeyBinding
property is not necessary.
<bp:CheckBoxList DataSource="{value: Countries}"
SelectedValues="{value: SelectedCountryIds}"
ItemValueBinding="{value: Id}"
ItemTextBinding="{value: Name}"/>
using System.Collections.Generic;
using DotVVM.Framework.ViewModel;
namespace DotvvmWeb.Views.Docs.Controls.businesspack.CheckBoxList.sample3
{
public class ViewModel : DotvvmViewModelBase
{
public List<Country> Countries { get; set; } = new List<Country> {
new Country { Id = 1, Name = "Czech Republic" },
new Country { Id = 2, Name = "Slovakia" },
new Country { Id = 3, Name = "United States" }
};
public List<int> SelectedCountryIds { get; set; } = new List<int>();
}
}
using System.Collections.Generic;
namespace DotvvmWeb.Views.Docs.Controls.businesspack.CheckBoxList.sample3
{
public class Country
{
public int Id { get; set; }
public string Name { get; set; }
public List<string> Cities { get; set; } = new List<string>();
public bool IsEnabled { get; set; } = true;
public bool IsChecked { get; set; }
}
}
Sample 4: Changed Event
The Changed
event is triggered whenever the selection changes.
<bp:CheckBoxList DataSource="{value: Countries}"
SelectedValues="{value: SelectedCountries}"
Changed="{command: SelectionChanged()}" />
<p>You've selected {{value: SelectedCountriesCount}} countries.</p>
using System.Collections.Generic;
using DotVVM.Framework.ViewModel;
namespace DotvvmWeb.Views.Docs.Controls.businesspack.CheckBoxList.sample4
{
public class ViewModel : DotvvmViewModelBase
{
public int SelectedCountriesCount { get; set; }
public List<string> Countries { get; set; } = new List<string> {
"Czech Republic", "Slovakia", "United States"
};
public List<string> SelectedCountries { get; set; } = new List<string>();
public void SelectionChanged()
{
SelectedCountriesCount = SelectedCountries.Count;
}
}
}
Sample 5: Disabling CheckBoxes
If you need to disable some of the checkboxes, you can use the ItemEnabledBinding
to determine which checkboxes will be enabled and which will not. By default, all checkboxes are enabled and can be checked or unchecked freely.
The Enabled
property on the control takes the precedence before the ItemEnabledBinding
.
<bp:CheckBoxList DataSource="{value: Countries}"
SelectedValues="{value: SelectedCountries}"
ItemKeyBinding="{value: Id}"
ItemTextBinding="{value: Name}"
ItemEnabledBinding="{value: IsEnabled}" />
<br />
<bp:CheckBox Checked="{value: Countries[2].IsEnabled}"
Text="Enable United States" />
using System.Collections.Generic;
using DotVVM.Framework.ViewModel;
namespace DotvvmWeb.Views.Docs.Controls.businesspack.CheckBoxList.sample5
{
public class ViewModel : DotvvmViewModelBase
{
public List<Country> Countries { get; set; } = new List<Country> {
new Country { Id = 1, Name = "Czech Republic" },
new Country { Id = 2, Name = "Slovakia" },
new Country { Id = 3, Name = "United States", IsEnabled = false }
};
public List<Country> SelectedCountries { get; set; } = new List<Country>();
}
}
using System.Collections.Generic;
namespace DotvvmWeb.Views.Docs.Controls.businesspack.CheckBoxList.sample5
{
public class Country
{
public int Id { get; set; }
public string Name { get; set; }
public List<string> Cities { get; set; } = new List<string>();
public bool IsEnabled { get; set; } = true;
public bool IsChecked { get; set; }
}
}
Sample 6: In-place Checked Property
If you do not need to have a second collection with the items that are checked, you can make the control to store the state of the individual items in the items of the DataSource
collection.
Let's assume that the DataSource
collection items have the IsChecked
property. We can have this property set to true
or false
based on the checkbox state, using the ItemCheckedBinding
property.
<bp:CheckBoxList DataSource="{value: Countries}"
ItemCheckedBinding="{value: IsChecked}"
ItemTextBinding="{value: Name}"
ItemKeyBinding="{value: Id}" />
using System.Collections.Generic;
using DotVVM.Framework.ViewModel;
namespace DotvvmWeb.Views.Docs.Controls.businesspack.CheckBoxList.sample6
{
public class ViewModel : DotvvmViewModelBase
{
public List<Country> Countries { get; set; } = new List<Country> {
new Country { Id = 1, Name = "Czech Republic", IsChecked = true },
new Country { Id = 2, Name = "Slovakia" },
new Country { Id = 3, Name = "United States" }
};
}
}
using System.Collections.Generic;
namespace DotvvmWeb.Views.Docs.Controls.businesspack.CheckBoxList.sample6
{
public class Country
{
public int Id { get; set; }
public string Name { get; set; }
public List<string> Cities { get; set; } = new List<string>();
public bool IsEnabled { get; set; } = true;
public bool IsChecked { get; set; }
}
}
Sample 7: Templates
To display custom content in the control, you can use the ItemTemplate
property to declare a custom template for the data source items.
You can also use the EmptyDataTemplate
when you want to display contents when the DataSource
is empty.
<bp:CheckBoxList DataSource="{value: Countries}"
ItemCheckedBinding="{value: IsChecked}"
ItemTextBinding="{value: Name}"
ItemKeyBinding="{value: Id}">
<ItemTemplate>
<span>{{value: Id}}. {{value: Name}}</span>
</ItemTemplate>
</bp:CheckBoxList>
<br />
<bp:CheckBoxList DataSource="{value: SelectedCountries}"
ItemCheckedBinding="{value: IsChecked}"
ItemTextBinding="{value: Name}"
ItemKeyBinding="{value: Id}">
<EmptyDataTemplate>
You must fill the DataSource before you can select countries.
</EmptyDataTemplate>
</bp:CheckBoxList>
using System.Collections.Generic;
using DotVVM.Framework.ViewModel;
namespace DotvvmWeb.Views.Docs.Controls.businesspack.CheckBoxList.sample7
{
public class ViewModel : DotvvmViewModelBase
{
public List<Country> Countries { get; set; } = new List<Country> {
new Country { Id = 1, Name = "Czech Republic", IsChecked = true },
new Country { Id = 2, Name = "Slovakia" },
new Country { Id = 3, Name = "United States" }
};
public List<Country> SelectedCountries { get; set; } = new List<Country>();
}
}
using System.Collections.Generic;
namespace DotvvmWeb.Views.Docs.Controls.businesspack.CheckBoxList.sample7
{
public class Country
{
public int Id { get; set; }
public string Name { get; set; }
public List<string> Cities { get; set; } = new List<string>();
public bool IsEnabled { get; set; } = true;
public bool IsChecked { get; set; }
}
}
Properties
Name | Type | Description | Notes | Default Value | |
---|---|---|---|---|---|
Attributes | Dictionary<String,Object> |
attribute
static value
|
null | ||
ClientIDMode | ClientIDMode | Gets or sets the client ID generation algorithm. |
attribute
static value
|
Static | |
DataContext | Object | Gets or sets a data context for the control and its children. All value and command bindings are evaluated in context of this value. |
attribute
static value
bindable
|
null | |
DataSource | IEnumerable |
attribute
bindable
|
null | ||
EmptyDataTemplate | ITemplate | Gets or sets the template which will be displayed when the DataSource is empty. |
inner element
static value
|
null | |
Enabled | Boolean | Gets or sets a value indicating whether the control is enabled and can be modified. |
attribute
static value
bindable
|
False | |
ID | String | Gets or sets the unique control ID. |
attribute
static value
bindable
|
null | |
IncludeInPage | Boolean | Gets or sets whether the control is included in the DOM of the page. |
attribute
bindable
|
True | |
InnerText | String | Gets or sets the inner text of the HTML element. |
attribute
static value
bindable
|
null | |
ItemCheckedBinding | IValueBinding<Boolean?> | Gets or sets the binding indicating whether a particular item is checked. |
attribute
static value
bindable
|
null | |
ItemEnabledBinding | IValueBinding<Boolean?> | Gets or sets the binding indicating whether a DataSource item can be checked. |
attribute
static value
bindable
|
null | |
ItemKeyBinding | IValueBinding | Gets or sets the binding which retrieves the unique key of a DataSource item. |
attribute
static value
bindable
|
null | |
ItemTemplate | ITemplate | Gets or sets the template used to render each item in the DataSource. |
inner element
static value
default
|
null | |
ItemTextBinding | IValueBinding<String> | Gets or sets the binding which retrieves text from a DataSource item. It retrieves the whole item by default. |
attribute
static value
bindable
|
null | |
ItemValueBinding | IValueBinding | Gets or sets the binding which retrieves a value from a checked DataSource item. It retrieves the whole item by default. |
attribute
static value
bindable
|
null | |
SelectedValues | IEnumerable | Gets or sets a collection of values of all items that are checked. |
attribute
bindable
|
null | |
Visible | Boolean | Gets or sets whether the control is visible. |
attribute
bindable
|
True |
Events
Name | Type | Description | |
---|---|---|---|
Changed | ICommandBinding | Gets or sets the command that will be triggered when an item is checked / unchecked. |