TreeList Editors Module Overview
- 9 minutes to read
The TreeList Editors module displays List View information in a tree-like structure (a TreeList control). Tree List controls allow you to sort data values against multiple columns, calculate summary values, display node preview and node images, customize column layout at runtime, format column and summary values, and use advanced editors to display and edit cell values.
This topic explains how to use the TreeList Editors module.
#TreeList Module Components
#Modules and Integrated DevExpress Controls
Platform | Module | Editor | Control | Demo / Overview |
---|---|---|---|---|
ASP. |
DevExpress. |
Dx |
Blazor. |
Dx |
Windows Forms | Tree |
Win. |
Xtra |
Tree List Overview |
ASP. |
Tree |
Web. |
ASPx |
ASPx |
Platform-agnostic | Tree |
XAF targets the List Editors mentioned in the table for objects that implement the ITreeNode interface from the Business Class Library.
In Windows Forms applications, the TreeList Editors module supports a categorized tree view where tree nodes are categories with related items. For this purpose, XAF supplies the CategorizedListEditor for category items which are objects that implement the ICategorizedItem interface.
ASP.NET Core Blazor DxTreeListEditor supports flat data sources and allows to display objects in a hierarchical structure with Key Field - Parent Key Field relationships.
#Add the TreeList Editors Module to Your Application
#Solution Wizard
You can add the TreeList Editors module to your application when you use the Solution Wizard to create a new XAF solution. Select the module in the Choose Extra Modules step.
#.NET
#Windows Forms
In .NET applications, you can call the AddTreeListEditors(IModuleBuilder<IWinApplicationBuilder>, Action<TreeListEditorOptions>) method in your WinForms application builder.
#ASP.NET Core Blazor
DxTreeListEditor
ships with the base DevExpress.ExpressApp.Blazor
module. You do not need to add a module to an existing XAF ASP.NET Core Blazor application to start using it.
#.NET Framework
#Windows Forms
- Invoke the Application Designer and drag the TreeList Editors module from the Toolbox to the Modules panel.
- Rebuild your solution.
#ASP.NET Web Forms
- Invoke the Application Designer and drag the TreeList Editors module from the Toolbox to the Modules panel.
- Rebuild your solution.
#Organize a Tree
#Tree-like Data Structure with ITreeNode Objects
To display data in a tree-like structure in the UI, implement the ITreeNode
interface in the required business classes.
public interface ITreeNode {
string Name { get; }
ITreeNode Parent { get; }
IBindingList Children { get; }
}
The ITreeNode.Name property specifies a tree node caption. The ITreeNode.Parent property refers to the parent object (tree node). If this property is set to null
, the object is the root object (root tree node). The ITreeNode.Children property is a collection of child objects (child tree nodes).
For an example of the ITreeNode
interface implementation, refer to the following topic: Display a Tree List using the ITreeNode Interface.
The Business Class Library supplies the HCategory
class that implements the ITreeNode
interface. You can use it as is, or inherit from it, instead of implementing the ITreeNode
interface from scratch. For details, refer to the Display a Tree List using the HCategory Class topic. To see the HCategory
class implementation, refer to the following folders:
- %PROGRAMFILES%\DevExpress 24.2\Components\Sources\DevExpress.Persistent\DevExpress.Persistent.BaseImpl.Xpo
- %PROGRAMFILES%\DevExpress 24.2\Components\Sources\DevExpress.Persistent\DevExpress.Persistent.BaseImpl.EFCore
You can find the HCategory.cs file in these folders.
Note
The Tree
and Categorized
cannot properly display a tree if the hierarchy contains objects of a type that is not assignable from the List View object type (see Type.
When you add the TreeList Editors module to the application, XAF uses Tree List Editors to display all List Views associated with ITreeNode
objects.The editors build root nodes from a List View’s objects where ITreeNode.Parent property is set to null
. When you expand a node, the editor looks for the List View’s objects contained in the node’s ITreeNode.Children collection. It displays the found objects as child nodes. The following images show XAF Tree List editors:
#DxTreeListEditor
#TreeListEditor
#ASPxTreeListEditor
#Flat Data Structure
With XAF ASP.NET Core Blazor DxTreeListEditor you can use a data source with a flat data structure (a non-hierarchical list of objects without children collections). To build a hierarchical structure of Tree List nodes, specify additional properties that define node relationships:
- KeyFieldName
- A field name that contains node’s unique identifier.
- ParentKeyFieldName
- A field name that contains a parent node identifier.
In the Client data access mode, Tree List loads all objects. To load only root objects, use Queryable data access mode. XAF will load child nodes only when you expand the parent node for the first time. To use this mode, specify an additional model property:
- HasChildrenFieldName
- A field name that returns whether a node has children. The component uses this property to determine which nodes require expand buttons.
Note
If you make this property persistent, only visible nodes are queried from the database initially. If this property is calculated, XAF loads the next level to allow Tree List to evaluate whether nodes have children or not.
#Support Node Images
To support node images, implement the ITreeNodeImageProvider interface in a class that implements the ITreeNode
interface. As a result, each node should be accompanied by an image.
Note
XAF ASP.
The ITreeNodeImageProvider
declares a single member - the ITreeNodeImageProvider.GetImage method. In this method, return the image corresponding to a tree node.
To see an example of the ITreeNodeImageProvider
interface implementation, refer to the following topic: Node Images in a Tree List.
#Implement the Category-Items Scenario (Windows Forms)
In most scenarios, a tree node is a category that can have related items. The following business model can be implemented in terms of the Category-Items scenario. The root category is represented by objects of the ProjectGroup class (“.Net”, “VCL”, …). This category’s child category is represented by Project type objects (“XtraGrid”, “XtraEditors”, “QuantumGrid”, …). There may be more levels in this hierarchy. For example, each Project can contain a list of its own Areas: “Columns”, “RepositoryItems”, “MaskEdit”, etc. These objects should implement the ITreeNode
interface to be displayed as a tree. At the same time, there can be Issue
objects related to specific categories (to a ProjectGroup, Project or ProjectArea). Each category is related to Issue
objects by the One-to-Many relationship. When displaying the Issue
List View, you may need to see a tree of categories and a list of Issue
objects related to the currently selected category, as shown in the image below.
This image demonstrates how the Windows Forms CategorizedListEditor
displays the Issue
List View. The TreeList Editors module supplies this List Editor for the scenarios, as defined above. It displays List Views associated with objects of the ICategorizedItem
type, so the Issue
class from the example above should implement the ICategorizedItem
interface.
public interface ICategorizedItem {
ITreeNode Category { get; set; }
}
For more information, refer to the following topic: Categorized List.
It is not necessary to display Issue List Views via the CategorizedListEditor
. For example, you can use an ordinary GridListEditor for nested Issue List Views:
- Invoke the Model Editor for the Windows Forms application project.
Right-click the Views node and select Add… | ListView in the invoked context menu.
For the newly created node, specify the
Id
property and set theModelClass
property to the type that implements theICategorizedItem
interface (for example,Issue
).- Right-click the new node and choose Generate content.
- Navigate to the Detail View node that defines the Detail View with a collection of
ICategorizedItem
objects (for example,ProjectArea
). Locate the child View Item node that corresponds to this collection. Set its
View
property to the node that you created in the previous steps.
#Access a Control in Tree List Editors
You can customize the TreeListEditor
and CategorizedListEditor
List Editors or the TreeList
control exposed via the List Editor’s ListEditor.Control property.
To access a List Editor in code, create a View Controller and handle its ViewController.ViewControlsCreated event or override the OnViewControlsCreated
protected method.
#Access DxTreeListEditor (ASP.NET Core Blazor)
using DevExpress.ExpressApp;
using DevExpress.ExpressApp.Blazor.Editors;
namespace YourSolutionName.Blazor.Server.Controllers;
public class ColumnResizeModeViewController : ViewController<ListView> {
protected override void OnViewControlsCreated() {
base.OnViewControlsCreated();
if (View.Editor is DxTreeListEditor treeListEditor) {
treeListEditor.TreeListModel.ColumnResizeMode =
DevExpress.Blazor.TreeListColumnResizeMode.ColumnsContainer;
}
}
}
#Access TreeListEditor (Windows Forms)
using DevExpress.ExpressApp.TreeListEditors.Win;
using DevExpress.XtraTreeList;
using DevExpress.Persistent.Base.General;
namespace YourSolutionName.Win.Controllers;
public partial class TreeListController : ViewController {
public TreeListController() {
TargetViewType = ViewType.ListView;
TargetObjectType = typeof(ITreeNode);
}
protected override void OnViewControlsCreated() {
base.OnViewControlsCreated();
ListView view = (ListView)View;
TreeListEditor listEditor = (TreeListEditor)view.Editor;
TreeList treeList = listEditor.TreeList;
// Access the TreeList object here.
}
}
#Access CategorizedListEditor (Windows Forms)
using DevExpress.ExpressApp.TreeListEditors.Win;
using DevExpress.XtraTreeList;
using DevExpress.Persistent.Base.General;
namespace YourSolutionName.Win.Controllers;
public partial class CategorizedListController : ViewController {
public CategorizedListController() {
TargetViewType = ViewType.ListView;
TargetObjectType = typeof(ICategorizedItem);
}
protected override void OnViewControlsCreated() {
ListView view = (ListView)View;
CategorizedListEditor listEditor = (CategorizedListEditor)view.Editor;
ListView categoriesListView = listEditor.CategoriesListView;
TreeListEditor treeListEditor = (TreeListEditor)categoriesListView.Editor;
TreeList treeList = treeListEditor.TreeList;
// Implement the required changes here.
}
}
#Access ASPxTreeListEditor (ASP.NET Web Forms)
XAF ASPxTreeList
integration code is not designed to immediately show the new value of a Boolean property if it was changed on the server side. For example, XAF does not display a new value immediately if you use an Action to change it. To display the new value, you need to refresh the page. To avoid this restriction, use the following code.
using DevExpress.Web.ASPxTreeList;
using DevExpress.ExpressApp;
using DevExpress.ExpressApp.TreeListEditors.Web;
// ...
public class RemoveTreeListDataCellTemplateController : ViewController {
public RemoveTreeListDataCellTemplateController() : base() { }
protected override void OnActivated() {
base.OnActivated();
ListView listView = View as ListView;
if (listView != null && listView.Editor != null) {
listView.Editor.ControlsCreated += Editor_ControlsCreated;
}
}
void Editor_ControlsCreated(object sender, EventArgs e) {
ASPxTreeListEditor treeListEditor = sender as ASPxTreeListEditor;
if (treeListEditor != null) {
TreeListDataColumn column =
treeListEditor.TreeList.Columns["BoolProperty"] as TreeListDataColumn;
if (column != null) {
column.DataCellTemplate = null;
}
}
}
}
This way the ASPxTreeList
control uses the TreeListDataColumn to show Boolean values. For more information, refer to the following topic: TreeListDataColumn.DataCellTemplate.
Since Controllers are implemented in modules, add a reference to the TreeList Editors module to the required module. Set a reference to the DevExpress.XtraTreeList.v24.2.dll assembly as well.
#Filtering a Tree List
List View Tree List controls - DxTreeList, TreeList, and ASPxTreeList - provide advanced filtering features. For example, the controls support filtering operators and can filter root and child objects. Follow the links below for more information:
The following resource uses these features in XAF applications:
- The List Editors | Tree | Filtering section in the Feature Center demo (%PUBLIC%\Documents\DevExpress Demos 24.2\Components\XAF\FeatureCenter.NETFramework.XPO) or the Feature Center demo online