Switch Access

switch_access.coffee is a coffeescript that enables switch/keyboard control for navigating a webpage for AAC users.

Features

• 1 or 2 switches
• Switch groups and nested groups
• Switches need to send normal "keys" (e.g. space/enter)
• Lots of options to customize how the switch access works on a page.
• Triggers the a click on the a html element or the first link inside the element (depending on options)

Usage

Example

HTML markup:

  <div class"switch-element">
    Div is the switch-element
    <a href="#">link inside a div.</a>
  </div>
  <a href="#" class="switch-element">link is a switch element</a>
  <p class="switch-element"><a href="#">link inside a p.</a></p>

Javascript:

  $(document).ready(function(){
    window.switch_access = new SwitchAccess({
      switches: {
        number_of_switches: 2
      }
    });
  });

Methods

All methods assume that you initiated the controller similar to the above example.

  // start switch access (Done automatically upon construction of object)
  window.switch_access.start() 

  // stop switch access
  window.switch_access.stop() 

  // Remove/Destroy the switch access 
  window.switch_access.destroy()

  // set options. Note: The switch access will stop, so you need to call start after setting options.
  window.switch_access.setoptions({
    switches: {
      number_of_switches: 1,
      single_switch_move_time: 2500 // 2,5 seconds (time is in milliseconds)
    }
  })

