A jQuery plugin for moving up and down between elements.
JavaScript CSS
Switch branches/tags
Nothing to show
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
examples
src
LICENSE
README.md
updown.jquery.json

README.md

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

Copyright

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