peterszerzo / elm-arborist / Arborist

Drag-and-drop interface to edit, dissect and-rearrange tree structures with arbitrary data sitting in their nodes.

Module setup


type State

Opaque type for the editor's model, dependent on a node type variable. You can only use this for type annotation - to initialize a new model, see init.

init : State

Initialize state.


type alias NodeView node msg =
Context node -> Maybe node -> Html msg

View function for an individual node, depending on its context, and its value. This value is expressed as a maybe because the node may contain an insert new node-type placeholder.

view : List (Html.Attribute msg) -> { nodeView : NodeView node msg, tree : Tree node, state : State, toMsg : Updater node -> msg, settings : List (Setting node) } -> Html msg

The editor's view function, taking the following arguments:

subscriptions : List (Setting node) -> State -> Tree node -> Platform.Sub.Sub ( State, Tree node )

Subscriptions for interactive enhancements like keyboard events


type alias Updater node =
State -> Tree node -> ( State
, Tree node 
}

A function that updates hidden state and tree. This function is passed in the toMsg field of the view function.

Passing functions is necessary here because in the update function using elm-arborist, modifications in state always need to operate on the latest value because events like mousemove are fired very frequently and therefore it is possible that the changes caused by one event in the runtime are undone by one that follows immediately after.

Configuration


type alias Setting node =
Internals.Settings.Setting node

Type definition for the settings object

Arborist tree getters and modifiers

hasActiveNode : State -> Basics.Bool

Determines whether there is an active node. This is a simple alternative to activeNode, which provides a lot more information and requires more inputs in scope.

activeNode : { settings : List (Setting node), state : State, tree : Tree node } -> Maybe ( Maybe node, { position : ( Basics.Float, Basics.Float ), context : Context node } )

Returns the current active node as a tuple of Maybe node (as the node maybe a placeholder for a new node), as well as some contextual information as a two-field record:

In order for the position calculations to match the current active node, you must supply the same settings array that the view method gets.

setActiveNode : node -> State -> Tree node -> ( State, Tree node )

Sets a new node at the active position. This may be adding a completely new node from scratch (in case the current node is a placeholder), or modifying an existing one. Typically, the modification is based off an original value provided by the activeNode method.

setActiveNodeWithChildren : { node : node, childrenOverride : Maybe (List node) } -> State -> Tree node -> ( State, Tree node )

Sets the active node with the option to also set its children. The existing children will be discarded along with their children.

deleteActiveNode : State -> Tree node -> ( State, Tree node )

Delete the active node from a tree, including all of its children. If a placeholder is active, this method does nothing.

activeBranch : State -> Tree node -> Maybe (Tree node)

Returns the entire active branch

updateActiveBranch : (Tree node -> Tree node) -> State -> Tree node -> ( State, Tree node )

Similar to setActiveNode, but instead of updating just the node with its subtrees intact, it updates the entire branch based on a Tree -> Tree function.

Display modifiers

reposition : State -> State

Restores the original pan position of the tree.

deactivate : State -> State

Remove active node

Context


type NodeState
    = Normal
    | Active
    | Hovered
    | DropTarget

The state of a node at a given time. May be normal one of the following:


type alias Context item =
{ parent : Maybe item
, siblings : List item
, children : List item
, state : NodeState 
}

View context. Contains the following fields: