The Latest in Mapping
with Javascript and jQuery

Presented at the 2011 CAR Conference, Raleigh, NC

Timothy C. Barmann
The Providence Journal /

The Concept

The Concept (cont.)

It's great for fast-changing maps, such as an election night map showing results as they come in. We used this technique on election night to results as they came in to the local Board of Elections.

More examples

Downside of Javascript maps


OR ...

Let's get started

We're going to build a map that shows the change in population for each county in North Carolina between 2000 and 2008.

The shapefile we need can be found at Check the box for County and Equivalent (Current) and click download.

If you haven't done so already, download the files and software from the links at the top.

Shapefile and companion files

Unzip the shapefile you downloaded. These are the files contained in the zip file.

Preparing the data

Open the population spreadsheet. To make this exercise simpler, remove all the population columns except those for 2000 and 2008.

Delete the other extra rows and notes, as shown in the next slide.

Preparing the data (cont.)

Search and replace the county column to get rid of the space and the word "County" that follows the county names. There may be a period in front of each county name that needs to be removed. Add two more columns called "change" and "pct_chg" with the appropriate formulas.

Format the four columns with numbers as "general." We'll make the percent value look nice later.

Save the data file

Save the spreadsheet as a CSV file.

Refining the data with Google Refine

This may be overkill, but I like to use Google Refine to convert the CSV file into a format the Javascript mapping program can easily read.

Refining the data with Google Refine (cont.)

The format is called JSON -- Javascript Object Notation. It's a way of formatting that's both easy for humans and computers to read, similar to XML. (For more information about JSON, see

Google Refine has a built-in JSON export feature. Click on Export and choose Templating.

Refining the data with Google Refine (cont.)

The right side of the export module shows a preview of the data formatted in JSON.

There are a couple extra characters we don't need, so we'll edit the template on the left.

In the prefix section, get rid of the opening squiggly bracket ({) and the word "rows:".

In the suffix section, delete the closing squiggly bracket (}).

Refining the data with Google Refine (cont.)

Then we'll give the array a Javascript variable name in the prefix section.

And in the suffix section, add a semicolon to end the Javascript statement.

Click export, and the program will send the file to your browser.

Saving the JSON data

Here is what the JSON file looks like opened in Notepad. It contains an array of objects, one for each county.

Save the file to a place where you will be building your web page. I like to name the file the same name as the variable, with an extension of json.

Editing the map template file

Open the map template file and resave it with a new name. Add a <script> tag to include the JSON file you just created.

Editing the map template file (cont.)

Set the datasource variable and the join_field variable.

Datasource holds the name of the variable assigned to the JSON array.

Join_field is the name of the field from the JSON array that corresponds with the onmouseover attribute of the area tags. This is usually a geographic label like county, city, state, etc.

The initial_map_field_name is the field we want mapped when the map page is initially loaded.

After making these changes, save the file to your web directory.

Load the shapefile into QGIS

We need an HTML image map so we'll get it by loading the shapefile into QGIS and using its Html Image Map plugin.

Fortunately, we only have to go through this process once. We will be able to re-use the image map for any other map of North Carolina we care to make.

Click on Layer and choose Add Vector Layer

Load the shapefile into QGIS (cont.)

Choose the shapefile of North Carolina counties you downloaded and unzipped from the Census bureau.

Load the shapefile into QGIS (cont.)

Here is how the shapefile appears in QGIS.

Click on the Open Attribute Table icon to see the data that is included in the shapefile.

Load the shapefile into QGIS (cont.)

The important column here is called "NAME" and it contains all the names of the counties in North Carolina.

We don't need to do anything here, so just close the window.

Export Image Map from QGIS

Resize the QGIS window to get rid of empty space around the map. Click the zoom icon to maximize the size of the map. (We'll be able to resize the map later in the Javascript mapping program.)

Then, click on Plugins and select Html Image Map plugin.

Export Image Map from QGIS

In the Html Image Map plugin, the image size is already set based on the dimensions of the QGIS map window.

Choose a filename. The plugin will automatically append .html to the filename you enter.

Uncheck all the boxes except onMouseOver attr. For that value, select NAME, the field that holds the county name.

Click OK.

Export Image Map from QGIS (cont.)

If everything works properly, the plugin will create two files: An html page and an image with the extension png.

We don't need the png file, as the Javascript program will create the map for us. All we need is the image map html code, which contains the coordinates for each county.

Open up the html file that the Html image map plugin just created and copy all the code between the start tag and the end tag (including those tags).

Paste Image Map into web map template

Open the web map template file and locate the image map section, which begins with the <map> tag and ends with the </map> tag. Paste the image map html code into this section. And save the file to your Web directory.

First look at the map

Here is what the map looks like without any other configuration.

You can see that by default, the program creates a map for each field it finds. It has a palette of colors that goes from green to blue. And it divides the data to fall within six equal classes.

And the program has created tooltips that show when hover over particular counties.

We can then customize it.

Customizing the map

We can customize the map by setting up the "fields" array. This is an array of objects, one for each field.

There are a host of settings that let you:

Customizing the map (cont.)

Here you can see we've set the name of the field, the label that should be shown, whether we want the program to map this field or simply show it in the tooltips, and how to format the values in this field.

Customizing the map (cont.)

Here's how the map looks with the fields variable set. Notice the nice labels for the field headings instead of the original ones we made in Excel. The Percent Change legend is formatted nicely with a plus or minus sign, one digit of precisino and a percent sign

Also note the labels on the other maps we can select.

Customizing the map (cont.)

This demonstrates another feature of the mapping program. When you hold your mouse over a legend color swatch, the corresponding regions on the map are highlighted.

Customizing the map (cont.)

Finally, let's move the legend so it is tucked under the map, and to the left of where it is now. This is done by adjusting the top and left offset numbers in the map web page file.

The finished product