dosarf / elm-tree-view / TreeView

Tree view facility.

Also, non-leaf nodes can also be collapsed / expanded programmatically, as well as selected node and visible nodes can be retrieved.

Node uid


type NodeUid comparable
    = NodeUid comparable

Tree view tracks internal state (collapsed/expanded, etc) of the nodes and identifies them by their node uid, thus a node uids must be comparable. Node uids are to be unique in the scope of the forest being displayed by a tree view. Call-site will define how to calculate the node uid for a given node, see uidThunk in Configuration and Configuration2.

To make clear when a function signature is referring to a node uid and not just any other old comparable value, this product type is used.

uidOf : NodeUid comparable -> comparable

Obtains the actual node uid (comparable) value out of the product type value.

Configuration


type alias Configuration d comparable =
{ uidThunk : Tree.Node d -> NodeUid comparable
, labelThunk : Tree.Node d -> String
, cssClasses : CssClasses 
}

Configuration for initializing a tree view Model, to be given to initializeModel. Its fields are: uidThunk : Tree.Node d -> NodeUid comparable gets the uid for a node, wrapped in a NodeUid value, labelThunk : Tree.Node d -> String gets the text representation of a node for rendering, * cssClasses : the record with the CSS class names to generate the tree view HTML element with, see CssClasses as well as defaultCssClasses.

defaultCssClasses : CssClasses

Some CSS class names you can use by default.

A tree view is constructed out of HTML elements table, tr and td, and one or more of the CSS classes will be assigned to them:


type alias CssClasses =
{ treeViewCssClass : String
, selectedTreeNodeCssClass : String
, indentationCssClass : String
, bulletExpandedCssClass : String
, bulletCollapsedCssClass : String
, bulletLeafCssClass : String 
}

Defines CSS classes to be used for a tree view. Different tree views can be made to look different by initializing them with a different set of CSS class names, see also defaultCssClasses.

The actual CSS definitions must always be provided manually, even when the default CSS class names are used. For a working default CSS declarations, see Demo CSS.

Good old TEA types and functions


type Model d comparable customMsg cookie

Model for a tree/forest, with the ability to get the uid for a node, render a node into a string, as well as storing expanded/collapsed presentation states.

Type variables d is the custom data, comparable is the type of the node uid (in practice Int or String) customMsg is the message coming (potentially) out of rendered nodes cookie the type of data given to the view2 function, enabling custom node rendering to use data other than the one stored in a node.

See initializeModel, initializeModel2.

initializeModel : Configuration d comparable -> List (Tree.Node d) -> Model d comparable Basics.Never ()

Initializes a model for a tree view.


type Msg comparable

Message, carrying the uid of the node something happened to.

update : Msg comparable -> Model d comparable customMsg cookie -> Model d comparable customMsg cookie

Updates the tree view model according to the message.

view : Model d comparable customMsg cookie -> Html (Msg comparable)

Render the tree view model into HTML.

subscriptions : Model d comparable customMsg cookie -> Platform.Sub.Sub (Msg comparable)

Subscriptions, for enabling arrow-key based user interactions, such as: selection navigation (up / down arrows), collapse & expand action ( left / right arrows).

Working with tree views

getSelected : Model d comparable customMsg cookie -> Maybe (Tree.AnnotatedNode d)

Gets the selected (annotated) node, if any. See AnnotatedNode.

setSelectionTo : NodeUid comparable -> Model d comparable customMsg cookie -> Model d comparable customMsg cookie

Selects a visible node by its uid. If a node with given uid does not exist or is not visible, nothing happens.

getVisibleAnnotatedNodes : Model d comparable customMsg cookie -> List (Tree.AnnotatedNode d)

Gets the currently visible nodes (annotated). See AnnotatedNode.

Collapsing a non-leaf node will make its children hidden, transitively. The remaining visible nodes are the ones navigated with the up/down arrow keys.

expandAll : Model d comparable customMsg cookie -> Model d comparable customMsg cookie

Expands all nodes.

collapseAll : Model d comparable customMsg cookie -> Model d comparable customMsg cookie

Collapses all nodes.

expandOnly : (d -> Basics.Bool) -> Model d comparable customMsg cookie -> ( Model d comparable customMsg cookie, List comparable )

Expands only the parts of the tree view that are necessary to have nodes with their data matching a given predicate visible.

In addition to the updated model, it returns the list of highlit node uids (nodes matching the predicate).

Coupled with the support to custom-render nodes, this can be used to implement a basic tree search functionality: custom node rendering could highlight an entire node or only parts of it matching a search criteria while hiding any part of the tree that's not harboring a matching node, * as well as setSelectionTo can be used to step selection from one matching node to the next.

updateExpandedStateOf : NodeUid comparable -> Basics.Bool -> Model d comparable customMsg cookie -> Model d comparable customMsg cookie

Updates the model by setting the epxansion state of a node, identified by its node uid. True will expand the node, False will collapse it.

updateNodeData : (d -> Basics.Bool) -> (d -> d) -> Model d comparable customMsg cookie -> Model d comparable customMsg cookie

Updates the data of selected nodes, similar to Tree.updateTreeData. Also updates other bookkeeping related to the tree view.

Custom rendering nodes


type alias Configuration2 d comparable customMsg cookie =
{ uidThunk : Tree.Node d -> NodeUid comparable
, itemThunk : cookie -> Tree.Node d -> Html customMsg
, cssClasses : CssClasses 
}

Similar to Configuration but this allows customer rendering of nodes instead of simple text representation. So instead of labelThunk you have

itemThunk : cookie -> T.Node d -> Html customMsg

that will turn a node (and a cookie of your choice) into a bit of HTML, possibly with its own events. See Msg2.CustomMsg, which will carry the custom messages coming out of the little HTML rendering of a node.

Cookie is for handing down some state that you wish to maintain outside nodes, to node rendering. E.g. you want some check box for each node to mark whether it's selected or not. That selection state may be modeled and stored within a node, but it might be easier to store the set of selected node (uids) outside the tree as well.

initializeModel2 : Configuration2 d comparable customMsg cookie -> List (Tree.Node d) -> Model d comparable customMsg cookie

Just like initializeModel only for tree views with custom rendered nodes.


type Msg2 comparable customMsg
    = Internal (Msg comparable)
    | CustomMsg customMsg

The type of messages emitted by tree views with custom rendered nodes.

update2 : Msg2 comparable customMsg -> Model d comparable customMsg cookie -> Model d comparable customMsg cookie

Just like update only for tree views with custom rendered nodes.

view2 : cookie -> Model d comparable customMsg cookie -> Html (Msg2 comparable customMsg)

Just like view only for tree views with custom rendered nodes.

subscriptions2 : Model d comparable customMsg cookie -> Platform.Sub.Sub (Msg2 comparable customMsg)

Just like subscriptions only for tree views with custom rendered nodes.