TreeView

Tree view facility.

Construct a tree of Node instances, embedding your data into them.
Initialize a model.
Interact with it (conventional TEA)
- Arrow-key interactions require the call-site to use the subscriptions of the facility, otherwise only mouse-click driven interactions work, see subscriptions.
Provide manually the required CSS definitions to make your tree view look usable & nice,
- for a basic working CSS see Demo CSS.

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.

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 : Node d -> NodeUid comparable

, labelThunk : 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:

treeViewCssClass: The CSS class set on all parts of the tree view, table, tr and td, always. Default is tree-view.
selectedTreeNodeCssClass: The CSS class for the TD of a selected node. Default is tree-view-selected-node.
indentationCssClass: The CSS class for an empty TD that used for indentation purposes. Default is tree-view-indentation.
bulletExpandedCssClass: The CSS class for the TD with a bullet in expanded node state. Default is tree-view-bullet-expanded.
bulletCollapsedCssClass: The CSS class for the TD with a bullet in collapsed node state. Default is tree-view-bullet-collapsed.
bulletLeafCssClass: The CSS class for the TD with a bullet in collapsed node state. Default is tree-view-bullet-leaf.

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

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)

See initializeModel.

initializeModel :

Configuration d comparable

-> List (Node d)

-> Model d comparable 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

Updates the tree view model according to the message.

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

Render the tree view model into HTML.

subscriptions : Model d comparable customMsg -> 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 -> Maybe (AnnotatedNode d)

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

getVisibleAnnotatedNodes : Model d comparable customMsg -> List (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 -> Model d comparable customMsg

Expands all nodes.

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

Collapses all nodes.

updateExpandedStateOf :

NodeUid comparable

-> Bool

-> Model d comparable customMsg

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 -> Bool)

-> (d -> d)

-> Model d comparable customMsg

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 =

{ uidThunk : Node d -> NodeUid comparable

, itemThunk : 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 : T.Node d -> Html customMsg

that will turn a node 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.

initializeModel2 :

Configuration2 d comparable customMsg

-> List (Node d)

-> Model d comparable customMsg

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.

Enum Internal carries the type of internal Msg messages that make the tree view work itself. These you feed back to update2 just like with any old message,
Enum CustomMsg carries the custom messages emitted by the HTML fragments that nodes got rendered into. These are the messages that you want to process yourself. E.g. every node may have a button that can be clicked.

update2 :

Msg2 comparable customMsg

-> Model d comparable customMsg

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

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

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

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

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

dosarf/elm-tree-view/2.0.0

TreeView

Node uid

Configuration

Good old TEA types and functions

Working with tree views

Custom rendering nodes

Modules