Tree view facility.
subscriptions
.Also, non-leaf nodes can also be collapsed / expanded programmatically, as well as selected node and visible nodes can be retrieved.
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.
{ 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:
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
.{ 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.
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.
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).
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.
{ 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.
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 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.