Options

  ###
  Switch/Key settings 
  ###
  switches:

    ### 
    The number of switches 0 = disable, 1 = single switch, 2 = two switches 
    Default: 2
    ###
    number_of_switches:                  0

    ###
    Array for the keycodes to use as single switch (Multiple keycodes possible)
    Default: [32, 13]  (32 = 'Space', 13 = 'Enter')        
    ###
    keys_1:                              [32, 13] # Space / Enter

    ###
    Array of two arrays for the keys to use as two switches
    Default: [[32, 9], [13]] (9 = 'Tab, 32 = 'Space', 13 = 'Enter')        
    ###
    keys_2:                              [[9, 32], [13]] # Tab + Space / Enter
    
    #keys_3:                             # forward/backward and select
    
    ###
    Time for single switch scanning to move from element to element 
    Default: 1500 milliseconds
    ###
    single_switch_move_time:             1500
    
    ###
    If the single switch movement should restart/go to index 0 when restarted
    Default: true
    ###
    single_switch_restart_on_activate:   true

    ###
    Time after "triggering" a element to it's activated 
    Default: 0
    ###
    delay_before_activating_element:     0

    ###
    Delay before an keypress is "allowed" after last keypress.
    Default: 250 ms
    ###
    delay_for_allowed_keypress:          250;

    ###
    Groups enabled/disabled (If elements should be grouped or run as single elements)
    Default: true
    ###
    groups:                              true;

  ###
  DOM options
  ###
  dom:
    ###
    The class which all elements must have to be a switch controlled element
    The class should be appended with numbers 1,2,3 etc to set order of elements. order is unpredicaable if several
    elements have the same number within a group.
    Default: "switch-element-"
    ###
    element_class:            "switch-element-" # Use classnames such as switch-element-1 switch-element-2 or change this value
    ###
    The jQuery selector from where the first switch element should be searched for.
    Usually this should be body or the first container on the webpage
    Note: Use a selector which selects a single object. Else behaviour is unpredictable
    ###
    start_element_selector:   "body"

  ###
  Other settings
  ###
  # Use .search where you have class="search" or #search for id="search" (jQuery selectors)
  key_filter_skip:        [".search"]
  
  ###
  If set to true, the first link within the element is "clicked".
  Else the actual element is clicked.
  FUTURE feature: (on the todo list) 
  A data attribute can be set on the element in order to override this on a per-element basis
  ###
  activate_first_link:    true # activate element or first link within
  ###
  Enable/Disable debug
  Note: log4javascript must be available if used
  Default: false
  ###
  debug:                  false

  ###
  Visual settings
  ###
  visual:
    ###
    Scroll to ensure the entire element in focus is visible (if possible)
    Default: true
    ###
    ensure_visible_element: true # ensure element is visible on the page

    ###
    The number of pixels for margin to the viewport/window when the element is positioned in the viewport/window
    Default: 15
    ###
    scroll_offset:          15 # offset from top/bottom in pixels for the element

    ###
    Time in milliseconds the scroll will last (set to 0 if instant scroll is preferred)
    Default: 200
    ###
    animate_scroll_time:    200 # time to use for animating scroll
    ###
    The easing to use for animation
    Default: "linear"
    ###
    easing:                 "linear" # easing to use for scrolling

  ###
  Element highlighting using the built in Highlighter object feature
  ###
  highlighter:
    ###
    Use highlighter div element for each element.
    A div is positioned absolute around the element and shown/hidden accordingly
    Default: true
    ###
    use:                      true
    
    ###
    Additional content for the highlighter
    Note: The content is placed within every highlighter and multiple highlighters can be visible at the same time.
          It is best to not use ID's on elements placed inside the highlighter
    Default: ""
    ###
    content:                  ""
    
    ###
    Class for the highlighter
    Default: "highlighter"
    ###
    class:                    "highlighter"

    ###
    The class when a highlighter is active/currently selected
    Default: "current"
    ###
    current_class:            "current"

    ###
    The class when set on a highlighter when activated action is triggered 
    Note: only usable if options.visual.delay_before_activating_element is > 0
    Default: "activate"
    ###
    activate_class:           "activate"
    
    ###
    Margin between the highlighter and the element
    Default: 5
    ###
    margin_to_element:        5

    ###
    Selector to set size on. (Change in case you have content inside the highlighter you wish to highlight)
    ###
    selector_for_set_to_size: ".highlighter"
    
    ###
    Use CSS watch to watch the element for changes in position and dimensions
    This is only needed if you have javascript or other DOM elements 
    that might change the position or size of a switch-enabled element
    Default: false
    ###
    watch_for_resize:         false
    # use_size_position_check:  true
    
    ###
    The ID for the holder for all highlighters. Unlikely to need changing
    Default: "sw-highlighter-holder"
    ###
    holder_id:               "sw-highlighter-holder"

    ###
    Read out the z-index for the element to be highlighted and set to 1 less than the value specified
    on the element.
    If it's set to inherit or auto it will create set z-index 5371 on the element and 5370 on the highlighter
    ###
    auto_z_index:            true

  ###
  Options specific to highlighting
  ###
  highlight:
    ###
    Options specifict to highlighting a switch-element
    ###
    element:
      ###
      The class when a element is active/currently selected
      Default: "current"
      ###
      current_class:         "current"

      ###
      The class when set on a switch-element when activated action is triggered 
      Note: only usable if options.visual.delay_before_activating_element is > 0
      Default: "activate"
      ###
      activate_class:        "activate"

Special data attributes

Two data attributes are supported for single switch. These data attributes have noe effect when using two switches.

data-sw-single-stay

Set this to true to stop scanning when the element is highlighted. The user has to click the single switch to start scanning/move forward

data-sw-single-noaction

Set this to true to skip triggering actions on the element. Unless this option is set, the user have to press twice to move away from a field. First click will activate, second will move

Example

  <div class="switch-element-1" data-sw-single-stay="true">
    <a href"#test">Switch element 1, which will trigger #test anchor and then move to next element upon click</a>
  </div>
  <div class="switch-element-1" data-sw-single-stay="true" data-sw-single-noaction>
    <a href="#test">Switch element 1, first click will move. Anchor #test will never be triggered for single switch.</a>
  </div>

Events

There are four events dispatched that can be listened to:

switch-access-activate

This event is dispatched when a element is activated. Three parameters are sent with the element.

1. The index of the element that has been highlighted/moved to (0-based).
2. The level (group level) of the activated element (0-based), where 0 is root
3. The clicked element (Either the DOM element that is the switch element or a link inside, depending on options)
4. The current element.

switch-access-move

This event is dispatched when a element is moved to (highlighted). Two parameters are sent with the element.

1. The index of the element that has been highlighted/moved to (0-based).
2. The level (group level) of the activated element (0-based), where 0 is root
3. The current element.

switch-access-enter-group

This event is dispatched when a group of switch-elements is entered.

1. The index of the element that is the parent of the highlighted group/objects (0-based).
2. The level (group level) of the highlighted objects
3. The element that is the parent of the highlighted group/objects.

switch-access-leave-group

This event is dispatched when a group of switch-elements is left.

1. The index of the highlighted element (0-based).
2. The level (group level) of the highlighted object
3. The element that is highlighted.

Requirements

jQuery (1.8 or newer)

For development:

log4javascript (http://log4javascript.org) only if debug is set to true

For more easings on the scrolling:

http://gsgd.co.uk/sandbox/jquery/easing/

Browser Compatibility

Chrome Firefox Internet Explorer 9+

License

This work is under either a GPL License or a Commercial license. For commercial usage, please contact (leifcr@gmail.com)