Option to disable cursor keyboard navigation on treelist widgets

Thomas Bruederli

2014-06-18 6c647deffce183bc37ac55e3b3ae35eb5922d428

 program/js/treelist.js

@@ -1,20 +1,33 @@
/*
 +-----------------------------------------------------------------------+
 | Roundcube Treelist widget                                             |
 |                                                                       |
 | This file is part of the Roundcube Webmail client                     |
 | Copyright (C) 2013, The Roundcube Dev Team                            |
 |                                                                       |
 | Licensed under the GNU General Public License version 3 or            |
 | any later version with exceptions for skins & plugins.                |
 | See the README file for a full license statement.                     |
 |                                                                       |
 +-----------------------------------------------------------------------+
 | Authors: Thomas Bruederli <roundcube@gmail.com>                       |
 +-----------------------------------------------------------------------+
 | Requires: common.js                                                   |
 +-----------------------------------------------------------------------+
*/
/**
 * Roundcube Treelist Widget
 *
 * This file is part of the Roundcube Webmail client
 *
 * @licstart  The following is the entire license notice for the
 * JavaScript code in this file.
 *
 * Copyright (c) 2013-2014, The Roundcube Dev Team
 *
 * The JavaScript code in this page is free software: you can
 * redistribute it and/or modify it under the terms of the GNU
 * General Public License (GNU GPL) as published by the Free Software
 * Foundation, either version 3 of the License, or (at your option)
 * any later version.  The code is distributed WITHOUT ANY WARRANTY;
 * without even the implied warranty of MERCHANTABILITY or FITNESS
 * FOR A PARTICULAR PURPOSE.  See the GNU GPL for more details.
 *
 * As additional permission under GNU GPL version 3 section 7, you
 * may distribute non-source (e.g., minimized or compacted) forms of
 * that code without the copy of the GNU GPL normally required by
 * section 4, provided you include this license notice and a URL
 * through which recipients can access the Corresponding Source.
 *
 * @licend  The above is the entire license notice
 * for the JavaScript code in this file.
 *
 * @author Thomas Bruederli <roundcube@gmail.com>
 * @requires jquery.js, common.js
 */


