Elm Tree View

Tree view library (elm-tree-view) for Elm 0.19.

You give the tree of nodes with your data embedded in them, along with with some configuration, and this will take care of some usual UI interaction, such as

• navigate between visible nodes with up/down arrow keys,
• expand / collapse non-leaf nodes with right/left arrow keys,
• expand / collapse non-leaf nodes with mouse clicks.

Demo

Check out

• the working demo,
• or the demo sources.

Overview

The simplest way to take this facility into use is to show tree views that have a simple text representation for each node data.

For that,

• define a data type for the values you'll put into the tree nodes,
  • define a function to calculate the text representation of a node, e.g.

    type alias MyData = { ... }

    nodeLabel : Tree.Node MyData -> String
    nodeLabel node = ...

• decide on a comparable type for the uids of the nodes of the tree,
  • define another function to calculate the uid of a node,

    nodeUid : Tree.Node MyData -> TreeView.NodeUid String
    nodeUid = ...

• build a tree (forest) of nodes, putting your data into them,

    rootNodes : List (Tree.Node MyData)
    rootNodes =
        [ Tree.Node { data = ..., children = [...] }
        , ...
        ]

• construct a configuration for your tree view

    -- configuration for this tree view needs two type parameters
    -- (a) data type and (b) node UID type
    configuration : TreeView.Configuration MyData String
    configuration =
        TV.Configuration
            nodeUid  -- to construct node UIDs
            nodeLabel  -- to render node (data) to text
            TreeView.defaultCssClasses  -- CSS classes to use

• initialize the TreeView model

    type alias Model =
        { ...
        , treeViewModel = TreeView.Model MyData String Never ()
        , ...
        }

    initialModel : Model
    initialModel =
        { ...
        , treeViewModel =
            TreeView.initializeModel configuration rootNodes
        , ...
        }

• and otherwise interact with your tree view in the usual TEA manner, making calls to TreeView.update, TreeView.view

    type Msg
        = TreeViewMsg (TreeView.Msg String) -- for node UIDs of type String
        | ...

• if (or when) you want the tree view to navigate up/down between visible nodes and expand/collapse nodes on arrow key presses, use TreeView.subscriptions

    subscriptions : Model -> Sub Msg
    subscriptions model =
        Sub.map TreeViewMsg (TreeView.subscriptions model.treeModel)

Custom node rendering

You may want fancier rendering of nodes, possibly with user interaction.

The essential difference to the simple case outlined above is that instead of a node data -> text rendering function, you need a function that turns a cookie (of yours) and a node data into a piece of Html emitting your own little node-specific messages.

-- the type of application data that may be needed for custom
-- node rendering
type alias MyCookie = { ... }

-- messages coming out of node specific Html fragments
type MyDataMsg = ...

-- fancy custom node rendering using cookie + node data
viewNodeData : MyCookie -> Tree.Node MyData -> Html.Html MyDataMsg
viewNodeData = ...

From here on, switch to using types and functions with the suffix 2, such as TreeView.Configuration2, TreeView.initializeModel2, TreeView.Msg2, TreeView.update2, TreeView.view2 and TreeView.subscriptions2.

Test

• Install elm-test (with npm)
• Run elm-test.

Changelog

3.x

3.0.0 (2019-09-17)

Cookie for custom node rendering

Custom node rendering function can now use cookie data - data that is not within the node. That's an extra type parameter to the TreeView.Model.

If you are not using custom rendering at all, or you do but you don't need any cookie data for node rendering, just update your 2.x TreeView application

    type alias MyModel =
    {
        ...
    ,   treeViewModel : TreeView.Model MyData MyUid Never -- elm-tree-view 2.x
    }

thusly:

    type alias MyModel =
    {
        ...
    ,   treeViewModel : TreeView.Model MyData MyUid ()
    }

If you use custom node rendering with cookie, then you will be using some type of yours instead of the unit type ().

Support for TreeView search

You can now construct tree views that can be searched. Or more accurately, you now have a way (see TreeView.expandOnly) to expand only those nodes that harbor a child node matching a certain criteria, effectively hiding (collapsing) significant part of the tree. See also the demo.

2.x

2.0.1 (2019-08-30)

Added changelog to README.md, no code changes.

2.0.0 (2019-08-29)

Nodes can have custom HTML rendering with messages and interactions on their own.

To upgrade from using 1.x to 2.0.0, modify 1.x TreeView model declarations like

    type alias MyModel =
    {
        ...
    ,   treeViewModel : TreeView.Model MyData MyUid -- elm-tree-view 1.x
    }

just add a Never to say no custom messages are coming from such a simple tree view, like

    type alias MyModel =
    {
        ...
    ,   treeViewModel : TreeView.Model MyData MyUid Never -- elm-tree-view 2.0.0
    }

it should build and behave the same (nodes rendered as simple texts).

To go for custom node rendering, use the new types and functions with the suffix 2, like TreeView.Configuration2, TreeView.initializeModel2, etc ...

1.x

1.0.0 (2019-07-26)

Initial version - nodes are rendered as simple text only.