Tab Override jQuery Plugin
This plugin makes it easy to use Tab Override with jQuery by providing a wrapper for the Tab Override API. In addition, it adds support for delegated events. Code documentation is available at wjbryant.github.io/jquery.taboverride/docs/.
Setup
Download the latest release from the releases page.
Load either jquery.taboverride.js
or jquery.taboverride.min.js
in your
project. These files can be found in the build
directory.
This project is also hosted on the jsDelivr CDN. See http://www.jsdelivr.com/#!jquery.taboverride for more information.
Dependencies
The latest version of the plugin requires:
- jQuery v1.7.0+
- Tab Override v4.0.0+
Bower
This plugin is registered as jquery.taboverride
in the global Bower
registry. Install Bower via npm and then
run this command from the root directory of your project to install the plugin:
bower install jquery.taboverride
This will download the Tab Override jQuery plugin and all of its dependencies
into a components
directory in your project.
AMD
This plugin is AMD compatible and can be loaded using a script loader such as RequireJS.
Optimization
To safely concatenate the plugin with the taboverride
core module, it is
recommended to use the RequireJS optimization tool,
r.js, like so:
r.js -o name=jquery.taboverride out=jquery.taboverride.combined.min.js paths.jquery=empty:
Note: The above command assumes both files are in the same directory. On Windows,
you may have to use r.js.cmd
instead.
CommonJS
This plugin is also compatible with CommonJS module systems.
Usage
The jQuery plugin is simply a wrapper for the Tab Override public API. It can be used as follows:
Enable/Disable Tab Override
// enable Tab Override by calling tabOverride() with no arguments
$('textarea').tabOverride();
// or any truthy argument
$('textarea').tabOverride(true);
// disable Tab Override using any falsy argument
$('textarea').tabOverride(false);
Delegated Events
The jQuery plugin also supports delegated events. Simply specify a selector string as the second argument:
// enable Tab Override for all textareas on the page,
// including textareas that are dynamically generated
$(document).tabOverride(true, 'textarea');
The plugin can then be disabled using the same syntax:
// disable Tab Override
$(document).tabOverride(false, 'textarea');
Get/Set Tab Size
// get the current tab size (0 represents the tab character)
var tabSize = $.fn.tabOverride.tabSize();
// set the tab size to the tab character (default)
$.fn.tabOverride.tabSize(0);
// set the tab size to 4 spaces
$.fn.tabOverride.tabSize(4);
Get/Set Auto Indent
// get the current auto indent setting
var autoIndentEnabled = $.fn.tabOverride.autoIndent();
// enable auto indent
$.fn.tabOverride.autoIndent(true);
// disable auto indent (default)
$.fn.tabOverride.autoIndent(false);
Get/Set Key Combinations
// get the current tab key combination
var tabKeyCombo = $.fn.tabOverride.tabKey();
// get the current untab key combination
var untabKeyCombo = $.fn.tabOverride.untabKey();
The key combinations used for tabbing and untabbing can be customized. If accessibility is a concern, it is recommended to set key combinations that are not mapped to any action by default.
Setting the key combinations is done by calling the tabKey()
or untabKey()
method with arguments. The first parameter is the key code (number
) of the
key. The second parameter is optional and specifies modifier keys (alt
, ctrl
,
meta
, shift
) as an array of strings.
// set the tab key combination to ctrl+]
// and the untab key combination to ctrl+[
$.fn.tabOverride
.tabKey(221, ['ctrl'])
.untabKey(219, ['ctrl']);
The default tab key combination is: Tab
. The default untab key combination is:
Shift + Tab
. These combinations can be set like this:
// reset the default key combinations
$.fn.tabOverride
.tabKey(9)
.untabKey(9, ['shift']);
Hooks
This plugin creates the following hooks for adding extension functions via the
tabOverride.addExtension
method.
setDelegated - Called when Tab Override is enabled or disabled using a delegated event
Parameters:
-
$container
- the jQuery object for the container element(s) -
selector
- the selector string used to select the textareas in the container -
enable
- whether Tab Override was enabled or disabled
addDelegatedListeners - Called when the event listeners for delegated events are added
Parameters:
-
$container
- the jQuery object for the container element(s) -
selector
- the selector string used to select the textareas in the container
removeDelegatedListeners - Called when the event listeners for delegated events are removed
Parameters:
-
$container
- the jQuery object for the container element(s) -
selector
- the selector string used to select the textareas in the container
Utility Methods
The jQuery plugin provides utility methods under the $.fn.tabOverride.utils
namespace. These are separate from the Tab Override library utility methods
found under tabOverride.utils
.
addDelegatedListeners
removeDelegatedListeners
Documentation on these methods is available in the code documentation.
Additional Notes
When used as setters, the settings methods can be chained together:
// set up Tab Override
$.fn.tabOverride.tabSize(4).autoIndent(true);
Utility methods under the $.fn.tabOverride.utils
namespace are not chainable.
License
MIT license - http://opensource.org/licenses/mit