DropDownList

in namespace DotVVM.BusinessPack.Controls

Renders a DropDownList control similar to HTML <select> element.

Usage & Scenarios

The Business Pack DropDownList control lets the user select items from a drop down list. The items in a list are created from the DataSource collection and can have custom templates. This control does not support searching and the user is not able to add custom values in this control.

The Business Pack includes a similar control called ComboBox. It is a text field which suggests the user the items to select from. It can perform server search, use custom templates for the suggested items and let the user to add his own values which are not present in the DataSource collection.

Sample 1: Basic Usage

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

The SelectedValue property is bound to a property which contains the item from the DataSource collection which was selected in the control. The data-binding works in both ways, so you can either read, or modify the property in the viewmodel and the changes will get synchronized with the control.

page.dothtml
ViewModel.cs

<bp:DropDownList DataSource="{value: Countries}"
             SelectedValue="{value: SelectedCountry}"
             Placeholder="Please select Country" />

<p>Selected Country: {{value: SelectedCountry}}</p>

using System.Collections.Generic;
using DotVVM.Framework.ViewModel;

namespace DotvvmWeb.Views.Docs.Controls.businesspack.DropDownList.sample1
{
    public class ViewModel : DotvvmViewModelBase
    {
        public string SelectedCountry { get; set; }

        public List<string> Countries { get; set; } = new List<string> {
            "Czech Republic", "Slovakia", "United States"
        };
    }
}

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 list item.

The SelectedValue will still contain the object from the DataSource collection which is selected. To be able to identify these objects, you should 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.

The Placeholder property specifies the text which is displayed when no value is selected.

<bp:DropDownList DataSource="{value: Countries}"
             SelectedValue="{value: SelectedCountry}"
             ItemTextBinding="{value: Name}"
             ItemKeyBinding="{value: Id}"
             Placeholder="Please select Country" />

<p>Selected Country: {{value: SelectedCountry.Name}}</p>

using System.Collections.Generic;
using DotVVM.Framework.ViewModel;

namespace DotvvmWeb.Views.Docs.Controls.businesspack.DropDownList.sample2
{
    public class ViewModel : DotvvmViewModelBase
    {
        public Country SelectedCountry { 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" }
        };
    }
}

using System.Collections.Generic;

namespace DotvvmWeb.Views.Docs.Controls.businesspack.DropDownList.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 SelectedValue property contain only a value of a specific property from the DataSource object (like the Id property of the selected object), you may use the ItemValueBinding property.

The SelectedValue property will then contain only the value of the property 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 object in the SelectedValue property. If the ItemValueBinding is set and makes the SelectedValue property use a primitive type 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:DropDownList DataSource="{value: Countries}"
             SelectedValue="{value: SelectedCountryId}"
             ItemTextBinding="{value: Name}"
             ItemValueBinding="{value: Id}"
             Placeholder="Please select Country" />

<p>Selected Country ID: {{value: SelectedCountryId}}</p>

using System.Collections.Generic;
using DotVVM.Framework.ViewModel;

namespace DotvvmWeb.Views.Docs.Controls.businesspack.DropDownList.sample3
{
    public class ViewModel : DotvvmViewModelBase
    {
        public int? SelectedCountryId { 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" }
        };
    }
}

using System.Collections.Generic;

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

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

The ItemTemplate is by default used also for selected values. You can override it by setting the SelectedValueTemplate.

<bp:DropDownList DataSource="{value: Countries}"
             SelectedValue="{value: SelectedCountryId}"
             ItemValueBinding="{value: Id}"
             ItemTextBinding="{value: Name}"
             Placeholder="Please select Country">
    <SelectedValueTemplate>
        <span>{{value: Name}}</span>
    </SelectedValueTemplate>
    <ItemTemplate>
        <span>{{value: Id}}. {{value: Name}}</span>
    </ItemTemplate>
</bp:DropDownList>

using System.Collections.Generic;
using DotVVM.Framework.ViewModel;

namespace DotvvmWeb.Views.Docs.Controls.businesspack.DropDownList.sample4
{
    public class ViewModel : DotvvmViewModelBase
    {
        public int? SelectedCountryId { 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" }
        };
    }
}

using System.Collections.Generic;

namespace DotvvmWeb.Views.Docs.Controls.businesspack.DropDownList.sample4
{
    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 5: Changed Event

The Changed event specifies the command in the viewmodel that is triggered whenever the user changes the value in the control.

<bp:DropDownList DataSource="{value: Countries}"
             SelectedValue="{value: SelectedCountry}"
             ItemTextBinding="{value: Name}"
             ItemKeyBinding="{value: Id}"
             Placeholder="Please select Country"
             Changed="{command: CountryChanged()}" />

<bp:DropDownList DataSource="{value: Cities}"
             SelectedValue="{value: SelectedCity}"
             Placeholder="Please select City" />

<p>You've selected: {{value: SelectedCity}}, {{value: SelectedCountry.Name}}</p>

using System.Collections.Generic;
using DotVVM.Framework.ViewModel;

namespace DotvvmWeb.Views.Docs.Controls.businesspack.DropDownList.sample5
{
    public class ViewModel : DotvvmViewModelBase
    {
        public Country SelectedCountry { get; set; }
        public string SelectedCity { get; set; }

