Map iterates over a collections and applies a function to each element - returning a new, usually modified, list. Our tests will examine jQuery's "inline" map with it's global $.map map, and JavaScript's native map function. The object (no pun intended) is to see how each implementation varies in terms of the parameters and the value of this we get each iteration, and how they handle weird arrays.

Our initial task will to be to turn a list of <li> tags into an array of numerical values that each element contains. The input will therefore be:

<ul id="list">
  <li>1</li>
  <li>2</li>
  <li>3</li>
</ul>

And the required output is a simple JavaScript array:

[1, 2, 3]

jQuery likes to keep things jQuery-y, so some of the outputs (and inputs) will be wrapped in the jQuery function (i.e. jQuery(1, 2, 3) instead of [1, 2, 3]). Chrome's logger will show both the values as [1, 2, 3] - but if you tried to .reverse a jQuery object it's going to die - so if you need to get at the underlying array from a jQuery object then used the .get method: jQuery(1, 2, 3).get().

The code for the tests is up on GitHub. I've abstracted the tests a bit for code readability, but I'll list the "long version" here so it makes more sense out of context. Each method will print the collection ("Input"), the this value and arguments ("args") for each item iteration, and the result ("Output").

Ok, let's run some tests...

Ex 1a: inline jQuery map

$("#list li").map(function(){
  return parseInt($(this).text(), 10);
});

Input: jQuery(li, li, li)
this: <li> args: [0, li]
this: <li> args: [1, li]
this: <li> args: [2, li]
Output: jQuery(1, 2, 3)

Ex 1b: global jQuery map

$.map($("#list li"), function(el){
  return parseInt($(el).text(), 10);
});

Input: jQuery(li, li, li)
this: DOMWindow args: [li, 0, undefined]
this: DOMWindow args: [li, 1, undefined]
this: DOMWindow args: [li, 2, undefined]
Output: [1, 2, 3]

There are some notable differences between the two jQuery methods. The inline version scopes to the list, so this is the element, and the first argument to the callback is the element's index. The second is the same as this (for some reason).

The global version scopes to the document window. To get the element you need to look at the first parameter. The index is the second, and we get a handy undocumented reference to undefined as the third. (I really should have a squizz at the jQuery source code to see what is going on here). The global map also returns us a real JavaScript array - not a jQuery array-like array.

Ex 1c: JavaScript map over array

$("#list li").get().map(function(el){
  return parseInt($(el).text(), 10);
});

Input: [li, li, li]
this: DOMWindow args: [li, 0, [li, li, li]]
this: DOMWindow args: [li, 1, [li, li, li]]
this: DOMWindow args: [li, 2, [li, li, li]]
Output: [1, 2, 3]

The native JavaScript map gives us an output that looks like the global jQuery map - except we get something a bit more useful as the third parameter: the original collection. The original collection in this case is the .get() value of the jQuery selection - that is, a real array. But it works over a jQuery collection too, if we apply it - as in the following example...

Ex 1d: JavaScript map over jQuery collection

Array.prototype.map.call($("#list li"), function(el){
    return parseInt($(el).text(), 10);
});

Input: jQuery(li, li, li)
this: DOMWindow args: [li, 0, jQuery(li, li, li)]
this: DOMWindow args: [li, 1, jQuery(li, li, li)]
this: DOMWindow args: [li, 2, jQuery(li, li, li)]
Output: [1, 2, 3]

That was just to show the output was the same with the jQuery input. The native map also lets you specify an optional parameter after the callback function to scope the map too - rather than the DOMWindow object.

There are a few things in common with each implementation: they all have a way to access the element and the element's index (zero offset), and none of them mutate the original collection. It's not hard to figure out the differences and adapt your style - but it's not all rosy once we leave the land of jQuery...

Holey arrays, batman

All three map implementations work over regular ol' arrays. However, regular ol' arrays in JavaScript have a tendency to not be that regular at all: we can have null values, and "holes" that can trip up our brave iterators.

var holey = [ "1", "2", null, ["4a", "4b"], , "6"];

