The best way to learn how to do something is to study the work of the greats. Today, we're going on an expedition through the New York Times' source code. Grab your tools, and let's get started.
Part I: A Quick Survey of the DOM
A quick scan of our map shows a typical breakdown: meta tags at the top, some CSS thrown in, followed by some HTML. For the purposes of making this journey concise and expedient, we're going to be mainly venturing through the script in the document. This means we'll be treating the meta tags and social media and Google Analytics like the far-out corners of the map: you're probably not going to need to know the exact terrain, but it's nice to know that they're there.
Moving on, we hit our basic setup in the DOM. Open up the link of our map, and inspect element. Hovering over each element will give us a good idea of what all these pieces are doing. We can see that the header is one element, the graphic is another, and the footer is, fittingly, the end element. Keep exploring the layout of the land, and when you're ready, we'll move on to the meat of the expedition.
Part II: Exploring All Our Routes
Starting out in the source code, let's start with the fun part: clicking on any link that looks like it might have a trailmarker. How will you know what's down a trail if you don't explore it? Starting in the footer, clicking on the first link leads us to the source for the base of the whole graphic: the data. We can see that this graphic's data is coming from the U.S. Census Bureau— pretty trustworthy, and it's worth knowing where all the data's coming from.
Skipping down to the script source links, the first link shows they're using Google Maps API, which is, mercifully, pretty well-documented. Note the specification in the API url here: libraries is set to geometry. According to the Google Maps documentation, using a setting of geometry adds built-in functions to calculate geometric values, including geographic area. This gives us a clue that they may be adding shapes on top of the map Google's API returns, and a quick check back at our map confirms this, with the area lines for the 'Percentage below poverty' graph, and the circles for the 'Number living below poverty' map.
Part III: Heading Deeper Into the Forest
We're really in the thick of it now. Still on map.js, this is another case of a long trail we're not going to make it back from in time. But a quick scan shows some interesting helper methods being setup here: a constructor called Waiter is setup with some prototype methods to help it wait around on objects in the program until they're ready. A few take an argument of ctx, which according to the experts over at Stack Overflow means 'context', and is usually used to pass around in a program to help maintain state, as opposed to global variables.
Next, a variable slug is set up to normalize text that's being passed in as an argument to a function. From the regex used here, it looks as though it's trying to eliminate any characters that aren't letter characters and then lowercase the result.
The next variable, cities, is calling on the d3 library and selecting elements in the DOM with an id of 'g-cities', and a class of 'g-city'. From here, the following few lines are appending HTML to the cities variable. What this all really appears to be doing is setting up a way to swap out all of the data depending on which city map is currently selected. We can also see that they're using slug to set up a unique link to an image depending on which city's map has been selected. So RESTful!
Now that the city url has been appended, an event is set up to listen for any clicks on cities in the DOM. Once clicked, a function that zooms into the currently set latitude and longitude fires, based on where the user's mouse is. This is a part of D3's library, and it's pretty neat. If you're interested in learning more, checkout this visual.
A variable called selection is pointed toward this (in this case, buttons, which is what's calling this function). 'id' is set to point toward anything in this that has the attribute 'data-id'. Next a function toggle is called, and if we take a quick peek ahead on the map, we can see that that function is being defined just a few lines below.
Normally when we encounter toggle in the wild, it behaves by, well, toggling between hiding and showing the selected element. The one we see here in the New York Times' code is a slightly different beast. This one works by taking the buttons and keys and returning a boolean value depending on whether the value of their attribute 'data-id' matches id or not. Then, depending on the size of the window, a certain image is returned for the map.
Part IV: The End of Our Journey
At long last, we've come to the sweet, sweet end of the trail. We saw a whole lot of code here today, some setting up mouse event functions, some setting up conditions to swap out images, and some setting variables for D3. And while we didn't go to the end of every trail and back, much like a typical hike, simply exploring the main trail and taking a quick peek down the side trails gave us more than enough to explore. We saw some interesting sites and learned some useful things today, so go ahead and head home with the pride that you now know a little bit more about the wilderness that is someone else's source code today.