        public List<Country> Countries { get; set; } = new List<Country> {
            new Country { Id = 1, Name = "Czech Republic", Cities = new List<string> { "Praha", "Brno" } },
            new Country { Id = 2, Name = "Slovakia", Cities = new List<string> { "Bratislava", "Košice" } },
            new Country { Id = 3, Name = "United States", Cities = new List<string> { "Washington", "New York" } }
        };

        public List<string> Cities { get; set; } = new List<string>();

        public void CountryChanged()
        {
            SelectedCity = null;
            Cities = SelectedCountry.Cities;
        }
    }
}

using System.Collections.Generic;

namespace DotvvmWeb.Views.Docs.Controls.businesspack.DropDownList.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: 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:DropDownList DataSource="{value: Cities}"
             SelectedValue="{value: SelectedCity}"
             ItemTextBinding="{value: Name}"
             ItemKeyBinding="{value: Id}"
             Placeholder="Select city">
    <ItemTemplate>
        <span>{{value: Name}}, {{value: Country}}</span>
    </ItemTemplate>
</bp:DropDownList>

<p>Selected City: {{value: SelectedCity.Name}}, {{value: SelectedCity.Country}}</p>

using System.Collections.Generic;
using DotVVM.Framework.ViewModel;

namespace DotvvmWeb.Views.Docs.Controls.businesspack.DropDownList.sample6
{
    public class ViewModel : DotvvmViewModelBase
    {
        public List<City> Cities { get; set; } = new List<City> {
            new City { Id = 1, Name = "Praha", Country = "Czech Republic" },
            new City { Id = 2, Name = "Praha", Country = "Slovakia" },
            new City { Id = 3, Name = "Praha", Country = "Texas" }
        };

        public City SelectedCity { get; set; }
    }
}

namespace DotvvmWeb.Views.Docs.Controls.businesspack.DropDownList.sample6
{
    public class City
    {
        public int Id { get; set; }
        public string Name { get; set; }
        public string Country { get; set; }
    }
}

Sample 7: Customizing Icons

The icons used by the control can be customized using the following properties:

ToggleIconCssClass represents an icon that opens the popup with list of available items. The default value is fa fa-chevron-down (FontAwesome).
UnselectIconCssClass represents an icon that allows the user to deselect the item. The default value is fa fa-close (FontAwesome).

page.dothtml
ViewModel.cs

<bp:DropDownList DataSource="{value: Countries}"
                 SelectedValue="{value: SelectedCountry}"
                 ToggleIconCssClass="toggle"
                 UnselectIconCssClass="unselect"
                 Placeholder="Please select Country" />

using DotVVM.BusinessPack.Controls;
using DotVVM.Framework.ViewModel;

namespace DotvvmWeb.Views.Docs.Controls.businesspack.DropDownList.sample7
{
    public class ViewModel : DotvvmViewModelBase
    {
        public string SelectedCountry { get; set; }

        public List<string> Countries { get; set; } = new List<string> {
            "Czech Republic", "Slovakia", "United States"
        };
    }
}

Properties

Name	Type	Description	Notes	Default Value
AllowUnselect	Boolean	Gets or sets whether the selected value can be unselected. The default value is true.	attribute inner element static value bindable default	True
Attributes	Dictionary<String,Object>		attribute inner element static value bindable default	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 inner element static value bindable default	False
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	null
DataSource	Object	Gets or sets the source collection or a GridViewDataSet that contains data in the control.	attribute inner element static value bindable default	null
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	null
InnerText	String	Gets or sets the inner text of the HTML element.	attribute inner element static value bindable default	null
ItemEnabledBinding	IValueBinding	Gets or sets the binding indicating whether a DataSource item can be selected.	attribute inner element static value bindable default	null
ItemKeyBinding	IValueBinding	Gets or sets the binding which retrieves the unique key of a DataSource item.	attribute inner element static value bindable default	null
ItemTemplate	ITemplate	Gets or sets the template used to render each item in the DataSource.	attribute inner element static value bindable default	null
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	null
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	null
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	null
SelectedValue	Object	Gets or sets the value of the item selected by user.	attribute inner element static value bindable default	null
SelectedValueTemplate	ITemplate	Gets or sets the template for the item selected by user.	attribute inner element static value bindable default	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 inner element static value bindable default	0
ToggleIconCssClass	String	Gets or sets the CSS class for the icon displayed on the toggle button. The default value is FaChevronDown.	attribute inner element static value bindable default	fa fa-chevron-down
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.

DropDownList

Usage & Scenarios

Sample 1: Basic Usage

Sample 2: Working with Objects

Sample 3: Working with Objects 2

Sample 4: Templates

Sample 5: Changed Event

Sample 6: Item Keys

Sample 7: Customizing Icons

Properties

Events

HTML produced by the control

On this page

DropDownList

Usage & Scenarios

Sample 1: Basic Usage

Sample 2: Working with Objects

Sample 3: Working with Objects 2

Sample 4: Templates

Sample 5: Changed Event

Sample 6: Item Keys

Sample 7: Customizing Icons

Properties

Events

HTML produced by the control

On this page

Information about cookies