Output: ["1", "2", null, Array[2], undefined, "6"]

Here we have an array that is pretty funky. It's got strings, and nulls, and arrays, and holes. First we'll look at how our maps index such a quirky beast:

Ex 2a: jQuery global map-to-index

$.map(holey, function(el, index){
    return index;
});

Output: [0, 1, 2, 3, 4, 5]

Ex 2b: JavaScript map-to-index

holey.map(function(el, index){
    return index;
});

Output: [0, 1, 2, 3, undefined, 5]

Oh kay... be careful there - our "hole" is not processed by the native map, so we get no value for index, which results in a big fat undefined in the middle. Best keep that in mind.

Finally, we'll look at what happens if we map the elements to themselves.

Ex 2c: JavaScript map-to-element

holey.map(function(el){
    return el;
});

Output: ["1", "2", null, ["4a", "4b"], undefined, "6"]

Ex 2d: jQuery global map-to-element

$.map(holey, function(el){
    return el;
});

Output: ["1", "2", "4a", "4b", "6"]

Errrgh... Um, wow? Native JavaScript acts as (I) expected, but there's something peculiar happening in the world of jQuery. Actually, if you consult the docs then you'll see it's not a flaw but a feature. Null values are dropped from the resulting map, and any arrays are flattened one level (if fact, if you need to combat that you can return the element wrapped in an extra array).

That's a wacky feature - map is actually a flatmap and filter type thing in jQuery. So make sure you know what you're doing before you go playing with JavaScript arrays with them!

Ok. That'll do us for now. Things get even more funky if you delete items during a loop, but if you're doing that then you're on your own. In the next post we'll have a look at some map/reduce/filter/etc methods in action, and we'll see why it's important to have dissected poor old map. See you then.

jQuery long fade test

