(this page was created automatically. In case of formatting issues, please visit the official Wiki Page)

Tree View

The Dynamic Tree View component is a hierarchical data display component that presents information in a collapsible tree structure. It allows users to visualize and navigate through nested data with parent-child relationships. This component is ideal for representing organizational structures, file systems, category hierarchies, or any nested data that has a clear parent-child relationship.

Properties

General Properties

  • displayName - Sets the display name of the component shown in the structure panel. For example, "Category Tree" allows for easy identification of the component's purpose in the component structure. This name is used to reference the component in the editor and does not affect the front-end display.

Visual Properties

  • displayExpression - Defines the field from your data that will be displayed as text for each tree node. For example, setting it to "name" will display the value of the "name" field for each item in your data. This is essential for making your tree nodes meaningful and readable to users.

  • keyExpression - Specifies the field from your data that uniquely identifies each node. For example, setting it to "id" means the component will use the "id" field as the unique identifier for each tree node. This is crucial for the component to track selection, expansion states, and parent-child relationships.

  • childrenExpression - Defines the field that contains child items for each node. For example, setting it to "children" means the component will look for child nodes in a field called "children" in your data objects. If your nested data uses a different field name for child items, you would specify that here.

  • selectionMode - Determines how users can select nodes in the tree. Options include "single" (only one node can be selected at a time), "multiple" (multiple nodes can be selected simultaneously), or null (no selection allowed). For example, setting to "multiple" allows users to select several categories in a product catalog tree.

  • showCheckBoxesMode - Controls how checkboxes are displayed in the tree view. Options include "none" (no checkboxes), "normal" (checkboxes shown for all nodes), or "selectAll" (includes a select all checkbox). For example, using "selectAll" is helpful when users need to select multiple items in a permissions tree.

  • selectNodesRecursive - Determines if selecting a parent node automatically selects all its child nodes. When set to true, clicking a parent node selects all its children recursively, which is useful for operations that apply to entire branches of the tree.

  • selectByClick - Enables or disables node selection when clicking on a node. When set to true, users can select a node by clicking anywhere on it; when false, they must use checkboxes (if enabled) to select nodes. This provides flexibility in how users interact with the tree.

  • paddingClass - Configures the padding around the component using CSS classes. For example, "p-4" adds medium padding on all sides of the tree view, while "px-3 py-2" adds different horizontal and vertical padding. Proper padding ensures the tree view has adequate spacing within its container.

Datasource Properties

  • dataSourceId - Specifies the data source ID for retrieving tree data. For example, "api/categories" connects the tree view to a categories API endpoint. This property is essential as it defines where the component will fetch its hierarchical data from.

  • getEntityCollectionHttpRequestParametersMap - Configures HTTP parameters for data fetching. This object maps additional parameters needed for the data request, such as filters or sorting options. For example, {"headers": {"Content-Type": "application/json"}, "pathParams": {"tenantId": "{{tenantId}}"}} allows you to pass dynamic path parameters to the API.

Event Actions Properties

  • events - Configures the events that the component can trigger and respond to:

  • ONTREEITEM_CLICK: Triggered when a tree node is clicked. Can be used to navigate to detail pages or load related content based on the selected node.

  • ON_INIT: Triggered when the component is initialized. Can be used to perform setup operations like setting initial states or loading additional data.

  • ON_DESTROY: Triggered when the component is removed from the DOM. Useful for cleanup operations and releasing resources.

    For example, you could configure an ONTREEITEM_CLICK event to update a detail panel with information about the selected category or navigate to a filtered view of products in that category.

Authorization Properties

  • visibilityPolicySetId - Determines the visibility of the component based on specified policy sets. For example, setting to "categoryAdminPolicy" restricts the tree view to users with category management privileges. This enables role-based access control for the component, ensuring only authorized users can see and interact with certain hierarchical data.

Visibility Properties

  • displayConditions - Defines conditions for displaying the component based on context values. For example, { key: "showCategoryTree", operator: "equals", value: "true" } would only show the tree view when the context contains a "showCategoryTree" property set to "true". This allows the tree view to be shown or hidden dynamically depending on the state of the application.

Testing Hooks Properties

  • id - Specifies a unique identifier for the component used for programmatic access. For example, "productCategoryTree" enables targeted manipulation of this specific component in scripts or for automated testing.

  • dataTestId - Sets the testing hook ID for automated testing. For example, setting it to "product-category-tree" allows test scripts to reliably locate this component during test execution.

  • enableAsHotspot - Enables the component as a guided tour hotspot. When set to true, this component can be highlighted in guided tours to help users understand its navigation functionality.

  • guidedTourHotSpotTitle - Sets the title for the guided tour hotspot with support for multiple languages. For example, {"en-US": "Category Navigation", "fr-FR": "Navigation par Catégorie"} ensures proper localization of the hotspot title.

  • guidedTourHotSpotDescription - Sets the description for the guided tour hotspot with language support. For example, {"en-US": "Use this tree to navigate between different product categories", "fr-FR": "Utilisez cet arborescence pour naviguer entre différentes catégories de produits"} provides localized guidance about how to use the component.

Technical Implementation Notes

When implementing the Tree View component:

  1. The data structure should have a clear parent-child relationship, with each node containing a unique identifier and a field that references its children.
  2. The component automatically handles the expansion and collapse of tree nodes.
  3. When a node is selected, the ONTREEITEM_CLICK event is triggered, passing the selected node's data to any configured actions.
  4. The component supports both flat and hierarchical data structures, as long as the appropriate expressions are set to map the relationships.
  5. For large datasets, consider implementing server-side filtering or pagination through the request parameters.

Data Format

The tree view component expects a hierarchical data structure or a flat structure that can be converted to a hierarchy. Here's an example of a hierarchical data format:

[
  {
    "id": "1",
    "name": "Electronics",
    "children": [
      {
        "id": "1-1",
        "name": "Smartphones",
        "children": []
      },
      {
        "id": "1-2",
        "name": "Laptops",
        "children": []
      }
    ]
  },
  {
    "id": "2",
    "name": "Clothing",
    "children": [
      {
        "id": "2-1",
        "name": "Men's",
        "children": []
      },
      {
        "id": "2-2",
        "name": "Women's",
        "children": []
      }
    ]
  }
]

With this data structure, you would set:

  • keyExpression: "id"
  • displayExpression: "name"
  • childrenExpression: "children"
  • No labels