/**
@@ -31,6 +44,8 @@
    scroll_delay: 500,
    scroll_step: 5,
    scroll_speed: 20,
    save_state: false,
    keyboard: true,
    check_droptarget: function(node){ return !node.virtual }
  }, p || {});

@@ -39,6 +54,9 @@
    indexbyid = {},
    selection = null,
    drag_active = false,
    search_active = false,
    last_search = '',
    has_focus = false,
    box_coords = {},
    item_coords = [],
    autoexpand_timer,
@@ -46,6 +64,10 @@
    body_scroll_top = 0,
    list_scroll_top = 0,
    scroll_timer,
    searchfield,
    tree_state,
    ui_droppable,
    list_id = (container.attr('id') || p.id_prefix || '0'),
    me = this;


@@ -60,10 +82,12 @@
  this.drag_start = drag_start;
  this.drag_end = drag_end;
  this.intersects = intersects;
  this.droppable = droppable;
  this.update = update_node;
  this.insert = insert;
  this.remove = remove;
  this.get_item = get_item;
  this.get_node = get_node;
  this.get_selection = get_selection;

  /////// startup code (constructor)
@@ -92,6 +116,56 @@
    }
  });

  // activate search function
  if (p.searchbox) {
    searchfield = $(p.searchbox).on('keyup', function(e) {
      var key = rcube_event.get_keycode(e),
        mod = rcube_event.get_modifier(e);

      switch (key) {
        case 9:   // tab
          break;

        case 13:  // enter
          search(this.value, true);
          return rcube_event.cancel(e);

        case 27:  // escape
          reset_search();
          break;

        case 38:  // arrow up
        case 37:  // left
        case 39:  // right
        case 40:  // arrow down
          return;  // ignore arrow keys

        default:
          search(this.value, false);
          break;
      }
    }).attr('autocomplete', 'off');

    // find the reset button for this search field
    searchfield.parent().find('a.reset').click(function(e) {
      reset_search();
      return false;
    })
  }

  container.on('focusin', function(e){
      // TODO: only accept focus on virtual nodes from keyboard events
      has_focus = true;
    })
    .on('focusout', function(e){
      has_focus = false;
    });

  container.attr('role', 'tree');

  $(document.body)
    .bind('keydown', keypress);


  /////// private methods

@@ -106,11 +180,6 @@
      node.collapsed = typeof set == 'undefined' || set;
      update_dom(node);

      // Work around a bug in IE6 and IE7, see #1485309
      if (window.bw && (bw.ie6 || bw.ie7) && node.collapsed) {
        id2dom(node.id).next().children('ul:visible').hide().show();
      }

      if (recursive && node.children) {
        for (var i=0; i < node.children.length; i++) {
          collapse(node.children[i].id, recursive, set);
@@ -118,6 +187,7 @@
      }

      me.triggerEvent(node.collapsed ? 'collapse' : 'expand', node);
      save_state(id, node.collapsed);
    }
  }

@@ -146,13 +216,13 @@
  function select(id)
  {
    if (selection) {
      id2dom(selection).removeClass('selected');
      id2dom(selection).removeClass('selected').removeAttr('aria-selected');
      selection = null;
    }

    var li = id2dom(id);
    if (li.length) {
      li.addClass('selected');
      li.addClass('selected').attr('aria-selected', 'true');
      selection = id;
      // TODO: expand all parent nodes if collapsed
      scroll_to_node(li);
@@ -172,9 +242,17 @@
  /**
   * Return the DOM element of the list item with the given ID
   */
  function get_item(id)
  function get_node(id)
  {
    return id2dom(id).get(0);
    return indexbyid[id];
  }

  /**
   * Return the DOM element of the list item with the given ID
   */
  function get_item(id, real)
  {
    return id2dom(id, real).get(0);
  }

  /**
@@ -183,13 +261,27 @@
  function insert(node, parent_id, sort)
  {
    var li, parent_li,
      parent_node = parent_id ? indexbyid[parent_id] : null;
      parent_node = parent_id ? indexbyid[parent_id] : null
      search_ = search_active;

    // ignore, already exists
    if (indexbyid[node.id]) {
      return;
    }

    // apply saved state
    state = get_state(node.id, node.collapsed);
    if (state !== undefined) {
      node.collapsed = state;
    }

    // insert as child of an existing node
    if (parent_node) {
      node.level = parent_node.level + 1;
      if (!parent_node.children)
        parent_node.children = [];

      search_active = false;
      parent_node.children.push(node);
      parent_li = id2dom(parent_id);

@@ -202,9 +294,25 @@
        // append new node to parent's child list
        li = render_node(node, parent_li.children('ul').first());
      }

      // list is in search mode
      if (search_) {
        search_active = search_;

        // add clone to current search results (top level)
        if (!li.is(':visible')) {
          $('<li>')
            .attr('id', li.attr('id') + '--xsR')
            .attr('class', li.attr('class'))
            .addClass('searchresult__')
            .append(li.children().first().clone(true, true))
            .appendTo(container);
        }
      }
    }
    // insert at top level
    else {
      node.level = 0;
      data.push(node);
      li = render_node(node, container);
    }
@@ -268,7 +376,7 @@
    if (sibling) {
      li.insertAfter(sibling);
    }
    else if (first.id != myid) {
    else if (first && first.id != myid) {
      li.insertBefore(first);
    }

@@ -284,7 +392,7 @@
    var node, li;

    if (node = indexbyid[id]) {
      li = id2dom(id);
      li = id2dom(id, true);
      li.remove();

      node.deleted = true;
@@ -301,7 +409,7 @@
   */
  function update_data()
  {
    data = walk_list(container);
    data = walk_list(container, 0);
  }

  /**
@@ -310,6 +418,7 @@
  function update_dom(node)
  {
    var li = id2dom(node.id);
    li.attr('aria-expanded', node.collapsed ? 'false' : 'true');
    li.children('ul').first()[(node.collapsed ? 'hide' : 'show')]();
    li.children('div.treetoggle').removeClass('collapsed expanded').addClass(node.collapsed ? 'collapsed' : 'expanded');
    me.triggerEvent('toggle', node);
@@ -327,6 +436,80 @@
    drag_active = false;

    container.html('');

    reset_search();
  }

  /**
   * 
   */
  function search(q, enter)
  {
    q = String(q).toLowerCase();

    if (!q.length)
      return reset_search();
    else if (q == last_search && !enter)
      return 0;

    var hits = [];
    var search_tree = function(items) {
      $.each(items, function(i, node) {
        var li, sli;
        if (!node.virtual && !node.deleted && String(node.text).toLowerCase().indexOf(q) >= 0 && hits.indexOf(node.id) < 0) {
          li = id2dom(node.id);
          sli = $('<li>')
            .attr('id', li.attr('id') + '--xsR')
            .attr('class', li.attr('class'))
            .addClass('searchresult__')
            .append(li.children().first().clone(true, true))
            .appendTo(container);
            hits.push(node.id);
        }

        if (node.children && node.children.length) {
          search_tree(node.children);
        }
      });
    };

    // reset old search results
    if (search_active) {
      $(container).children('li.searchresult__').remove();
      search_active = false;
    }

    // hide all list items
    $(container).children('li').hide().removeClass('selected');

    // search recursively in tree (to keep sorting order)
    search_tree(data);
    search_active = true;
    last_search = q;

    me.triggerEvent('search', { query: q, last: last_search, count: hits.length, ids: hits, execute: enter||false });

    return hits.count;
  }

  /**
   * 
   */
  function reset_search()
  {
    if (searchfield)
      searchfield.val('');

    $(container).children('li.searchresult__').remove();
    $(container).children('li').show();

    search_active = false;

    me.triggerEvent('search', { query: false, last: last_search });
    last_search = '';

    if (selection)
      select(selection);
  }

  /**
@@ -342,6 +525,7 @@

    // render child nodes
    for (var i=0; i < data.length; i++) {
      data[i].level = 0;
      render_node(data[i], container);
    }

@@ -358,7 +542,9 @@

    var li = $('<li>')
      .attr('id', p.id_prefix + (p.id_encode ? p.id_encode(node.id) : node.id))
      .addClass((node.classes || []).join(' '));
      .attr('role', 'treeitem')
      .addClass((node.classes || []).join(' '))
      .data('id', node.id);

    if (replace)
      replace.replaceWith(li);
@@ -370,6 +556,9 @@
    else if (typeof node.html == 'object')
      li.append(node.html);

    if (!node.text)
      node.text = li.children().first().text();

    if (node.virtual)
      li.addClass('virtual');
    if (node.id == selection)
@@ -377,12 +566,14 @@

    // add child list and toggle icon
    if (node.children && node.children.length) {
      li.attr('aria-expanded', node.collapsed ? 'false' : 'true');
      $('<div class="treetoggle '+(node.collapsed ? 'collapsed' : 'expanded') + '">&nbsp;</div>').appendTo(li);
      var ul = $('<ul>').appendTo(li).attr('class', node.childlistclass);
      var ul = $('<ul>').appendTo(li).attr('class', node.childlistclass).attr('role', 'group');
      if (node.collapsed)
        ul.hide();

      for (var i=0; i < node.children.length; i++) {
        node.children[i].level = node.level + 1;
        render_node(node.children[i], ul);
      }
    }
@@ -394,17 +585,19 @@
   * Recursively walk the DOM tree and build an internal data structure
   * representing the skeleton of this tree list.
   */
  function walk_list(ul)
  function walk_list(ul, level)
  {
    var result = [];
    ul.children('li').each(function(i,e){
      var li = $(e), sublist = li.children('ul');
      var state, li = $(e), sublist = li.children('ul');
      var node = {
        id: dom2id(li),
        classes: li.attr('class').split(' '),
        classes: String(li.attr('class')).split(' '),
        virtual: li.hasClass('virtual'),
        level: level,
        html: li.children().first().get(0).outerHTML,
        children: walk_list(sublist)
        text: li.children().first().text(),
        children: walk_list(sublist, level+1)
      }

      if (sublist.length) {
@@ -412,14 +605,39 @@
      }
      if (node.children.length) {
        node.collapsed = sublist.css('display') == 'none';

        // apply saved state
        state = get_state(node.id, node.collapsed);
        if (state !== undefined) {
          node.collapsed = state;
          sublist[(state?'hide':'show')]();
        }

        if (!li.children('div.treetoggle').length)
          $('<div class="treetoggle '+(node.collapsed ? 'collapsed' : 'expanded') + '">&nbsp;</div>').appendTo(li);

        li.attr('aria-expanded', node.collapsed ? 'false' : 'true');
      }
      if (li.hasClass('selected')) {
        li.attr('aria-selected', 'true');
        selection = node.id;
      }

      li.data('id', node.id);

      // declare list item as treeitem
      li.attr('role', 'treeitem').attr('aria-level', node.level+1);

      // allow virtual nodes to receive focus
      if (node.virtual) {
        li.children('a:first').attr('tabindex', '0');
      }

      result.push(node);
      indexbyid[node.id] = node;
    })
    });

    ul.attr('role', level == 0 ? 'tree' : 'group');

    return result;
  }
