SpecSelect

Vision

Trees should support selection of one ore more nodes.

Status

This feature is already implemented (demo).

Yet there are still open questions, so this feature is open for discussion and the API is subject to change.

Please discuss here: https://github.com/mar10/fancytree/issues/12

Requirements

• Nodes may have a state ´selected´, which is independent from the active state.
• There must be a visual representation, that makes this distinguishable.
• The selection state must be easily queried by JS. It must also easily be submitted to the server.
• Selection must be controllable using events (i.e. return false on beforeSelect).
• Selection must possible using checkboxes.
  Checkboxes may be hidden globally or by node.
  Checkboxes may be disabled globally or by node.
• Selection must be possible using the API.
• We support different modes
  • 1: single
    Only one (or no) node is selected at any time. Selecting another node will deselect the previous.
  • 2: multi
    No, one, or more nodes may be selected at any time.
  • 3: multi-hier
    No, one, or more nodes may be selected at any time.
    In this mode only the selection status of end nodes (i.e. leaves) is relevant!.
    (De)selecting a parent node will (de)select all children.
    If some (but not all) descendants of a node are selected, this node is displayed as 'partly selected'

Diskussion

Resources

Problems

The feature is basically working, but currently there are some main issues and open questions:

1. Precedence in simple mode
   When the tree source data (or initial Ajax response) contains more than one selected node, should we fix it? If so: how?
2. 'unselectable' option
   Nodes may be marked 'unselectable', which should prevent changing the selection state by user clicks.
   An unselectable node by be initialized 'selected', which is fine. The user may not deselect it using a click.
   (De)Selection using the API should still be possible(?)
3. 'unselectable' option in multi-hier mode
   Should the unselectable node preserve its state when the parent is (de)selected? This would mean, that after selecting the parent, the parent is still marked 'partSel'.
   Or we mark the parent 'selected', even if some children are unselectable.
4. Precedence in multi-hier mode
   When the tree source data (or initial Ajax response) contains inconsistent data, should we fix it?
   If so: how?
   Example: a node is marked as selected, but its children are not. Should we select all children, or deselect the parent?
5. Lazy trees in multi-hier mode
   When we select a lazy/unloaded node, this means 'select all children'.
   Now we expand the parent, which triggers lazy loading. The response may contain unselected nodes; what now? (see issue #247)
6. Persistence
   This feature must be compatible with persistence (see SpecPersistence)

Proposal

We assume the following use case as most likely:

The server does maintain the tree structure, but not the selection state. For example we have a hierarchical structure of options, but any user will choose its own selection set.
If the user has finished its selections, she will submit this data to the server (or the selection set is only used by client-side JavaScript).

This allows the following decisions:

• When a user expresses a wish by actively selecting a node, this takes precedence.
  So if we select a lazy parent, then expand it, all children are expected to be selected, even if the server sends them unselected.
• If the server sends selected nodes, we treat this as initial default selection.
• If this data is inconsistent, we don't repair it!

But we should also make the following - less likely - use case possible:

The tree represents a single data model that is maintained on the server - or the server maintains the tree model by user. Selecting a node will modify the global data. If the tree sends selected nodes, this should take precedence.

Current Implementation

(See the demo).

Select mode 3 (multi-hier) is implemented, so that (de-)selection of nodes by the user will update the tree automatically .
In addition, two API functions are available to implement desired behavior after lazy loading or manipulating the tree structure:

• fixSelection3AfterClick()
  Fix selection status, after this node was (de)selected in multi-hier mode. This includes (de)selecting all children.
  This method is called internally after checkbox clicks, but may be handy in other situations as well.

• fixSelection3FromEndNodes()
  Fix selection status for multi-hier mode. Only end-nodes are considered to update the descendants branch and parents.
  Should be called after this node has loaded new children or after children have been modified using the API.

Example:

Fix the check-status of children after lazy load. This assumes that the expanded parent node should apply its status to the children, even if the server sent different selection statuses:

$("#tree").fancytree({
    ...
    loadChildren: function(event, ctx) {
        ctx.node.fixSelection3AfterClick();
    },
});

Fix the check-status of all nodes, assuming that the end nodes currently contain the truth. This will repair the status, after nodes have been added or removed using the API:

$("#tree").fancytree("getRootNode").fixSelection3FromEndNodes();