MultiSelect
in namespace DotVVM.BusinessPack.Controls
Renders a MultiSelect control similar to ComboBox control. It allows to select multiple values.
Usage & Scenarios
The Business Pack MultiSelect
control is a text field which suggests items to select and supports multiple selected items.
Sample 1: Basic Usage
The DataSource
property specifies a collection of strings. When the user starts interacting with the control, a list of items made from this collection will appear.
The SelectedValues
property is bound to a collection which contains all items that are selected. The data-binding works in both ways, so you can either read, or modify the collection in the viewmodel and the selected values in the control will get synchronized to reflect the changes.
The Placeholder
specifies the text displayed when the Text
is empty.
<bp:MultiSelect DataSource="{value: Countries}"
SelectedValues="{value: SelectedCountries}"
Placeholder="Select multiple countries" />
using System.Collections.Generic;
using DotVVM.Framework.ViewModel;
namespace DotvvmWeb.Views.Docs.Controls.businesspack.MultiSelect.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:MultiSelect DataSource="{value: Countries}"
SelectedValues="{value: SelectedCountries}"
ItemTextBinding="{value: Name}"
ItemKeyBinding="{value: Id}"
Placeholder="Select multiple countries" />
using System.Collections.Generic;
using DotVVM.Framework.ViewModel;
namespace DotvvmWeb.Views.Docs.Controls.businesspack.MultiSelect.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.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 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: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;
using DotVVM.Framework.ViewModel;
namespace DotvvmWeb.Views.Docs.Controls.businesspack.MultiSelect.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> 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}"
ItemTextBinding="{value: Name}"
Placeholder="Select multiple cities">
<ItemTemplate>
<span>{{value: Name}}, {{value: Country}}</span>
</ItemTemplate>
</bp:MultiSelect>
using System.Collections.Generic;
using DotVVM.Framework.ViewModel;
namespace DotvvmWeb.Views.Docs.Controls.businesspack.MultiSelect.sample4
{
public class ViewModel : DotvvmViewModelBase
{
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;
using DotVVM.Framework.ViewModel;
namespace DotvvmWeb.Views.Docs.Controls.businesspack.MultiSelect.sample5
{
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 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;
using DotVVM.Framework.ViewModel;
namespace DotvvmWeb.Views.Docs.Controls.businesspack.MultiSelect.sample6
{
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 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 either added to existing items in the DataSource
collection or they replace the existing items. It depends on the LoadItemsMode
property.
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 : DotvvmViewModelBase
{
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.), or when the ItemValueBinding
is not specified.
This property helps the control to uniquely identify the selected object.
<bp:MultiSelect DataSource="{value: Cities}"
SelectedValues="{value: SelectedCities}"
ItemKeyBinding="{value: Id}"
ItemTextBinding="{value: Name}"
Placeholder="Select multiple cities">
<ItemTemplate>
<span>{{value: Name}}, {{value: Country}}</span>
</ItemTemplate>
</bp:MultiSelect>
using System.Collections.Generic;
using DotVVM.Framework.ViewModel;
namespace DotvvmWeb.Views.Docs.Controls.businesspack.MultiSelect.sample8
{
public class ViewModel : DotvvmViewModelBase
{
public List<City> Cities { get; set; } = new List<City> {
new City { Id = 1, Name = "Salt Lake City", Country = "Utah" },
new City { Id = 2, Name = "Wichita", Country = "Kansas" },
new City { Id = 3, Name = "Atlanta", 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; }
}
}
Sample 9: Customizing Icons
The icon used by the control can be customized using the following inner elements:
UnselectIcon
represents an icon that allows the user to deselect items. The default isClose
icon.
See the Icon documentation to find about using other icon packs.
<bp:MultiSelect DataSource="{value: Countries}"
SelectedValues="{value: SelectedCountries}"
Placeholder="Select multiple countries" >
<UnselectIcon>
<bp:Icon Icon="Minus"></bp:Icon>
</UnselectIcon>
</bp:MultiSelect>
using System.Collections.Generic;
using DotVVM.BusinessPack.Controls;
using DotVVM.Framework.ViewModel;
namespace DotvvmWeb.Views.Docs.Controls.businesspack.MultiSelect.sample9
{
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>();
}
}
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
static value
bindable
|
False | |
Attributes | Dictionary<String,Object> |
attribute
static value
|
null | ||
AutoFocus | Boolean | Gets or sets whether the control should have focus when page loads or when a dialog is opened. The default value is false. |
attribute
static value
|
False | |
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 | ||
Enabled | Boolean | Gets or sets 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 | |
ItemEnabledBinding | IValueBinding<Boolean?> | Gets or sets the binding indicating whether a DataSource item can be selected. |
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 the 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 DataSource property. It retrieves the whole item by default. |
attribute
static value
bindable
|
null | |
LoadItems | MultiSelect+LoadItemsFunc | 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
bindable
|
null | |
LoadItemsMode | LoadItemsMode | Gets or sets how are items returned by the LoadItems command processed. They can either be merged with existing items in the DataSource; or they can replace them. The default value is Merge. |
attribute
static value
bindable
|
Merge | |
Placeholder | String | Gets or sets the text displayed when no item is selected (or when text is empty). |
attribute
static value
|
null | |
SelectedValues | IEnumerable | Gets or sets values of the items selected by user. |
attribute
bindable
|
null | |
SelectedValueTemplate | ITemplate | Gets or sets the template for each MultiSelect value. |
inner element
static value
|
null | |
TabIndex | Int32 | Gets or sets the order in which the control is reachable in sequential keyboard navigation. The default value is 0 which means the document order. |
attribute
static value
|
0 | |
UnselectIcon | IconBase |
inner element
static value
bindable
|
null | ||
Visible | Boolean | Gets or sets whether the control is visible. |
attribute
bindable
|
True |
Events
Name | Type | Description | |
---|---|---|---|
Changed | Command | Gets or sets the command that will be triggered when the text (or value) is changed. |