DOT

VVM

 DOCS

Version: 1.0 | 1.1 |

MultiSelect

in namespace DotVVM.BusinessPack.Controls

Renders a MultiSelect control similar to ComboBox control. It allows to select multiple values.

Properties

Name Type Description Notes Default Value
AllowNewItems Boolean Gets or sets whether it is allowed to create new items from the entered text.
attribute
inner element
static value
bindable
default
False
Attributes Dictionary<String,Object>
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
Enabled Boolean Gets or sets 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
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 for each item.
attribute
inner element
static value
bindable
default
ItemTextBinding IValueBinding Gets or sets the binding which retrieves the 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 DataSource property. It retrieves the whole item by default.
attribute
inner element
static value
bindable
default
LoadItems Func<String,Task<IEnumerable>> Gets or sets a function used to load additional items from server. For example, it is used to search for items on server-side.
attribute
inner element
static value
bindable
default
Placeholder String Gets or sets the text displayed when no item is selected (or when text is empty).
attribute
inner element
static value
bindable
default
SelectedValues IEnumerable Gets or sets values of the items selected by user.
attribute
inner element
static value
bindable
default
SelectedValueTemplate ITemplate Gets or sets the template for each MultiSelect value.
attribute
inner element
static value
bindable
default
Text String Gets or sets the text value of the control that is used mainly for the LoadItems command.
attribute
inner element
static value
bindable
default
UnselectIconCssClass String Gets or sets the CSS class for the icon displayed on the unselect button. The default value is FaClose.
attribute
inner element
static value
bindable
default
fa fa-close
Visible Boolean Gets or sets whether the control is visible.
attribute
inner element
static value
bindable
default
True

Events

Name Type Description
Changed Command Gets or sets the command that will be triggered when the text (or value) is changed.

Usage & Scenarios

The Business Pack MultiSelect control is a text field which suggests items to select and supports multiple selected items.

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:MultiSelect DataSource="{value: Countries}"
                SelectedValues="{value: SelectedCountries}"
                Placeholder="Select multiple countries" />
using System.Collections.Generic;

namespace DotvvmWeb.Views.Docs.Controls.businesspack.MultiSelect.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:MultiSelect DataSource="{value: Countries}"
                SelectedValues="{value: SelectedCountries}"
                ItemTextBinding="{value: Name}"
                ItemKeyBinding="{value: Id}"
                Placeholder="Select multiple countries" />
using System.Collections.Generic;

namespace DotvvmWeb.Views.Docs.Controls.businesspack.MultiSelect.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.MultiSelect.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:MultiSelect DataSource="{value: Countries}"
                SelectedValues="{value: SelectedCountries}"
                ItemValueBinding="{value: Id}"
                ItemTextBinding="{value: Name}"
                Placeholder="Select multiple countries"
                Changed="{command: PrintSummary()}" />

<p>Selected Countries: {{value: Summary}}</p>
using System.Collections.Generic;
using System.Linq;

namespace DotvvmWeb.Views.Docs.Controls.businesspack.MultiSelect.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> SelectedCountries { get; set; } = new List<int>();
        public string Summary { get; set; }

        public void PrintSummary()
        {
            Summary = string.Join(", ", SelectedCountries.Select(c => c.ToString()));
        }
    }
}
using System.Collections.Generic;

namespace DotvvmWeb.Views.Docs.Controls.businesspack.MultiSelect.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: Item Templates

To display custom content in the list items, you can use the ItemTemplate property to declare a custom template for the list items.

<bp:MultiSelect DataSource="{value: Cities}"
                SelectedValues="{value: SelectedCities}"
                ItemKeyBinding="{value: Id}"
                Placeholder="Select multiple cities">
    <ItemTemplate>
        <span>{{value: Name}}, {{value: Country}}</span>
    </ItemTemplate>
</bp:MultiSelect>
using System.Collections.Generic;

namespace DotvvmWeb.Views.Docs.Controls.businesspack.MultiSelect.sample4
{
    public class ViewModel
    {
        public List<City> Cities { get; set; } = new List<City> {
            new City { Id = 1, Name = "Prague", Country = "Czech Republic" },
            new City { Id = 2, Name = "Bratislava", Country = "Slovakia" }
        };