@@ -442,17 +660,18 @@
   */
  function dom2id(li)
  {
    var domid = li.attr('id').replace(new RegExp('^' + (p.id_prefix) || '%'), '');
    var domid = li.attr('id').replace(new RegExp('^' + (p.id_prefix) || '%'), '').replace(/--xsR$/, '');
    return p.id_decode ? p.id_decode(domid) : domid;
  }

  /**
   * Get the <li> element for the given node ID
   */
  function id2dom(id)
  function id2dom(id, real)
  {
    var domid = p.id_encode ? p.id_encode(id) : id;
    return $('#' + p.id_prefix + domid);
    var domid = p.id_encode ? p.id_encode(id) : id,
      suffix = search_active && !real ? '--xsR' : '';
    return $('#' + p.id_prefix + domid + suffix, container);
  }

  /**
@@ -467,6 +686,124 @@
    if (rel_offset < 0 || rel_offset + li.height() > scroller.height())
      scroller.scrollTop(rel_offset + current_offset);
  }

  /**
   * Save node collapse state to localStorage
   */
  function save_state(id, collapsed)
  {
    if (p.save_state && window.rcmail) {
      var key = 'treelist-' + list_id;
      if (!tree_state) {
        tree_state = rcmail.local_storage_get_item(key, {});
      }

      if (tree_state[id] != collapsed) {
        tree_state[id] = collapsed;
        rcmail.local_storage_set_item(key, tree_state);
      }
    }
  }

  /**
   * Read node collapse state from localStorage
   */
  function get_state(id)
  {
    if (p.save_state && window.rcmail) {
      if (!tree_state) {
        tree_state = rcmail.local_storage_get_item('treelist-' + list_id, {});
      }
      return tree_state[id];
    }

    return undefined;
  }

  /**
   * Handler for keyboard events on treelist
   */
  function keypress(e)
  {
    var target = e.target || {},
      keyCode = rcube_event.get_keycode(e);

    if (!has_focus || target.nodeName == 'INPUT' || target.nodeName == 'TEXTAREA' || target.nodeName == 'SELECT')
      return true;

    switch (keyCode) {
      case 38:
      case 40:
      case 63232: // 'up', in safari keypress
      case 63233: // 'down', in safari keypress
        var li = p.keyboard ? container.find(':focus').closest('li') : [];
        if (li.length) {
          focus_next(li, (mod = keyCode == 38 || keyCode == 63232 ? -1 : 1));
        }
        return rcube_event.cancel(e);

      case 37: // Left arrow key
      case 39: // Right arrow key
        var id, node, li = container.find(':focus').closest('li');
        if (li.length) {
          id = dom2id(li);
          node = indexbyid[id];
          if (node && node.children.length && node.collapsed != (keyCode == 37))
            toggle(id, rcube_event.get_modifier(e) == SHIFT_KEY);  // toggle subtree
        }
        return false;

      case 9:  // Tab
        if (p.keyboard) {
          // jump to last/first item to move focus away from the treelist widget by tab
          var limit = rcube_event.get_modifier(e) == SHIFT_KEY ? 'first' : 'last';
          focus_noscroll(container.find('li[role=treeitem]:has(a)')[limit]().find('a:'+limit));
        }
        break;
    }

    return true;
  }

  function focus_next(li, dir, from_child)
  {
    var mod = dir < 0 ? 'prev' : 'next',
      next = li[mod](), limit, parent;

    if (dir > 0 && !from_child && li.children('ul[role=group]:visible').length) {
      li.children('ul').children('li:first').children('a:first').focus();
    }
    else if (dir < 0 && !from_child && next.children('ul[role=group]:visible').length) {
      next.children('ul').children('li:last').children('a:last').focus();
    }
    else if (next.length && next.children('a:first')) {
      next.children('a:first').focus();
    }
    else {
      parent = li.parent().closest('li[role=treeitem]');
      if (parent.length)
        if (dir < 0) {
          parent.children('a:first').focus();
        }
        else {
          focus_next(parent, dir, true);
        }
    }
  }

  /**
   * Focus the given element without scrolling the list container
   */
  function focus_noscroll(elem)
  {
    if (elem.length) {
      var frame = container.parent().get(0) || { scrollTop:0 },
        y = frame.scrollTop || frame.scrollY;
      elem.focus();
      frame.scrollTop = y;
    }
  }


  ///// drag & drop support

