Hi, I’m jQuery++.
I am a MIT licensed collection of extremely useful DOM helpers and special events for jQuery 1.8 and later. I’m not a UI project like jQuery UI or jQuery Tools. Instead, I’m all about providing low-level utilities for things that jQuery doesn’t support. If Underscore is jQuery’s functional-programming tie, I am jQuery’s bald-spot covering toupee.
Learn more about how I can be useful to you. If you think I should have other utilities, let me know on the forum. If you like me, check out my sister library CanJS. Finally, my apologies about talking about myself in the third person from this point forward.
There are several ways to get and setup jQuery++:
- using the download builder
- using individual files
- using Steal
- using AMD
Using the download builder
Simply select the files you want and click “Download”. This will create and download a
with all the files you selected and their dependencies. Load this script
after jQuery 1.8 like:
The files to load the jQuery++ plugins with an AMD module loader like RequireJS, are located in the
amd/ folder of the full download.
jquerypp/ folder in your module directory and load a plugin like this:
You might have to map the
jquery module name to the name of your jQuery AMD module. In RequireJS like this:
Note: Starting at version 1.7 jQuery will define itself as an AMD module if a loader is available. There is no need to create a wrapper anymore.
$(el).animate(properties, [speed], [callback]) -> jQuery
$.fn.animate to use
CSS 3 animations if possible.
It takes the same arguments as the original $.fn.animate and will fall back to
A fade-in effect can be implemented like this:
Since CSS transitions are implemented natively in the browser and can make use of hardware acceleration, animations will perform a lot better, especially in Webkit based mobile browsers (iPhone, iPad, Android).
$(elA).compare(elB) -> Number
$.fn.compare to compare the position of two nodes. It returns a number that represents a bitmask showing how they are positioned relative to each other. The following list shows the
bitmask, the number and what it means for a
$.fn.compare call like
000000-> 0: Elements are identical
000001-> 1: The nodes are in different documents (or one is outside of a document)
000010-> 2: #bar precedes #foo
000100-> 4: #foo precedes #bar
001000-> 8: #bar contains #foo
010000-> 16: #foo contains #bar
You can tell if
This is useful to rapidly compare element positions which is common when widgets can reorder themselves (drag-drop) or with nested widgets (trees). In the following example, select two elements to see how they compare to each other and what bitmask the result represents:
$.cookie(name, [value], [options]) -> Object|String
The following options are available:
expires- the expiration time in days or an expiry date
domain- the domain name
path- the value of the path for the cookie
secure- if the cookie requires HTTPS
The example uses
jQuery.cookie and formParams to persist a form to a cookie. You can save the form
or load it from the value stored in the cookie. At the bottom it shows the current cookie value after running it through
$(form).formParams([convert]) -> Object|jQuery
true, values that look like numbers or booleans will be converted and empty strings won’t be added to the object. For a form like this:
It is also possible to set form values by passing an object:
Update the form in the following example to see a JSON representation of the object returned by
$.Range([el]) -> range
$(el).range() -> range
Use jQuery.Range to create, move and compare text ranges. Use
$.Range.current() to get the currently selected text range.
$(el).range() returns a text range on an element.
For example, for an element like
<div id="text">This is some text</div>,
$.Range can be used like this:
$.Range instance offers the following methods:
- range.clone() -> range - clones the range and returns a new $.Range object
- range.collapse([toStart]) -> range collapses a range
- range.compare(type, other) -> Number - compares one range to another range
- range.end([val]) -> range|Object - sets or returns the end of the range
- range.move(type, referenceRange) -> range - move the endpoints of a range relative to another range
- range.overlaps(other) -> Boolean - returns if any portion of these two ranges overlap
- range.parent() -> HtmlElement|Element|Node - returns the most common ancestor element of the endpoints in the range
- range.rect(from) -> TextRectangle - returns the bounding rectangle of this range
- range.rects(from) -> Array - returns the client rects
- range.start([val]) -> range|Object - sets or returns the beginning of the range
- range.toString() -> String - returns the text of the range
The following example uses
- Show the start end end offset of the selection
- Show the selected plain text
- Add a green border on the left to the start element
- Add a red border on the right to the end element
- Put a dotted outline around the parent element
$(el).selection([start], [end]) -> Object|jQuery
$.fn.selection to set or retrieve the currently selected text range. It works on all elements:
The following example shows how
$.fn.selection can be used. Initially the selection is set from position eight to 12. You can change the selection in the highlighted area and the status text will be updated:
$(el).within(left, top, [useOffsetCache]) -> jQuery
$.fn.withinBox that return all elements having a given position or area in common. The following example returns all
div elements having the point 200px left and 200px from the top in common:
$(el).withinBox(left, top, width, height) to get all elements within a certain area:
Move the mouse in the following example and it will show the ids for
div elements within the current mouse position:
jQuery.event.drag uses jQuery.within to determine dropable elements at the current position.
Note: The destroyed event does not bubble.
jQuery.event.drag adds delegatable drag events to jQuery:
dragdown- the mouse cursor is pressed down
draginit- the drag motion is started
dragmove- the drag is moved
dragend- the drag has ended
dragover- the drag is over a drop point
dragout- the drag moved out of a drop point
An element will become draggable by attaching an event listener for one of these events on it. A simple slider can be implemented like this:
Which looks like this in action:
drag object (passed to the event handler as the second parameter) can be used to modify the drag behavior:
- drag.cancel() -> undefined - stops the drag motion from happening
- drag.ghost() -> jQuery - copys the draggable and drags the cloned element
- drag.horizontal() -> drag - limits the scroll to horizontal movement
- drag.only([only]) -> Boolean - only have drags, no drops
- drag.representative(element, offsetX, offsetY) - move another element in place of this element
- drag.revert(val) -> drag - animate the drag back to its position
- drag.step(pixels) -> drag - makes the drag move in steps of amount pixels
- drag.vertical() -> drag - limit the drag to vertical movement
- drag.limit(container, center) -> drag - limit the drag within an element
- drag.scrolls(elements, options) -> undefined - scroll scrollable areas when dragging near their boundaries
jQuery.event.drag with delegatable drop events:
dropinit- the drag motion is started, drop positions are calculated
dropover- a drag moves over a drop element, called once as the drop is dragged over the element
dropout- a drag moves out of the drop element
dropmove- a drag is moved over a drop element, called repeatedly as the element is moved
dropon- a drag is released over a drop element
dropend- the drag motion has completed
The following example adds the
highlight class when a drag is moved over the element and removes it when it leaves:
drop object offers the following methods:
- drop.cancel() -> undefined - prevents this drop from being dropped on
- drop.cache() -> undefined
- call on
dropinitto cache the position of draggable elements
When adding drop-able elements after
dropinit, for example when expanding a folder view after hovering over it with a draggable for a while, $.Drop.compile() needs to be called explicitly to update the list of dropable elements (this happens automatically on
The following example shows two draggable elements and a drop area. When a drag starts it will create a copy of the element using
drag.ghost(). The drop area will be highlighted when the drag moves over it and update the text when it is dropped:
jQuery.event.hover provides the following hover events:
hoverinit- called on mouseenter
hoverenter- an element is being hovered
hovermove- the mouse moves on an element that has been hovered
hoverleave- the mouse leaves the hovered element
An element is hovered when the mouse moves less than a certain distance in a specific time over the element. These values can be modified either globally by setting
$.Hover.distance or individually during
You can also set
hover.leave(time) to set a time that the hover should stay active for after the mouse left.
The following example shows
jQuery.event.hover with different settings for distance, delay and leave:
jQuery.event.key adds a
.keyName() method to the event object that returns a string representation of the current key:
The following key names are mapped by default:
\r- enter key
' '- space
0-9- number key pressed
a-z- alpha key pressed
num0-9- number pad key pressed
f1-12- function keys pressed
The following example shows the keyname for
keypress events on the input field:
jQuery.event.pause adds a default event handler,
event.resume() for pausing and resuming event propagation and
$.fn.triggerAsync for triggering an event asynchronously and executing a callback when propagation is finished.
This is very useful for creating event oriented jQuery widgets that provide default behavior for certain events. A widget user can intercept any of these events, pause it and perform other actions before resuming the default action or prevent it entirely.
The following example implements a
tabs widget using CanJS. Each tab panel contains a form to input data. When the form data changes and you go to another tab it will ask you to save these changes before moving on. This will pause the tabs
hide event until you either confirmed or declined to save the form. On cancel the event will be prevented and the widget will stay in the current tab:
$(el).triggerAsync(event, [success], [prevented])
jQuery.fn.triggerAsync triggers an event and calls a success handler when it has finished propagating through the DOM and no handler called
event.preventDefault() or returned
false. The prevented callback will be used otherwise:
jQuery.event.default adds default event handlers. A default event runs when all other event handlers have been triggered and none has called
event.preventDefault() or returned
false. Default events are prefixed with the
default namespace. The following example adds a default
pause and resume
Pausing an event works similar to .stopImmediatePropagation() by calling
event.resume() will continue propagation. This is great when doing asynchronous processing in an event handler:
jQuery.event.resize allows you to listen to
resize events on arbitrary elements. Unlike other events that bubble from the target element to the document the
resize event will propagate from the outside-in.
This means that outside elements will always resize first. Trigger the
resize event whenever the dimensions of an element change and inside elements should adjust as well.
The following example will always resize to it’s full parent width and height
resize event makes creating application like layouts a lot easier. The following example creates a common layout with top, left, right and center elements within a container. Use the blue square to resize the outside container. The
resize event will take care of adjusting the dimensions of the inside elements:
jQuery.event.swipe adds support for swipe motions providing the delegatable
jQuery.event.swipe.delay to the maximum time the swipe motion is allowed to take (default is 500ms).
Swipe (using the mouse) in the green area in the following example to see the direction of the swipe:
This site highlights the most important features of jQuery++. You can find the full API documentation on the DoneJS documentation page.
There are also several places you can go to ask questions or get help debugging problems.
Follow @jquerypp for updates, announcements and quick answers to your questions.
Visit the Forums for questions requiring more than 140 characters. DoneJS has a thriving community that’s always eager to help out.
The DoneJS IRC channel (
#donejs on irc.freenode.net) is an awesome place to hang out with fellow DoneJS users and get your questions answered quickly.
__Help Us Help You __
Help the community help you by using the jQuery++ jsFiddle template. Just fork it and include the URL when you are asking for help.
Get Help from Bitovi
Easy to use
jQuery++ does things the jQuery way, which makes it really easy to learn if you are already familiar with jQuery. Get functionality that was always tricky to implement from one coherent library:
- Serialize forms into objects with formParams
- Drag & drop events - no need for jQuery UI
- Resize elements the right way
- Listen to swipe events for mobile apps
Some jQuery++ plugins can help to significantly speed up your applications. Use
- compare to quickly compare element positions
- destroyed to avoid memory leaks and keep your references up to date when elements get removed from the DOM
jQuery++ is developed by Bitovi. We’re active on the forums, but should the need arise, can also be hired for paid support, training, and development.
To develop jQuery++, add features, etc, you first must install DoneJS. DoneJS is the parent project of jQuery++ and the 4.0 version of JavaSciptMVC. It has DocumentJS and Steal as submodules that are used to generate the documentation and build the jQuery++ downloads.
Clone DoneJS with:
git clone git://github.com/bitovi/donejs
Install all submodules by running
cd donejs git submodule update --init --recursive
Depending on your version of git, you might need to cd into each submodule and run
Fork jquerypp on Github
Add your own fork as a remote in the
cd jquery git checkout master git remote add fork [email protected]:<username>/jquerypp.git
After installing jQuery++ and DoneJS, you’ll find
the jQuery++ files in the
jquery folder. Within
jquery, the plugins are located in the
For each plugin (for example
jquery/dom/compare) you will find:
compare.html- A demo page
compare.js- The actual commented and uncompressed source code
compare.md- The overview page (used in the generated documentation)
compare_test.js- The plugin tests
qunit.html/funcunit.html- The unit and/or functional tests
To develop jQuery++:
- Edit the plugin’s file.
- Add tests to the plugin_test.js test file.
- Open the plugin test page
funcunit.htmland make sure everything passes
- Open the big test page in
jquery/qunit.htmland make sure all tests pass
- Commit your changes and push to your fork (
git push fork <branch>)
- Submit a pull request!
To edit jquerypp.com, installing jQuery++ and DoneJS is not necessary. Simply fork and edit the github pages’s index.md page online. Don’t forget to submit a pull request.
To edit the documentation at DoneJS.com:
- install jQuery++ and DoneJS.
- Edit the markdown and js files in the
donejsroot folder generate the docs with:
View them at
- Submit a pull request.
Making a build
To make a jQuery++ build, run:
It puts the downloads in
jquery/dist. To build a specific version check out the git tag
you want to build and run the above command.
List of heroes
The following lists everyone who’s contributed something to CanJS. If we’ve forgotten you, please add yourself.
callumacrae - Width property for jQuery.selection and documentation fixes. fabianonunes - Fixed several errors in the build process. jbrumwell - Added several useful features for drag/drop events and jeffrose - 1 iamnoah - 1
1.0.1 (February 6th 2013)
- fix: Force hover leave on new mouseenter
- fix: Removing the element being hovered prevents all future hoverenter
- fix: hover.leave != 0 prevents hover of next element with same selecto
- fix: Changing jQuery references to local $
- fix: Breaks in jQuery.noConflict(true) Scenario
- fix: Can’t download drag.limit, drag.step, and drag.scroll from downloader on website
- feature: jQuery 1.9.x support
- feature: Added to the new jQuery plugin repository
1.0.0 (November 20th 2012)
- feature: jQuery 1.8.0+ compatibility
- feature: dragcleanup event
- feature: Reverse and move event
- fix: pass through scrollTop in animate
- fix: Fastfix: Original can be undefined
- fix: Animate Scroll not working
- fix: .stop() does not stop callbacks from being executed
- fix: jQuery.event.swipe.max isn’t actually being used
- fix: Range triggers error on IE8
- fix: [FormParams] convertValue function: Null value to undefined (Internet Explorer Fix)
- fix: HoverInit delay 0 does not trigger hoverenter if immediately moused out
1.0 Beta 2
- feature: Key mapping tool for jQuery.event.key for international characters
- fix: jQuery.formParams converts disabled fields
- fix: jQuery.animate supports all parameters
- change: jQuery.event.drag supports touch events
- fix: jQuery.animate .stop() doesn’t work
- fix: Bug with duplicate sub keys
- change: Added width property to jQuery.selection
- fix: Security error in jQuery.animate
1.0 Beta (June 1st 2012)