Question

A common pattern within jQuery is a method that takes a callback which is passed an element of an array and its index within that array. However, it seems completely random which argument comes first. For example, from the jQuery docs at http://api.jquery.com:

• jQuery.each( collection, callback(indexInArray, valueOfElement) )
• .each( function(index, Element) )
• jQuery.map( array, callback(elementOfArray, indexInArray) )
• .map( callback(index, domElement) )
• jQuery.grep( array, function(elementOfArray, indexInArray), [ invert ] )
• .filter( function(index) )

In three cases (jQuery.each, .each, .map) the index comes first. In the other two (jQuery.grep, jQuery.map) the element comes first. I know the api is now set, but it seems like a gross inconsistency to me.

Is there a pattern I’m missing or is this just random? Should this be fixed or should I just shut up and memorize them?

Answer 1

It is not totally random. Because :

$.map( $('selector'), function(el, index) { /* element (DOMElement) is first, index optional */ } );
$('selector').map(function(index) { /* 'this' (DOMElement) is first.... index optional */ });

See the pattern? The second example has a second argument, but it is only passed by convenience, and it is the same as this.

The pattern is that the first argument is always “more” important than the second, and the last argument should be the least important (the “more optional”). So you don’t need to specify all the least important arguments if you only need one. And in the case of $(...).each, often you won’t even need any argument, because this is only what you want.