Skip to content

Latest commit

 

History

History
158 lines (115 loc) · 6.74 KB

api.md

File metadata and controls

158 lines (115 loc) · 6.74 KB

insightTree

Renders a hierarchical tree based on the provided data and configuration.

This function calculates a tree data structure based on the input data and configuration, then renders the tree into the specified DOM element. It also provides interactivity to expand or collapse nodes upon user clicks.

Parameters

  • selector string The CSS selector of the DOM element where the tree will be rendered.

  • options Object Configuration for the tree rendering and interaction.

    • options.data Array<Object> An array of objects representing the data rows.
    • options.groups (Array<string> | Object) Defines the hierarchy levels of the tree.
    • options.metrics (Array<string> | Object) Specifies the metrics to aggregate.
    • options.sort (string | Object)? Defines the sorting criteria for each level.
    • options.impact (string | function)? Specifies the impact metric to rank insights by.
    • options.totalGroup string Name of the total row's GROUP. (optional, default "Total")
    • options.render function A function to render the tree. (optional, default tableRender)
    • options.rankBy

Examples

const tree = insightTree("#myTree", {
  data: [...],
  groups: ["a", "b"],
  metrics: ["x", "y"],
  sort: "+x",
  impact: "x"
});
  • Throws Error Throws an error if the provided selector does not match any DOM element.

Returns Object Returns an object with methods to interact with the rendered tree. Includes* .tree - The calculated tree data structure.

  • .update() - Method to update the tree.
  • .toggle() - Method to toggle nodes' expansion or collapse state.
  • .show() - Method to show/hide nodes based on a rule.
  • .classed() - Method to set class on each node

toggle

Toggles the expansion or collapse state of the specified node.

If force is not provided, toggles the node. force=true expands the node. force=false collapses the node.

Uses data-insight-level to determine levels. After toggling, it also toggles the visibility of all child nodes. Direct children are shown/hidden based when the node is expanded/collapsed. Grandchildren and below are always hidden.

Parameters

  • insightTree Object insightTree object
  • node HTMLElement The DOM node to be toggled.
  • force boolean?? true expands node. false collapses node. If skipped, toggles node.

Examples

// Toggle the root node
toggle(treeData, document.querySelector("[data-insight-level=0]"));
// Expand the root node
toggle(treeData, document.querySelector("[data-insight-level=0]"), true);
// Collapse the root node
toggle(treeData, document.querySelector("[data-insight-level=0]"), false);

Returns insightTree Returns the insightTree object.

show

Filters the tree nodes based on a specified rule, expanding or collapsing each node accordingly.

Uses data-insight-level to determine levels. Applies the filter function to each node and expands the row if it returns true, else collapses it. The filter function receives two parameters:

  • row: The node object with properties like LEVEL, RANK, GROUP, and all group keys for the row.
  • node: The DOM node corresponding to the row.

Parameters

  • insightTree Object insightTree object

  • filter function (Object, HTMLElement): boolean function(row, node) that returns true/false to expand/collapse node

  • options Object? display options (optional, default {})

    • options.openAncestors boolean If true, opens all ancestors of the shown nodes. (optional, default true)
    • options.showSiblings boolean If true, shows all siblings of the shown nodes. (optional, default false)
    • options.hiddenClass string The CSS class to apply to hidden nodes. (optional, default "insight-hidden")
    • options.closedClass string The CSS class to apply to closed nodes. (optional, default "insight-closed")

Examples

// Assuming the DOM has nodes with `data-insight-level` attribute and a corresponding tree data structure.
show(treeData, (row) => row[LEVEL] == 0 || row[GROUP] == "Bonn");

Returns insightTree Returns the insightTree object.

update

Updates the visibility and styling of tree nodes based on the specified rank and level criteria.

Uses data-insight-level and data-insight-rank of the nodes to determine levels and ranks.

  • Nodes with a rank == options.rank will have ".insight-current".
  • Nodes with a rank <= options.rank will have ".insight-highlight" (if exactRank=true).
  • Nodes will be shown if
    • rank <= options.rank (or rank == options.rank if exactRank=false), OR
    • level <= options.level, OR
    • they have a child node that meets the rank criteria.
  • Closed nodes (without a child that meets the rank criteria) will have ".insight-closed".

Parameters

  • insightTree Object insightTree object

  • criteria Object The criteria for updating the tree nodes.

    • criteria.rank number? The rank criteria. Nodes with rank <= options.rank will be highlighted (or rank == options.rank if exactRank=true).
    • criteria.level number? The level criteria. Nodes with level <= options.value will be shown.

  • options Object? display options (optional, default {})

    • options.leaf Object? If true, shows the LEAF (not parent nodes) with specified rank. Default: false
    • options.exactRank Object? If true, shows only specified rank. Else shows all ranks UPTO specified rank. Default: false
    • options.showOptions boolean? Options for .show()

Examples

// Assuming the DOM has nodes with `data-insight-level` and `data-insight-rank` attributes.
update(
  treeData,
  { rank: 3, level: 2 },
  { exactRank: false, showSiblings: true },
);

Returns insightTree Returns the insightTree object.