adelegard / updown.js

A jQuery plugin for moving up and down between elements.

UpDown.js

UpDown.js is a jquery plugin that provides a flexible way to traverse through containers and their child elements with either keyboard commands or custom events.

Requirements

• jQuery 1.4.2+

Usage

Basic use case:

    $('.some_table').updown('tbody tr');

This will do the following:

1. Add a class of 'highlight' onto the first found 'tbody tr' element within '.some_table'
2. Let you move up and down between these elements (removing and adding the 'highlight' class) with the j/k keys

Advanced use case:

    $('.some_table').updown('tbody tr', {
        skip_selector: '.skip',
        loop: false,
        move_scrollbar: false,
        key_action: 18, // alt
        key_down: [74, 40], // j, down arrow
        key_up: [75, 38], // k, up arrow
        on_action_override: function() {
            $('.last_action').text($('.highlight td:first').text());
        }
    });

This will do the following:

1. Add a class of 'highlight' onto the first found 'tbody tr' element within '.some_table'
2. Skip over elements with the 'skip' class
3. Not loop (once you hit your last 'tbody tr' element going 'down' once more will not jump back to the first 'tbody tr')
4. Not move the scrollbar to keep the current 'highlight' class visible
5. Fire the 'action' event on 18
6. Fire the key_down event on 74 or 40
7. Fire the key_up event on 75 or 38
8. Execute a custom 'action' method on the 'action' event

Demos

1. The Default
2. Skipping and No Looping
3. Keys and Action
4. Buttons
5. Performance

Options

Option Name	Default	Purpose
jump_between	true	whether or not traversal should be made between parent containers
loop	true	whether or not traversal should loop around to the beginning/end of the traversal elements
skip_selector		the selector(s) to skip over during traversal
table_row_helper	false	attempting to account for inconsistent table markup Specifically, tables with their header row as: the first row in the tbody the first row in the table with no thead or tbody
move_scrollbar	true	whether or not the scrollbar should be moved to keep the highlighted element visible
scrollbar_move_additional_px	200	how many additional pixels we should move when keeping the 'highlight_class' visible (in addition to height of 'highlight_class' element)
scrollbar_animate_speed	300	the speed (in milliseconds) of the scrollbar animation
highlight_class	"highlight"	the class to be added to each traversal element
action_window_location_href	true	whether or not the first anchor found in the highlighted element on the action event should be used to navigate the browser to that href
action_selector	' > td > a'	the selector to be used if action_window_location_href is true to navigate the page on the action event
key_event	"keydown"	the jQuery event to listen to for keyboard interaction
key_action	13 (enter key)	the keyboard keyCode that will fire the action event (this action can be overridden using the on_action_override option)
key_down	74 (j key)	the keyboard keyCode that will fire the down event (this action can be overridden using the on_key_down_override option), which by default will move the highlight class down one matching element
key_up	75 (k key)	the keyboard keyCode that will fire the up event (this action can be overridden using the on_key_up_override option), which by default will move the highlight class up one matching element
key_ignore_when_selector	'input:focus, button:focus'	the selectors in which the plugin should take no action if any matching elements are found
on_action_before		an overrideable function that will fire before the action event is fired
on_action_after		an overrideable function that will fire after the action event is fired
on_action_override		an overrideable function that will fire instead of the default action event
on_key_down_before		an overrideable function that will fire before the key down event is fired
on_key_down_after		an overrideable function that will fire after the key down event is fired
on_key_down_override		an overrideable function that will fire instead of the default key down event
on_key_up_before		an overrideable function that will fire before the key up event is fired
on_key_up_after		an overrideable function that will fire after the key up event is fired
on_key_up_override		an overrideable function that will fire instead of the default key up event
jump_between_up_before		an overrideable function that will fire before the jumping up event is fired
jump_between_up_after		an overrideable function that will fire after the jumping up event is fired
jump_between_up_override		an overrideable function that will fire instead of the default jumping up event
jump_between_down_before		an overrideable function that will fire before the jumping down event is fired
jump_between_down_after		an overrideable function that will fire after the jumping down event is fired
jump_between_down_override		an overrideable function that will fire instead of the default jumping down event

That's it! Please note, however, that currently only one usage of the plugin is supported on the page at any given time.

Contributing to UpDown.js

Once you've made your great commits:

1. Fork UpDown.js
2. Create a feature branch
3. Write your code (and tests please)
4. Push to your branch's origin
5. Create a Pull Request from your branch
6. That's it!

Links

• Code: git clone git://github.com/adelegard/updown.js.git
• Bugs: http://github.com/adelegard/updown.js/issues

Copyright

Copyright © 2013 Alex Delegard. See LICENSE.txt for further details.