SpecKeyboard

Vision

Fancytree should be controllable using the keyboard. When embedded into a web form, it should behave like a control (e.g. a listbox).

Status

There is an experimental extension (see 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/71

Requirements

The option keyboard: true should be used to control if standard keyboard navigation is enabled. This assumes that the tree can be made 'keyboard-active' in some way, in case you have other trees or controls on the page. (Not necessarily the browsers system ':focus'. Maybe by adding a 'focus' class to the container or maintaining a global 'focusTree' variable).

• Key mapping:

  • +: Expand node.
  • -: Collapse node.
  • SPACE: in select mode: toggle selection. Otherwise set active.
  • ENTER: Set active.
  • BACKSPACE: Set focus to parent.
  • LEFT: If expanded: collapse. Otherwise set focus to parent.
  • RIGHT: If collapsed: expand. Otherwise set focus to first child.
  • UP: Set focus to previous sibling (or parent if already on first sibling).
  • DOWN: Set focus to next visible node.
  • Ctrl-Cursor: Same as Cursor, but only sets the focus, even if autoActivate is on.
  • F2 edit title (requires edit extension)

• Note that we distinguish 'focused', 'active', and 'selected'. 'Set focus' only sets a dotted border around the node. When autoActivate is enabled (which is on by default), the node also gets activated.

• Special case table extension: If the table is only used readonly to get a column-alignment, we can use the above mapping.
  ??? If the grid contains checkboxes or input fields however, it would be desirable to navigate between the grid cells with TAB, Shift-TAB, UP, DOWN?

The tabbable: true option was added to control the behavior when the tree is part of a web form. If we TAB through a form that contains a tree and other controls, the tree should behave like a listbox, i.e.

• be entered / exited using TAB, i.e. be part of the tab index chain
• set focus to the active node when entered using TAB
• it is possible that the tree control is active, but no node is yet active (see the listbox in the 'Embed in Forms' demo, at least in Safari).
• optionally activate first node when entered using TAB and no node was active
• gray out active node marker when tree control looses focus

If the default implementation for keyboard: true also satisfies these requirements (and makes all users happy), maybe we can remove the tabbable option.

Must Have

• Support multiple trees on one page
• Play nicely with other controls (listbox, input, ...) on the same page or form.
• A disabled tree should ignore keystrokes
• Don't break key handling for other controls on the same page (see https://github.com/mar10/fancytree/issues/71 )
• Setting keyboard: false will disable keyboard navigation for the tree. (??? but keep it in the TAB-chain?)
• Allow implementation of WAI-ARIA support (see SpecAria)
• Should work if the node titles contain tabbable elemts (like <a> or <input>).

Should Have

• Use valid HTML
• Setting tabbable: false will remove the tree from the tab chain.
• Should be portableto the table extension

Diskussion

Resources

• SpecMarkup
• SpecAria

Problems

Proposal

(TODO)

Variant 1: Bind key handler to container (prev. implementation in Dynatree)

Dynatree is the predecessor of Fancytree.

• Nodes use <a> tags for titles, which get the system focus on click.
• bind "keydown.dynatree" to widget.element --> node._onKeydown(event)
• bind focus + blur to tree.divTree --> node._onFocus(event)
• _onKeydown: implement navgation and preventDefault()
• _onKeypress: does nothing
• _onFocus: set tree.tnFocused and add class focused to the node

Known Problems

Using <a> tags may cause problems on IE (i.e. auto-scrolling to the left sometimes, when user click on a node).

Variant 2: Bind key handler to document (current implementation)

• nodes are simple span tags
• container: <ul tabindex="0"> (when tabbable option is true)
• keydown is bound to document, because $container might not receive key events, because the nodes cannot have the system focus.
• $(document).bind("keydown" + ns) --> tree.nodeKeydown(event)
• tree.$container.bind("focusin" + ns + " focusout" + ns) --> tree.treeOnFocusInOut(event);
• nodeKeydown(event):
• treeOnFocusInOut(event): calls nodeSetFocus()
• nodeSetFocus(event): maintain node.tree.focusNode and ...

<div id="tree">
  <ul class="fancytree-container" tabindex="0" >
  </ul>
</div>

Variant 3: Bind key handler to container

• add a dummy element with a tabindex

Variant 4: Bind key handler to nodes

• make tree.hasFocus() smarter, i.e. record if the tree is focused in tabbable=false mode. Then we could return false in the keyboard handler for inactive trees, which should solve the issue.
• improve 'tabbable=true' behavior (why do one want to disable it)?

Current Specification

Currently 'Variant 2' is implemented. TODO