CMS Interfaces

Tree

Overview

Tree renders a hierarchy of nodes that can be expanded, collapsed and selected. The node list comes from one of two places: staticNodes carries it inline, fetchUrl names a route that returns it. A tree can also load a branch on demand, so a deep hierarchy is only fetched where the viewer opens it.

import { Tree, TreeSelectionBehavior } from "@antelopejs-private/cms/interfaces/cms-base/tree";

Tree, TreeProps, TreeNode, TreeSelectionBehavior and TreeEvents are also exported from the package root. The same TreeNode shape is used by the tree form input — see FormComponents.InputTree in Forms and DefaultDataTypes.TreeType in Data Types.

Declare a Tree

selectionBehavior is the only required option; supply either fetchUrl or staticNodes for the data.

import {
  PageController,
  pagesCategory,
  RegisterPage,
} from "@antelopejs-private/cms/interfaces/cms/page";
import { Tree, TreeSelectionBehavior } from "@antelopejs-private/cms/interfaces/cms-base/tree";
import { DefaultLayout } from "@antelopejs-private/cms/interfaces/cms-base/layouts";
import { Color, Size } from "@antelopejs-private/cms/interfaces/cms-base/types";

@RegisterPage()
export class ExplorerPage extends PageController(
  "explorer",
  { displayName: "Explorer", icon: "i-ph-tree-structure", category: pagesCategory },
  DefaultLayout(),
) {
  static files = Tree({
    title: "Project structure",
    description: "Navigate folders and files",
    fetchUrl: "/api/tree/data",
    selectionBehavior: TreeSelectionBehavior.toggle,
    color: Color.primary,
    size: Size.medium,
  });
}

The component's display name is the title, falling back to "Tree".

TreeProps

TreeProps extends BaseComponentProps.

Option	Type	Description
`selectionBehavior`	`TreeSelectionBehavior`	How clicking a node changes the selection. Required.
`title`	`string`	Header title, and the component display name.
`description`	`string`	Header description.
`color`	`Color`	Colour of a selected node.
`size`	`Size`	Control size.
`trailingIcon`	`string`	Icon of the expand/collapse toggle.
`expandedIcon`	`string`	Icon of an expanded node that has no icon of its own.
`collapsedIcon`	`string`	Icon of a collapsed node that has no icon of its own.
`multiple`	`boolean`	Allow more than one node to be selected.
`propagateSelect`	`boolean`	Selecting a node also selects its descendants.
`defaultExpanded`	`string[]`	Node values expanded initially.
`expanded`	`string[]`	Node values considered expanded.
`disabled`	`boolean`	Make the whole tree non-interactive.
`fetchUrl`	`string`	Route returning the root node array.
`fetchUrlMethod`	`HttpMethod`	Method for `fetchUrl` and for lazy-load requests.
`staticNodes`	`TreeNode[]`	Inline nodes, as an alternative to `fetchUrl`.
`lazyLoad`	`boolean`	Enable on-demand loading of branches.
`nodeToggleFunctionId`	`string`	Watch function invoked when a node is toggled.
`nodeSelectFunctionId`	`string`	Watch function invoked when a node is selected.

TreeSelectionBehavior is an enum with two members: toggle, where clicking a selected node deselects it, and replace, where the click replaces the current selection.

TreeNode

Field	Type	Description
`label`	`string`	Node text. Required.
`value`	`string`	Node identifier.
`icon`	`string`	Leading icon.
`children`	`TreeNode[]`	Child nodes.
`expandable`	`boolean`	Whether the node can be expanded.
`selectable`	`boolean`	Whether the node can be selected.
`hasChildren`	`boolean`	The node has children that are not in `children` yet.
`isLoading`	`boolean`	The node's children are being fetched.
`lazyLoadUrl`	`string`	Route the node's children are fetched from.
`customData`	`unknown`	Arbitrary payload carried with the node.
`hierarchicalPath`	`string`	Path of the node within the hierarchy.

Nodes are plain data, so a route that feeds a tree returns the same shape:

import { Controller, Get } from "@antelopejs/interface-api";
import type { TreeNode } from "@antelopejs-private/cms/interfaces/cms-base/tree";

export class TreeAPIController extends Controller("/api/tree") {
  @Get("data")
  getTreeData(): TreeNode[] {
    return [
      {
        value: "documents",
        label: "Documents",
        icon: "i-ph-folder",
        expandable: true,
        selectable: true,
        children: [
          { value: "proposal", label: "Proposal.pdf", icon: "i-ph-file-pdf", selectable: true },
        ],
      },
    ];
  }
}

Lazy Loading

A lazy branch is a node that declares it has children without carrying them: set hasChildren: true, leave children empty, and point lazyLoadUrl at the route that returns them. The tree only follows those pointers when the builder was given lazyLoad: true.

import { Tree, TreeSelectionBehavior } from "@antelopejs-private/cms/interfaces/cms-base/tree";

static files = Tree({
  fetchUrl: "/api/tree/data",
  lazyLoad: true,
  selectionBehavior: TreeSelectionBehavior.replace,
});

import { Controller, Get } from "@antelopejs/interface-api";
import type { TreeNode } from "@antelopejs-private/cms/interfaces/cms-base/tree";

export class TreeAPIController extends Controller("/api/tree") {
  @Get("data")
  getTreeData(): TreeNode[] {
    return [
      {
        value: "reports",
        label: "Reports",
        icon: "i-ph-folder",
        expandable: true,
        hasChildren: true,
        lazyLoadUrl: "/api/tree/reports",
        children: [],
      },
    ];
  }

  @Get("reports")
  getReports(): TreeNode[] {
    return [{ value: "q1", label: "Q1.xlsx", icon: "i-ph-file-xls", selectable: true }];
  }
}

A branch returned from lazyLoadUrl can itself contain further lazy branches, so a hierarchy of any depth is fetched one level at a time. isLoading marks a node whose children are in flight.

Events

Namespace member	Value
`TreeEvents.NODE_SELECT`	`"CmsComponent.Tree.NodeSelect"`
`TreeEvents.NODE_TOGGLE`	`"CmsComponent.Tree.NodeToggle"`
`TreeEvents.NODE_EXPAND`	`"CmsComponent.Tree.NodeExpand"`
`TreeEvents.NODE_COLLAPSE`	`"CmsComponent.Tree.NodeCollapse"`
`TreeEvents.LAZY_LOAD`	`"CmsComponent.Tree.LazyLoad"`
`TreeEvents.LAZY_LOAD_SUCCESS`	`"CmsComponent.Tree.LazyLoadSuccess"`

These are the event names to pass to .watch() and .watchOn(). nodeToggleFunctionId and nodeSelectFunctionId are a separate mechanism: rather than binding an event to a function through a watch action, they name the function to invoke directly in the tree's own props.

Next Steps

Data Types - The type behind every form field and table column.

Layout and Containers

Data Types