DOT

VVM

 DOCS

Version: 1.0 | 1.1 |

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.

Properties

Name Type Description Notes Default Value
Attributes Dictionary<String,Object>
attribute
inner element
static value
bindable
default
Changed ICommandBinding Gets or sets the command that will be triggered when an item is checked / unchecked.
attribute
inner element
static value
bindable
default
ClientIDMode ClientIDMode Gets or sets the client ID generation algorithm.
attribute
inner element
static value
bindable
default
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
inner element
static value
bindable
default
DataSource Object Gets or sets the source collection or a GridViewDataSet that contains data in the control.
attribute
inner element
static value
bindable
default
EmptyDataTemplate ITemplate Gets or sets the template which will be displayed when the DataSource is empty.
attribute
inner element
static value
bindable
default
Enabled Boolean Gets or sets a value indicating whether the control is enabled and can be modified.
attribute
inner element
static value
bindable
default
True
ID String Gets or sets the unique control ID.
attribute
inner element
static value
bindable
default
InnerText String Gets or sets the inner text of the HTML element.
attribute
inner element
static value
bindable
default
ItemCheckedBinding IValueBinding Gets or sets the binding indicating whether a particular item is checked.
attribute
inner element
static value
bindable
default
ItemEnabledBinding IValueBinding Gets or sets the binding indicating whether a DataSource item can be checked.
attribute
inner element
static value
bindable
default
ItemKeyBinding IValueBinding Gets or sets the binding which retrieves the unique key of a DataSource item.
attribute
inner element
static value
bindable
default
ItemTemplate ITemplate Gets or sets the template used to render each item in the DataSource.
attribute
inner element
static value
bindable
default
ItemTextBinding IValueBinding Gets or sets the binding which retrieves text from a DataSource item. It retrieves the whole item by default.
attribute
inner element
static value
bindable
default
ItemValueBinding IValueBinding Gets or sets the binding which retrieves a value from a checked DataSource item. It retrieves the whole item by default.
attribute
inner element
static value
bindable
default
SelectedValues IEnumerable Gets or sets a collection of values of all items that are checked.
attribute
inner element
static value
bindable
default
Visible Boolean Gets or sets whether the control is visible.
attribute
inner element
static value
bindable
default
True

Events

Name Type Description

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.

HTML Rendered by the Control

Sample 1: Basic Usage

The DataSource property specifies a collection of strings. For each item in the collection, a checkbox is created.

The SelectedValues property is bound to a collection which contains all strings 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 changes will get synchronized with the checkboxes.

<bp:CheckBoxList DataSource="{value: Countries}"
                 SelectedValues="{value: SelectedCountries}" />
using System.Collections.Generic;

namespace DotvvmWeb.Views.Docs.Controls.businesspack.CheckBoxList.sample1
{
    public class ViewModel
    {
        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. To be able to identify these objects, you may 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;

namespace DotvvmWeb.Views.Docs.Controls.businesspack.CheckBoxList.sample2
{
    public class ViewModel
    {
        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 the DataSource collection with the objects in the SelectedValues. If the ItemValueBinding is set and makes the SelectedValues collection use primitive types that can be compared, the ItemKeyBinding property is not needed. Similarly, if the DataSource collection contains only primitive values (string, int etc.), the ItemKeyBinding property is not necessary.

<bp:CheckBoxList DataSource="{value: Countries}"
                 SelectedValues="{value: SelectedCountryIds}"
                 ItemValueBinding="{value: Id}"
                 ItemTextBinding="{value: Name}"/>
using System.Collections.Generic;

namespace DotvvmWeb.Views.Docs.Controls.businesspack.CheckBoxList.sample3
{
    public class ViewModel
    {
        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;

namespace DotvvmWeb.Views.Docs.Controls.businesspack.CheckBoxList.sample4
{
    public class ViewModel
    {
        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}"
                 Enabled="{value: IsControlEnabled}" />

<br />
<bp:CheckBox Checked="{value: IsControlEnabled}"
             Text="Enable control" />
<br />
<bp:CheckBox Checked="{value: Countries[2].IsEnabled}"
             Text="Enable United States" />
using System.Collections.Generic;

namespace DotvvmWeb.Views.Docs.Controls.businesspack.CheckBoxList.sample5
{
    public class ViewModel
    {
        public bool IsControlEnabled { get; set; }
        public bool IsItemEnabled { get; set; }

        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 collections with the items that are checked, you can use the control to switch the individual items on or off in the original 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;

namespace DotvvmWeb.Views.Docs.Controls.businesspack.CheckBoxList.sample6
{
    public class ViewModel
    {
        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.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}">
    <EmptyDataTemplate>
        You must fill the DataSource before you can select countries.
    </EmptyDataTemplate>
    <ItemTemplate>
        <span>{{value: Id}}. {{value: Name}}</span>
    </ItemTemplate>
</bp:CheckBoxList>
using System.Collections.Generic;

namespace DotvvmWeb.Views.Docs.Controls.businesspack.CheckBoxList.sample7
{
    public class ViewModel
    {
        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; }
    }
}

Suggestions


Help & Contribute

The documentation is maintained on GitHub.
We'll be happy if you edit the page and create a pull request.

Send message