If you open up Activity Monitor and click the "big fade" button, the screen will slowly fade in (to background colour #bada55, naturally) and your CPU will say bye-bye. Similarly, if you fade in a bunch of items over a long time you'll see a pretty serious drain too.

I haven't gone looking over on the mailing lists to see if this is a "known issue", or started digging into the source, 'cause I'm a lil' pressed for time at the moment - but if you found this page while googlin' to fix your fading woes, I feel your pain and will tell you to do what I shoulda done: use CSS transitions!

Finally, while checking I used the correct spelling of "whittling" I found this statement on the official whittling website:

Welcome to the world of whittling, a hobby for some, an obsession for others, a joy for all.

I'm a fan of whittling and all, but that just seems like a logical fallacy to me.

But if you're the betting type, I'd be putting my dollar on a free jQuery book - because if the SitePoint search results are anything to go by, we've got it in the bag...

The book opens with what we might assume to be the present day. A sense of tension and foreboding seeps from the text as we are introduced to the perils and dangers of cross-browser Web development. A likeable and handsome protagonist - the reader - emerges from darkness and attempts to harness the powers of jQuery to overcome these obstacles. By the end of the piece, our hero has changed: the naivety and timidness replaced with a quiet strength - an enchanting energy that knows no boundaries.

At least, that's what I got out of it. If you wanted to ignore the sub-text then I guess you'd just say it was a kick-ass jQuery book.

I'll conclude this review by saying that it is possibly the most important work released in the last 500 years, and leave you with an appropriate quote from Australian television personality, John Safran:

If you're not writing your own reviews, then you don't deserve to be famous.

To prove it could work, here's an early proof-of-concept to hopefully pique your interest. It'll take us a few posts to get there - but that was just something I cobbled together (and the perspective is messed up)... it will be even cooler when we arrive!

Now, I know at this point you're probably pretty excited - but I should warn you up front, I have a poor track record of following through on promises of "multi-part" tutorials. To this day I still receive threatening, tearful emails wondering when "part 3" of my 3d with HTML5 will be complete. But I can promise you this: we may not end up with a game, but we WILL end up with at least a cool curvey racetrack with some cars on it. Even if it runs at 2 frames a second.

Anyhoo, let's get on with it. In this first part we'll get everything set up and our screen-drawing animation technique in place. In the next part we'll add racing stripes: and then things get awesome.

But first of all, a back-story. Over the course of my illustrious JavaScript tinkering days I've implemented countful "classics": Pong, shoot'em ups, platformers, Tetris... all the basics. When deciding on what to waste my time on next I started wondering about the ol' racing games of the past and how they worked. I spent a fair chunk of time trying to figure it out in my head... line drawing and curve algorithms and so forth. But I concluded that there must be some trick - no way could the C64 redraw a full bitmap screen so fast?! How could it be done?! It started to hurt my brain, and I was all set to give up... when out-of-the-blue a friend emailed me this tome of enlightenment.

Everything you've ever wanted to know about old racing games but were too stupid to figure out on your own! And of course, behind the technique is a genius-ly simple trick: take a flat image of a "perspective-style" road trailing off into the distance. Break the road into the individual lines that make up the image, then move those lines left or right as required to create the illusion of a curving road! Now, after pouring over Lou's Pseudo 3d Page v0.9 I've managed to get a racer-style road working (and looking very cool)... but I have probably misunderstood some of the finer points of his writings - so this might not be the nicest way to do it. But it's a start, hey!

The first thing that isn't really mentioned in the article, but I think needs to be done is to make the road image quite a bit wider than the view port - so that when the road "curves" sharply, and you position the line's X position waaaay out to one side, the line doesn't stop in the middle of the screen - thus revealing the whole trick. Click on the image below to see the road graphic we'll be using. There are two "roads" which we'll intersperse to create the stripey-road effect.

I've joined the two road graphics together so we can manipulate it as a CSS sprite. As you'd expect, HTML and CSS don't really give us a nice way to manipulate the lines of an image individually. We're going to need to do some trickery: add a couple of hundred 1 pixel-high div elements to the page, and assign them all the same background image. Then we'll offset the background image position to show the correct line for that part of the road! Dodgy, but cool!

Right, some code... Here's some "base" HTML for those following along at home: Racer v0.0.0.0, but there's nothing special in it - feel free to start your own.

#board{
	width:320px;
	background-color:#008ace;
}
.line{
	width: 320px;
	height: 1px;
	overflow: hidden;
	background:transparent url(road.png) no-repeat 0 0;
}

The "board" will be our main screen div element, and the line class will be the individual lines of the screen. You'll need to grab a copy of the road.png file from above. Next, we'll set up our object literal to hold all the game details in. This is our game "controller" and ensures we play nicely with any other JavaScript on the page.

var tracks = {
	num_strips: 220,
	half_num_strips: 110,
	strips : [],
	init : function(){
		// Set up the screen, then...	
		// Start the animation running	
		setInterval( function(){ tracks.update() }, 200 );
	},
	update : function(){
		// Update the screen
	}
};

We aren't doing anything yet - just setting everything up. Our tracks object will be responsible for setting up the screen, and then updating it every 200 milliseconds. We've also defined a few properties at the top: num_strips, half_num_strips, and strips. The strips array will hold a reference to each of the 1 pixel-high lines of the screen. The num_strips property defines how many pixels high the entire screen will be, and the half_num_strips is just half that: it saves us having to calculate num_strips / 2 all over the place (which is important in some of our loops!).

Right, let's draw the initial screen then shall we? Inside the init function, we want to make a loop that appends as many 1 pixel-high div elements that fit on our screen, and keep a reference to them for later.

// Draw the screen lines
for( i = 0; i < this.num_strips; i++ ){
	var strip = $( "<div></div>" ).addClass( "line" ).appendTo( "#board" );
	this.strips.push( strip );
}

Now we have 220 div elements squished inside the #board container div! To see it in action, you'll need to fire the tracks.init function in your document-ready handler:

$(document).ready(function(){
	tracks.init();
});

