TreeView
in namespace DotVVM.BusinessPack.Controls
Renders a TreeView control displaying items in tree-like structure.
Usage & Scenarios
Renders a hierarchical structure of items and allows to select one or more of them.
Sample 1: Basic Usage
The DataSource
property specifies the collection of root items.
The SelectedValues
property is bound to a collection with items that are selected.
The ItemKeyBinding
defines a property which uniquely identifies the item and allows the DataSource
and SelectedValues
items to be compared.
The ItemHasChildrenBinding
property defines an expression which determines whether the particular item has children.
The ItemChildrenBinding
property specifies the collection of child items for a particular item. The children must be of the same type as the root items.
The contents inside the control are treated as the ItemTemplate
which specifies a template for each item in the tree.
<bp:TreeView DataSource="{value: Files}"
SelectedValues="{value: SelectedFiles}"
ItemKeyBinding="{value: Name}"
ItemHasChildrenBinding="{value: HasItems}"
ItemChildrenBinding="{value: Items}">
<p>{{value: Name}}</p>
</bp:TreeView>
using System.Collections.Generic;
using DotVVM.Framework.ViewModel;
namespace DotvvmWeb.Views.Docs.Controls.businesspack.TreeView.sample1
{
public class ViewModel : DotvvmViewModelBase
{
public List<TreeItem> SelectedFiles { get; set; } = new List<TreeItem>();
public List<TreeItem> Files { get; set; } = new List<TreeItem> {
new TreeItem {
Name = "Documents",
Items = new List<TreeItem> {
new TreeItem {
Name = "Invoices",
Items = new List<TreeItem> {
new TreeItem { Name = "Invoice.pdf" }
}
},
new TreeItem { Name = "CV.pdf" }
}
},
new TreeItem {
Name = "Pictures",
Items = new List<TreeItem> {
new TreeItem { Name = "dog.jpg" },
new TreeItem { Name = "cat.jpg" },
new TreeItem { Name = "horse.png" }
}
},
new TreeItem { Name = "My Notes.txt" }
};
}
}
using System.Collections.Generic;
namespace DotvvmWeb.Views.Docs.Controls.businesspack.TreeView.sample1
{
public class TreeItem
{
public string Name { get; set; }
public bool HasItems => Items?.Count > 0;
public List<TreeItem> Items { get; set; } = new List<TreeItem>();
}
}
Sample 2: Tree Item CheckBoxes
Using the CheckBoxMode
property, you can display the checkboxes. The property has the following values:
Hidden
means that no checkboxes are displayed.VisibleOnLeafs
means that the checkboxes are displayed for the items which don't have any children.Visible
means tha the checkboxes are displayed for all items in the tree.
By default, the control checks also the descendant items when an item is checked. The AutoCheckChildren
property can be used to disable this feature.
<bp:TreeView DataSource="{value: Files}"
SelectedValues="{value: SelectedFiles}"
CheckBoxMode="VisibleOnLeafs"
AutoCheckChildren="false"
ItemHasChildrenBinding="{value: HasItems}"
ItemChildrenBinding="{value: Items}"
ItemKeyBinding="{value: Name}">
<p>{{value: Name}}</p>
</bp:TreeView>
using System.Collections.Generic;
using DotVVM.Framework.ViewModel;
namespace DotvvmWeb.Views.Docs.Controls.businesspack.TreeView.sample2
{
public class ViewModel : DotvvmViewModelBase
{
public List<TreeItem> SelectedFiles { get; set; } = new List<TreeItem>();
public List<TreeItem> Files { get; set; } = new List<TreeItem> {
new TreeItem {
Name = "Documents",
Items = new List<TreeItem> {
new TreeItem {
Name = "Invoices",
Items = new List<TreeItem> {
new TreeItem { Name = "Invoice.pdf" }
}
},
new TreeItem { Name = "CV.pdf" }
}
},
new TreeItem {
Name = "Pictures",
Items = new List<TreeItem> {
new TreeItem { Name = "dog.jpg" },
new TreeItem { Name = "cat.jpg" },
new TreeItem { Name = "horse.png" }
}
},
new TreeItem { Name = "My Notes.txt" }
};
}
}
using System.Collections.Generic;
namespace DotvvmWeb.Views.Docs.Controls.businesspack.TreeView.sample2
{
public class TreeItem
{
public string Name { get; set; }
public bool HasItems => Items?.Count > 0;
public List<TreeItem> Items { get; set; } = new List<TreeItem>();
}
}
Sample 3: Changed Event
The Changed
property specifies a command in the viewmodel which is triggered whenever the selection is changed.
<bp:TreeView DataSource="{value: Files}"
SelectedValues="{value: SelectedFiles}"
CheckBoxMode="VisibleOnLeafs"
AutoCheckChildren="false"
ItemHasChildrenBinding="{value: HasItems}"
ItemChildrenBinding="{value: Items}"
Changed="{command: SelectionChanged()}"
ItemKeyBinding="{value: Name}">
<p>{{value: Name}}</p>
</bp:TreeView>
<p>You've selected: {{value: Summary}}</p>
using System.Collections.Generic;
using System.Linq;
using DotVVM.Framework.ViewModel;
namespace DotvvmWeb.Views.Docs.Controls.businesspack.TreeView.sample3
{
public class ViewModel : DotvvmViewModelBase
{
public string Summary { get; set; }
public List<TreeItem> SelectedFiles { get; set; } = new List<TreeItem>();
public List<TreeItem> Files { get; set; } = new List<TreeItem> {
new TreeItem {
Name = "Documents",
Items = new List<TreeItem> {
new TreeItem {
Name = "Invoices",
Items = new List<TreeItem> {
new TreeItem { Name = "Invoice.pdf" }
}
},
new TreeItem { Name = "CV.pdf" }
}
},
new TreeItem {
Name = "Pictures",
Items = new List<TreeItem> {
new TreeItem { Name = "dog.jpg" },
new TreeItem { Name = "cat.jpg" },
new TreeItem { Name = "horse.png" }
}
},
new TreeItem { Name = "My Notes.txt" }
};
public void SelectionChanged()
{
Summary = string.Join(",", SelectedFiles.Select(f => "[" + f.Name + "]"));
}
}
}
using System.Collections.Generic;
namespace DotvvmWeb.Views.Docs.Controls.businesspack.TreeView.sample3
{
public class TreeItem
{
public string Name { get; set; }
public bool HasItems => Items?.Count > 0;
public List<TreeItem> Items { get; set; } = new List<TreeItem>();
}
}
Sample 4: Working With Objects
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 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.
Use the ItemIsExpandedBinding
binding to control whether nodes are collapsed or expanded. It may be useful in combination with the LoadChildren
command.
<bp:TreeView DataSource="{value: Files}"
SelectedValues="{value: SelectedFileNames}"
ItemValueBinding="{value: Name}"
CheckBoxMode="VisibleOnLeafs"
AutoCheckChildren="false"
ItemIsExpandedBinding="{value: IsExpanded}"
ItemHasChildrenBinding="{value: HasItems}"
ItemChildrenBinding="{value: Items}"
ItemKeyBinding="{value: Name}">
<p>{{value: Name}}</p>
</bp:TreeView>
using System.Collections.Generic;
using DotVVM.Framework.ViewModel;
namespace DotvvmWeb.Views.Docs.Controls.businesspack.TreeView.sample4
{
public class ViewModel : DotvvmViewModelBase
{
public List<string> SelectedFileNames { get; set; } = new List<string>();
public List<TreeItem> Files { get; set; } = new List<TreeItem> {
new TreeItem {
Name = "Documents",
IsExpanded = true,
Items = new List<TreeItem> {
new TreeItem {
Name = "Invoices",
Items = new List<TreeItem> {
new TreeItem { Name = "Invoice.pdf" }
}
},
new TreeItem { Name = "CV.pdf" }
}
},
new TreeItem {
Name = "Pictures",
Items = new List<TreeItem> {
new TreeItem { Name = "dog.jpg" },
new TreeItem { Name = "cat.jpg" },
new TreeItem { Name = "horse.png" }
}
},
new TreeItem { Name = "My Notes.txt" }
};
}
}
using System.Collections.Generic;
namespace DotvvmWeb.Views.Docs.Controls.businesspack.TreeView.sample4
{
public class TreeItem
{
public string Name { get; set; }
public bool HasItems => Items?.Count > 0;
public List<TreeItem> Items { get; set; } = new List<TreeItem>();
public bool IsExpanded { get; set; }
}
}
Sample 5: Icons
The icons used by the control can be customized using the following inner elements:
ExpandIcon
represents an icon of toggle button that expand data. The default isPlus
icon.CollapseIcon
represents an icon of toggle button that collapse data. The default isMinus
icon.
See the Icon documentation to find about using other icon packs.
<bp:TreeView DataSource="{value: Files}"
SelectedValues="{value: SelectedFiles}"
ItemKeyBinding="{value: Name}"
ItemHasChildrenBinding="{value: HasItems}"
ItemChildrenBinding="{value: Items}">
<ExpandIcon>
<bp:Icon Icon="ChevronDown"></bp:Icon>
</ExpandIcon>
<CollapseIcon>
<bp:Icon Icon="ChevronUp"></bp:Icon>
</CollapseIcon>
<span>{{value: Name}}</span>
</bp:TreeView>CS
using System.Collections.Generic;
using DotVVM.Framework.ViewModel;
namespace DotvvmWeb.Views.Docs.Controls.businesspack.TreeView.sample5
{
public class ViewModel : DotvvmViewModelBase
{
public List<TreeItem> SelectedFiles { get; set; } = new List<TreeItem>();
public List<TreeItem> Files { get; set; } = new List<TreeItem> {
new TreeItem {
Name = "Documents",
Items = new List<TreeItem> {
new TreeItem {
Name = "Invoices",
Items = new List<TreeItem> {
new TreeItem { Name = "Invoice.pdf" }
}
},
new TreeItem { Name = "CV.pdf" }
}
},
new TreeItem {
Name = "Pictures",
Items = new List<TreeItem> {
new TreeItem { Name = "dog.jpg" },
new TreeItem { Name = "cat.jpg" },
new TreeItem { Name = "horse.png" }
}
},
new TreeItem { Name = "My Notes.txt" }
};
}
}
using System.Collections.Generic;
namespace DotvvmWeb.Views.Docs.Controls.businesspack.TreeView.sample5
{
public class TreeItem
{
public string Name { get; set; }
public bool HasItems => Items?.Count > 0;
public List<TreeItem> Items { get; set; } = new List<TreeItem>();
}
}
Sample 6: Lazy loading of children
The LoadChildren
command is there to dynamically load children of items being expanded. It receives an item and should return a collection of it's descendants. You can return as many child levels as you want.
<bp:TreeView DataSource="{value: Files}"
SelectedValues="{value: SelectedFiles}"
ItemKeyBinding="{value: Name}"
ItemHasChildrenBinding="{value: HasItems}"
ItemChildrenBinding="{value: Items}"
LoadChildren="{staticCommand: _parent.LoadChildren(_this)}">
<span>{{value: Name}}</span>
</bp:TreeView>
using System.Collections.Generic;
using DotVVM.Framework.ViewModel;
namespace DotvvmWeb.Views.Docs.Controls.businesspack.TreeView.sample6
{
public class ViewModel : DotvvmViewModelBase
{
public List<TreeItem> SelectedFiles { get; set; } = new List<TreeItem>();
public List<TreeItem> Files { get; set; } = new List<TreeItem> {
new TreeItem {
Name = "Documents",
HasItems = true // LoadChildren is called when HasItems is true and Items are empty
}
};
[AllowStaticCommand]
public IEnumerable<TreeItem> LoadChildren(TreeItem parent)
{
if (parent.Name == "Documents")
{
yield return new TreeItem {
Name = "Invoices",
HasItems = true,
Items = new List<TreeItem> {
new TreeItem { Name = "Invoice.pdf" }
}
};
}
}
}
}
using System.Collections.Generic;
namespace DotvvmWeb.Views.Docs.Controls.businesspack.TreeView.sample6
{
public class TreeItem
{
public string Name { get; set; }
public bool HasItems { get; set; }
public List<TreeItem> Items { get; set; } = new List<TreeItem>();
}
}
Properties
Name | Type | Description | Notes | Default Value | |
---|---|---|---|---|---|
Attributes | Dictionary<String,Object> |
attribute
static value
|
null | ||
AutoCheckChildren | Boolean | Gets or sets whether to automatically check all children when an item is checked. The default value is true. |
attribute
static value
bindable
|
True | |
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 | |
CheckBoxMode | CheckBoxMode | Gets or sets a value indicating where to show checkboxes. They are not displayed by default. |
attribute
static value
bindable
|
Hidden | |
ClientIDMode | ClientIDMode | Gets or sets the client ID generation algorithm. |
attribute
static value
|
Static | |
CollapseIcon | IconBase |
inner element
static value
bindable
|
null | ||
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 | |
ExpandIcon | IconBase |
inner element
static value
bindable
|
null | ||
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 | |
ItemChildrenBinding | IValueBinding<IEnumerable<Object>> |
attribute
static value
bindable
|
null | ||
ItemHasChildrenBinding | IValueBinding<Boolean?> | Gets or sets the binding which retrieves a value indicating whether a DataSource item has any children. |
attribute
static value
bindable
|
null | |
ItemIsExpandedBinding | IValueBinding<Boolean?> |
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 for each TreeView item. |
inner element
static value
default
|
null | |
ItemValueBinding | IValueBinding | Gets or sets the binding which retrieves a value from a DataSource item. It retrieves the whole item by default. |
attribute
static value
bindable
|
null | |
SelectedValues | IEnumerable | Gets or sets values of items selected by user. |
attribute
bindable
|
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 | |
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 selected values are changed. | |
LoadChildren | ICommandBinding<TreeView+LoadChildrenFunc> | Gets or sets a function used to load descendants of an item being expanded. |