My digital history project Shaping the Nation is live right now at maps.districtbuilt.com. It’s an online visualization of the incorporation of states into the United States overlaid on a Google Map. I wanted the project to reflect change to our nation over time, so I worked with an open-source Javascript library called timemap.js that provides an API (sort of) to adjust timeseries data.
I was inspired to do this project based on the class presentation of Maps of War, in which a number of different historical events are overlaid on a Flash map. I was unimpressed by both the technology behind it and the features the site included — particularly that there were no controls or features to provide additional information on what was happening. I made sure that Shaping the Nation would provide a level of flexibility and semantic design that allowed for interactivity to live front-and-center.
I’m using this post as both a way to announce it, and as a look into the process behind the website itself.
Project Statement (Edit)
I’m really pleased with the way Shaping the Nation turned out. It was an exciting and challenging exercise getting the multiple components behind the project to work in synchronization to display the information I wanted it to. I think Shaping the Nation demonstrates a solid proof-of-concept despite the absence of complete content.
In the process of making Shaping the Nation, I learned a great deal about not only the history of this nation, but about semantic and modern methods of displaying historical information on the Internet. Any further expansion of this project should reflect a likely target audience: given the simplicity and ease of access in this case, primary school students.
Getting my feet wet
Starting out, I didn’t find that WordPress would provide the flexibility or out-of-the-box features I was looking for in this project. Instead, I created a subdomain on my own hosted site and uploaded Twitter’s Bootstrap to provide a complete CSS/JS/HTML skeleton for the site. Bootstrap includes a well-designed grid system and layout components to rapidly prototype the site’s design and functionality. I highly recommend Bootstap for any project that needs to be designed quickly and efficiently — the level of customization and flexibility in the framework is amazing, and everything’s very well documented. Bootstrap has a form of community helpdesk on Github as well.
Working with timemap.js was really interesting. It’s well documented and the project’s authors provide examples, but getting it to do things outside what’s documented was a fun challenge. In the early stages of this project, I had to determine the most logical way to display the data I wanted on the map. I had prior knowledge of the Google Maps API and knew that the Maps platform supports polygonal shapes as a data overlay. The problem, though, was that polygons drawn in Google Maps itself are proprietary — they’re linked to your Google account and the information is stored on Google’s servers.
KML to the rescue
The solution to the problem of exporting polygons came from a bit of research. In Google Maps’ bigger brother Google Earth, it’s possible to draw polygons and export them to a filetype called KML. KML — Keyhole Markup Language — parallels XML data structures while providing geographic information to whatever the file is describing. In my case, I needed a dataset describing the shapes and locations of the 50 states, and KML delivered. I began hand-drawing the polygonal outlines of the states to export to KML.
What KML looks like
<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
<Document>
<Placemark>
<name>New York City</name>
<description>New York City</description>
<Point>
<coordinates>-74.006393,40.714172,0</coordinates>
</Point>
</Placemark>
</Document>
</kml>
The example above describes the New York City as a point on the map. The tag <name> identifies that the point is called New York City, and <coordinates> provides the latitude and longitude of the point. For my project, the KML is expanded to several different points, the object is described as a polygon and a tag is provided giving a date of incorporation. KML interpretation though timemap.js automatically overlays the data on the map when the timeline view is adjusted appropriately.
A few days later, I returned to the drawing board after further consideration on hand-drawn polygonal states. Because both Maps and Earth already know where the states are, why should I draw them inaccurately by hand? Looking through Google’s developer documentation, I found a link to the 50 states as a single KML file, complete with dates of incorporation.
Digging deeper
The KML file from Google allowed me to really get the ball rolling on Shaping the Nation. Timemap.js included a parser for KML files, so getting the timeline to display timeseries data and the polygons themselves was very straightforward. I could now turn my efforts toward working with Bootstrap and external Javascript libraries to expand the functionality of the core project.
My first thought came from an earlier mapping project shown to the class a few weeks ago. When the map updated, the URL changed — I wanted this functionality so Shaping the Nation could have browsing capabilities in the sidebar. I added a list of decades and the states that were incorporated inside those decades, then proceeded to look up best practices for manipulating URL states. Conveniently enough, timemap.js includes an optional URL state manipulation script called state.js that allows data on the map to be presented according to the structure of the URL.
How state.js works
http://maps.districtbuilt.com/#zoom=5¢er=38.102185,-77.96697&date=1889&selected=state-1
> #zoom=integer
> ¢er=long,lat
> &date=integer
> &selected=string
The example above zooms to Washington state (it has a default ID of 1 for some reason) and displays its polygon’s tooltip. There are four variables in play: the scale of the map, where the map is centered, what year it is and which state is selected. By using Single Page Interface (SPI) techniques like # and &, the state of the page can be easily manipulated using prebuilt programmatic URLs. I attempted to built a search interface for user-entered years, but form submission writes queries in the form of ?=, and I’m not that great at handwriting Javascript. There’s a solution living somewhere in location.hash, but I couldn’t figure it out. #Whatever.
State.js allows for manipulation of the map and timeline in synchronization, all from the URL. It’s an AJAX function, so URL state changes load the new data without refreshing the page. The intention of my project is to continue to build stateful URLs into the sidebar to load each individual state — unfortunately, finding latitude/longitude coordinates and appropriate zoom level is very time consuming for each individual state, especially when factoring the tooltip popup.
On the subject of popups, the plan for Shaping the Nation is to include basic data about each state on selection. In addition to the year of incorporation, each tooltip will include a brief note about incorporation and a link to relevant information. This can be built into the KML data and interpreted through timemap.js. Given the natural brevity of a tooltip and the simplicity of the application, a likely audience for Shaping the Nation is young children who would benefit from an interactive visualization of our nation.
Concluding Remarks
I had a lot of fun building and conceiving Shaping the Nation. Because it’s a subset of my own domain, I’ll be leaving this up for a while. It’s really exciting when the web entities you work on actually work — and I learned a great deal about Javascript and mapping APIs through this project.
Moving forward, I’d like to ask childhood educators how this application could be better suited for the classroom. I’d like to know what additional data could/should be added to it in addition to the core timeseries and state information. I hope you all like it and I’m eager to hear your feedback on the project.
—Chris
Whoa.
This is pretty legit Chris. Nice job on the project. I wonder what you could have done if you had more time.
Did you try to plug-in google earth and see what happened?