If you inspect the #board element with Firebug you'll see that there are hundreds of divs - but why isn't the first line of the image appearing in each div? Well, because I made the first line of the image transparent, 'cause I'm too lazy to do things properly. As always when you're being too lazy, it comes back to bight us later. But if you change the "no-repeat 0 0" in the css declaration to "no-repeat 1 0" or something like that, then you should see the repeated line fill the screen.

Having the same line repeated is not what we want though - we want to draw the entire road on screen. We'll have to do some math. In Lou's article he describes everything happening upside down - you draw the screen from the bottom to the top. I decided to do this too... it's going to make things scary later on when we get to "hills", but too bad. In the update function (which is being called every 200 milliseconds) we will set each line to its correct position. We know that (for now) we only have to draw from the bottom of the screen to half way up the screen (where the horizon starts), so we'll only loop over these lines. Inside the loop we'll calculate how far we need to move the background image to draw the correct line.

// Update the bottom half of the screen
for( var i = this.num_strips - 1; i >= this.half_num_strips; i-- ){
	var tex = 111;
	var y_off = ( i - ( this.half_num_strips ) ) + tex;

	this.strips[ i ].css( "background-position",  "-345px -" + y_off + "px"	);
}

Inside the loop we figure out the Y position for each screen line. The tex (for "texture") variable will be used later when it comes time to figure out how to draw the "racing stripes" on the road. The Y position offset is used to alter the background position of the image - so that the correct line is drawn in the correct place. The tex variable adds 111 pixels to the background image - that's why we see the bottom road. If you change it to 1, then you'll see it draws the top screen. Now, if you're feeling adventurous, change it to var tex = Math.random() < 0.5 ? 1 : 111; to get an idea about how the next tutorial will work!

The last thing we'll do is add a car, for good luck. It's just an image I ripped out of Pole Position. Looks lovely though. We'll define it with some CSS:

.car{
	width:90px;
	height:33px;
	background:transparent url(car.png) no-repeat 0 0;
	position:absolute;
	top:190px;
	left:122px;
}

And then in the init function (after the screen set up, and before the timer) we'll add it to the page with jQuery:

// Draw the car
var car = $( "<div></div>" ).addClass( "car" ).appendTo( "#board" );

Have a look at what we've got so far. Nothing spectacular - and hardly ANY jQuery... but the basics are in place and the scene is set. Have a play with all the variables and CSS properties we've set, and join me next time as we continue to push jQuery far in to the distant past!

Say we have an unordered list of items:

<ul id="tags">
	<li>jQuery</li>
	<li>Javascript</li>
	<li>reference</li>
	...
</ul>

The user can click on a list item to select it. When a click happens, we need to find out what the item's index is, relative to all its siblings....

$("#tags li").click(function(){
    alert( "Hi, I'm element " + $(this).index() );
});

That's all there is to it. Super useful!

Ok, here's something you'll want to refer to daily... the current status of the jQuery 1.4 "TODO list", or as I like to call it, "Report 37". Usually when people on the jQuery dev lists ask "When will jQuery 1.4 be ready?" they are met with a resigned (resigned not resiged) answer: "When it's ready". But we don't have to take that kind of glib-ness anymore...

Now we can go and consult good ol' Report 37 any time we need an ETA on 1.4. The method is simple: when all the red and white stripes turn light blue - then jQuery's ready to go! Of course, looking at all those lines takes up precious time and brain space - so I've compacted the data into a single image, so you can see how things are going at a glance.

Assuming this page has completed loading without JavaScript errors (a big assumption), you should see the Licorice Allsort graph to the right. The black lines mark the different components of the jQuery build: Ajax, Core, Event, FX, etc... The coloured lines are the status of the tickets. We want everything to turn blue, if only so there isn't so much pink on my blog.

To make the pretty pictures, I grab the report once a day, and dump it on my server. Then your browser goes all jQuery on it - loading it in and extracting relevant colour information. Then the super awesome Raphael SVG library makes some pixels, and we all have a cup of tea.

Of course, you won't have "1000" popping up... you'll have "added" or "removed" or "dugggg" or something a bit useful to the end user. I don't care about end users, so I'll have "1000".

