Public Lab Research note

MapKnitter Annotations: Interface Refactoring Underway

by justinmanley | August 19, 2014 00:03 19 Aug 00:03 | #11062 | #11062


I am working to add rich annotation functionality to MapKnitter as part of Google Summer of Code (read about my project here: This is my ninth week of coding.

The goal of this research note is to provide an update to the community on my progress with refactoring the MapKnitter interface.

If you're interested in reading about Leaflet.Illustrate, the Leaflet plugin that I wrote over the past few weeks to power MapKnitter's annotations, you can check out my last research note.

You can check out our previous discussion of this interface refactorinng in my previous research note:

August 6, 2014 - MapKnitter Annotations: Interface Refactoring


Screenshot with Vidun's upload modal!



So far, I have:

  • Added commenting and tagging to MapKnitter maps
  • Begun integrating @vidun's work on the upload interface

Under the hood, I've done a lot of work to make it easier for future developers to improve MapKnitter. I've:

  • Set up Bundler to handle MapKnitter's' dependencies
  • Set up Sprockets and bower for handling all of MapKnitter's static assets.
  • Given MapKnitter a RESTful API using Rails' resourceful routes.

Commenting and Tagging

I borrowed a lot of the commenting and tagging functionality from the Public Lab website. That means that commenting and tagging works pretty much the same in MapKnitter as it does on Public Lab. Among other things, users can write comments and the descriptions of their maps in Markdown.

Sprockets & bower

MapKnitter's static assets were a mess before this.

MapKnitter uses quite a few third-party libraries: Bootstrap, JQuery-Fileupload, Leaflet, Leaflet.Draw, etc. Using bower will make it clearer which javascript and css files are maintained by third parties and easier to upgrade to newer versions.

Using Sprockets enables MapKnitter to handle static assets in a much more elegant and maintanable way. Because this method of asset pipelining is the default in Rails 3.1+, this will also make it much easier should Public Lab ever upgrade MapKnitter to a more modern version of Ruby or Rails.

I found these articles helpful for integrating MapKnitter with Sprockets:


MapKnitter was previously not RESTful. Most significantly, resources were created, modified, and deleted using HTTP POST requests (as opposed to POST, PUT, and DELETE requests, respectively). Providing a RESTful API for MapKnitter will enable folks to use MapKnitter from the command line with curl. More importantly, it makes the code clearer, more logical, and more maintainable. For example, the routes can now be declared as:

app.resources :maps do |maps|
    maps.resources :tags
    maps.resources :comments
    maps.resources :uploads


  • Integrate Vidun's work on the MapKnitter upload interface. I've already merged Vidun's work into my MapKnitter branch, so now it's a matter of making sure everything works with the new routes, etc.

  • Merge Anish's LeafletImageDistort plugin.

  • Push MapKnitter site to beta server that @dogi set up for beta testing by MapKnitter community. (It will be ready for

beta-testing as soon as I merge Vidun and Anish's work).

  • Integrate the annotation features that I have developed in Leaflet.Illustrate. This will mean adding methods to Leaflet.Illustrate to serialize annotations to GeoJSON, adding routes, models, and controllers for annotations, and designing an annotation toolbar that will allow folks to change the colors and styles of polyline, polygon, and text annotations.

    I am also interested in enable users to add Riffle data to the map as annotations, so I'd like to talk to @mathew and others to figure out how to best implement this.

  • Create a workflow for generating Public Lab research notes from MapKnitter maps. This means generating an HTML POST query from MapKnitter map data that will be submitted to the Public Lab website to create a research note.


This is awesome, Justin! I'm excited about the code maintainability work you're doing, that is important to our future additions.

In terms of adding Riffle data, it my initial thought is we could treat it like embed content. We already have a goal of getting video and other rich media embeds on the maps, so would -- Dare i say it within earshot of @btbonval -- iframe embedding ala youtube be the way to go?

Is this a question? Click here to post it to the Questions page.

Reply to this comment...

@mathew - I've been thinking about Riffle data and just posted a research note about it: MapKnitter Annotations: Riffle Data as Map Annotations. I think that a more useful approach might be to provide a few d3 / Leaflet templates that would automatically visualize a small susbet of the Riffle data directly on the map.

Take a look at the research note and let me know what you think.

Reply to this comment...

omg this is too good to be true!!

hey, iframes are fine for pieces of media like that! that wasn't the debate :-)

Justin, you're comfortable with the amount of work you're taking on? If you start to worry, my feeling is always that some things 110% done is much better than all things 90% or less done.

Is this a question? Click here to post it to the Questions page.

Reply to this comment...

@warren - Don't worry - the RIFFLE data visualization feature is a looooong way off. To be honest, it's not likely that I'll get to it before the end of GSoC. I'm focusing on integrating Vidun's and Anish's work right now, and eventually my own annotation plugin, and that is my top priority for the time being.

I was excited about @mathew's suggestion to place RIFFLE data on the map and thought I would get the conversation started, even if I don't end up being the one who implements this functionality.

Reply to this comment...

@mathew iframes are a problem when a user can write the iframe any way he or she choses. If an iframe is part of a code base, maybe it isn't so good, but it is highly controlled. I think this would be a case where the user cannot arbitrarily make an iframe point at some spam site or a virus site, so I don't care.

Reply to this comment...

@btbonval cool. I think this might be a case where its going to be pretty arbitrary, as we'd like to make a format that people can create their own visualizations of data. so it might not turn out as well as something as straightforward as a Youtube.

Reply to this comment...

@mathew I must admit to not reading what was being discussed, only that you said I don't like iframes and @warren said its fine for pieces of media, so I assumed the user was not directly inputting what URL the iframe references. If the visualizations are made using mapknitter and the iframes don't reference any old URL the user puts in, that's fine. I think if the user is all like "woopeee I made visualization at and I'm 'gun link it in this fancy doohickey", then we could have a problem. That visualization could be any number of things we would rather not see ;) especially if the spammers can easily add annotations with iframes to any old internet.

Reply to this comment...

@mathew - I think at the beginning, we don't need to allow people to create arbitrary visualizations through MapKnitter. That is a worthy goal, but I think in the short term, we can set our sights on building in one or two of the most common visualizations.

In the meantime, if people want to create arbitrary visualizations, they can write something on GitHub or post a Public Lab research note, and then link to that using the map description or comments on MapKnitter.

Reply to this comment...

Login to comment.