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 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 ItemIsExpanded 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 ExpandIconCssClass and CollapseIconCssClass properties can be used to customize the icons used by the control. The default values are fa fa-caret-right and fa fa-caret-up respectively (FontAwesome).

<bp:TreeView DataSource="{value: Files}"
             ExpandIconCssClass="{resource: IconType.FaCaretRight}"
             CollapseIconCssClass="{resource: IconType.FaCaretUp}"
             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.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: _root.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 item)
        {
            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 Attributes Dictionary<String,Object>
attribute
inner element
static value
bindable
default
null
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 ClientIDMode ClientIDMode Gets or sets the client ID generation algorithm.
attribute
inner element
static value
bindable
default
Static
property icon CollapseIconCssClass String Gets or sets the CSS class for the icon displayed on the collapse button. The default value is FaMinusSquareO.
attribute
inner element
static value
bindable
default
fa fa-minus-square-o
property icon 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
property icon 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
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 ExpandIconCssClass String Gets or sets the CSS class for the icon displayed on the expand button. The default value is FaPlusSquareO.
attribute
inner element
static value
bindable
default
fa fa-plus-square-o
property icon ID String Gets or sets the unique control ID.
attribute
inner element
static value
bindable
default
null
property icon InnerText String Gets or sets the inner text of the HTML element.
attribute
inner element
static value
bindable
default
null
property icon ItemChildrenBinding IValueBinding Gets or sets the binding which retrieves children of a DataSource item.
attribute
inner element
static value
bindable
default
null
property icon ItemHasChildrenBinding IValueBinding 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 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 LoadChildren StaticCommandBindingExpression Gets or sets a function used to load descendants of an item being expanded.
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
property icon Visible Boolean Gets or sets whether the control is visible.
attribute
inner element
static value
bindable
default
True

Events

Name Type Description
event icon Changed Command Gets or sets the command that will be triggered when the selected values are changed.

HTML produced by the control