In the spirit of trying to get the effect to take over the web, I thought I'd throw together a jQuery plugin for sticking them on your site. The jquery.oneup.js plugin is very straightforward - it just animates an element upwards while fading out: 1UP style! To use it, just make your typical notification element position:relative, or position:absolute - whatever it takes to make it movable! (I'll fix this in the next version). For the demo, I've styled my notification message like so:

...
<input type="submit" id="go" value="go" />
<span id="loadn">load</span>
...
#loadn{
	position:relative;
	left:-30px;
	top:-4px;
	display:none;
}

The element then sits "invisibled" over the "go" button, ready to fly... Next we wire up our 1UP functionality with the plugin:

$("#go").click(function(){
	$("#loadn").oneUp();
});

YES! That is so cool: check it in action. The plugin accepts parameters speed (as a jQuery time - like, 'slow', 'fast' or 1000) and distance (how many pixels it travels upwards). You can also specify a callback if you need to do something after the notification completes (like in the demo).

Well, I'm pretty stoked with this turn of events. I've got to go back through every single site I've ever done and add way-too-many of these lil' fellows in. The jquery.oneup.js plugin needs a bit of work: so it handles positioning all by itself, and so forth... I'll let you know as soon as that's done. But in the mean time, I've got a highscore to go beat...

After finally getting fed up of saying "...just use the live/live event", @twalve realised that our heros are merely a single tweet away and hit up Brandon Aaron for the answer... and here it is:

live as in "live broadcast" :)

I'll sleep well tonight.

This idea seemed pretty wacky to me, and made me smile: jQuery events attach themselves to DOM elements - wrapping a JavaScript object in the jQuery selector seemed ludicrous - I mean, should I be able to do $(class).hide()?! No, of course not. But none the less, my curiosity got the better of me, and I tried this lil' snippet:

function cPerson( name, age ){
	this.name = name;
	this.age = age;

	$( this ).bind( "yell", function(){
		alert( this.name + " is " + this.age + " years old!!" );
	})
}
var person1 = new cPerson( "Bob", 32 );
$( person1 ).trigger( "yell" );

To my astonishment, it worked! The custom event fired! I quickly delved into the jQuery source to find out how it handled the object. Skipping through all the regular selector handlers, our object gets converted into an array like so:

return this.setArray(jQuery.isArray( selector ) ?
			selector :
			jQuery.makeArray(selector));

Which is also how other objects like "document" and "window" get handled. Ahh yeah, document and window... it's not that ludicrous after all. I tested it on functions which, I reasoned, should also work - but alas there is a path in the jQuery selector code that says:

if ( jQuery.isFunction( selector ) )
	return jQuery( document ).ready( selector )

So functions fall through to the document.ready shortcut code. Ah well.

But wait, what else can we do with a wrapped instance of an object? Obviously "slideDown()" is a bit stupid? And clone(), appendTo(), wrapAll() etc. don't make sense... how abooouut... data? or plugins?!

$.fn.misterise = function(){
  	return this.each(function() {
 		this.name = "Mr " + this.name;
		this.name += $(this).data( "surname" ) || "";
	});
};

var person1 = new cPerson( "Bob", 32 );
var person2 = new cPerson( "Dave", 27 );
var peeps = [ person1, person2 ];

$( peeps )
	.data( "surname", " Dobalina" )
	.misterise()
	.trigger( "yell" );

And out pops Mr Bob Dobalina & Mr Dave Dobalina! I'm not sure of any practical purpose for this odd bit of functionality. Perhaps some kind of AOP meta-data system or, um, no... I dunno. Here's a plugin for executing methods on an object by name:

$.fn.go = function( funcName ){
	return this.each(function(){
		if( $.isFunction( this[ funcName ] ) ){
			this[ funcName ]();
		}
	});
};

That's pretty stupid and cool. Using a plugin against your JavaScript classes instead of a simple method call will most likely get you killed by your colleagues, but hey, it keeps things looking jQuery-ish. And that's the important thing.

Update: Futher investigation has lead to some interesting discoveries... Go have a read!