@@ -590,7 +927,8 @@
    // no intersection with list bounding box
    if (mouse.x < box_coords.x1 || mouse.x >= box_coords.x2 || mouse.top < box_coords.y1 || mouse.top >= box_coords.y2) {
      // TODO: optimize performance for this operation
      $('li.droptarget', container).removeClass('droptarget');
      if (highlight)
        $('li.droptarget', container).removeClass('droptarget');
      return result;
    }

@@ -611,6 +949,8 @@
            expand(autoexpand_item);
            drag_start();  // re-calculate item coords
            autoexpand_item = null;
            if (ui_droppable)
              $.ui.ddmanager.prepareOffsets($.ui.ddmanager.current, null);
          }, p.autoexpand);
        }
        else if (autoexpand_timer && autoexpand_item != id) {
@@ -639,6 +979,38 @@

    return result;
  }

  /**
   * Wrapper for jQuery.UI.droppable() activation on this widget
   *
   * @param object Options as passed to regular .droppable() function
   */
  function droppable(opts)
  {
    var my_opts = $.extend({ greedy: true, hoverClass: 'droptarget', addClasses:false }, opts);

    my_opts.activate = function(e, ui) {
      drag_start();
      ui_droppable = ui;
      if (opts.activate)
        opts.activate(e, ui);
    };

    my_opts.deactivate = function(e, ui) {
      drag_end();
      ui_droppable = null;
      if (opts.deactivate)
        opts.deactivate(e, ui);
    };

    my_opts.over = function(e, ui) {
      intersects(rcube_event.get_mouse_pos(e), false);
      if (opts.over)
        opts.over(e, ui);
    };

    $('li:not(.virtual)', container).droppable(my_opts);
  }
}

// use event processing functions from Roundcube's rcube_event_engine