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 that 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 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.

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 is Plus icon.

  • CollapseIcon represents an icon of toggle button that collapse data. The default is Minus 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>
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
property icon AutoCheckChildren Boolean Gets or sets whether to automatically check all children when an item is checked. The default value is true.
attribute
inner element
static value
bindable
default
True
property icon 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
property icon CheckBoxMode CheckBoxMode Gets or sets a value indicating where to show checkboxes. They are not displayed by default.
attribute
inner element
static value
bindable
default
Hidden
property icon CollapseIcon IconBase
attribute
inner element
static value
bindable
default
null
property icon DataSource IEnumerable
attribute
inner element
static value
bindable
default
null
property icon EmptyDataTemplate ITemplate Gets or sets the template which will be displayed when the DataSource is empty.
attribute
inner element
static value
bindable
default
null
property icon ExpandIcon IconBase
attribute
inner element
static value
bindable
default
null
property icon ItemChildrenBinding IValueBinding<IEnumerable<Object>>
attribute
inner element
static value
bindable
default
null
property icon ItemHasChildrenBinding IValueBinding<Boolean?> Gets or sets the binding which retrieves a value indicating whether a DataSource item has any children.
attribute
inner element
static value
bindable
default
null
property icon ItemIsExpandedBinding IValueBinding<Boolean?>
attribute
inner element
static value
bindable
default
null
property icon ItemKeyBinding IValueBinding Gets or sets the binding which retrieves the unique key of a DataSource item.
attribute
inner element
static value
bindable
default
null
property icon ItemTemplate ITemplate Gets or sets the template for each TreeView item.
attribute
inner element
static value
bindable
default
null
property icon ItemValueBinding IValueBinding Gets or sets the binding which retrieves a value from a DataSource item. It retrieves the whole item by default.
attribute
inner element
static value
bindable
default
null
property icon SelectedValues IEnumerable Gets or sets values of items selected by user.
attribute
inner element
static value
bindable
default
null
property icon 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

Events

Name Type Description
event icon Changed Command Gets or sets the command that will be triggered when the selected values are changed.
event icon LoadChildren ICommandBinding<TreeView+LoadChildrenFunc> Gets or sets a function used to load descendants of an item being expanded.

HTML produced by the control