        public List<City> SelectedCities { get; set; } = new List<City>();
    }
}
namespace DotvvmWeb.Views.Docs.Controls.businesspack.MultiSelect.sample4
{
    public class City
    {
        public int Id { get; set; }
        public string Name { get; set; }
        public string Country { get; set; }
    }
}

Sample 5: Changed Event

The Changed event is triggered whenever the selection changes.

<bp:MultiSelect DataSource="{value: Countries}"
                SelectedValues="{value: SelectedCountries}"
                Placeholder="Select multiple countries"
                Changed="{command: SelectionChanged()}" />

<p>You've selected {{value: SelectedCountriesCount}} countries.</p>
using System.Collections.Generic;

namespace DotvvmWeb.Views.Docs.Controls.businesspack.MultiSelect.sample5
{
    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 6: New Items

To allow entering a custom value which is not present in the DataSource collection, you can use the AllowNewItems property.

The Text property contains the exact value the user entered in the text field.

This feature can be used only when the DataSource collection contains string values.

<bp:MultiSelect DataSource="{value: Countries}"
                SelectedValues="{value: SelectedCountries}"
                AllowNewItems="true"
                Placeholder="Select or type multiple countries" />
using System.Collections.Generic;

namespace DotvvmWeb.Views.Docs.Controls.businesspack.MultiSelect.sample6
{
    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 7: Server Search

The LoadItems property can specify a command in the viewmodel which will return new items based on what the user types in the control. Typically, this method is used with the Static Command and the method should return a list of items, and you need to use the value of the Text property as an argument to the viewmodel method.

The method in the viewmodel performs the search and returns a collection of items. These items are cached in the DataSource collection.

If you use the static command, don't forget to decorate the method with the AllowStaticCommand attribute.

In the future versions of DotVVM, there are plans to enhance the server search functionality with more features (e.g. REST API integration).

<bp:MultiSelect DataSource="{value: Countries}"
                SelectedValues="{value: SelectedCountries}"
                Text="{value: Text}"
                LoadItems="{staticCommand: LoadCountries(Text)}"
                Placeholder="Search and select multiple countries" />
using System.Collections;
using System.Collections.Generic;
using DotVVM.Framework.ViewModel;

namespace DotvvmWeb.Views.Docs.Controls.businesspack.MultiSelect.sample7
{
    public class ViewModel
    {
        public string Text { get; set; }
        public List<string> Countries { get; set; } = new List<string>();
        public List<string> SelectedCountries { get; set; } = new List<string>();

        [AllowStaticCommand]
        public IEnumerable LoadCountries(string searchText)
        {
            return new List<string> {
                $"{searchText} 1", $"{searchText} 2", $"{searchText} 3"
            };
        }
    }
}

Sample 8: Item Keys

The ItemKeyBinding property must be used when the SelectedValue is not a primitive type (like string, int etc.). This property helps the control to uniquely identify the selected object.

<bp:MultiSelect DataSource="{value: Cities}"
                SelectedValues="{value: SelectedCities}"
                ItemKeyBinding="{value: Id}"
                Placeholder="Select multiple cities">
    <ItemTemplate>
        <span>{{value: Name}}, {{value: Country}}</span>
    </ItemTemplate>
</bp:MultiSelect>
using System.Collections.Generic;

namespace DotvvmWeb.Views.Docs.Controls.businesspack.MultiSelect.sample8
{
    public class ViewModel
    {
        public List<City> Cities { get; set; } = new List<City> {
            new City { Id = 1, Name = "Washington", Country = "Utah" },
            new City { Id = 2, Name = "Washington", Country = "Kansas" },
            new City { Id = 3, Name = "Washington", Country = "Georgia" }
        };

        public List<City> SelectedCities { get; set; } = new List<City>();
    }
}
namespace DotvvmWeb.Views.Docs.Controls.businesspack.MultiSelect.sample8
{
    public class City
    {
        public int Id { get; set; }
        public string Name { get; set; }
        public string Country { 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