Building a Single-Page Application for GAP, Part 1

Hello, I’m Nick Rabinowitz, and as Elton mentioned in his last post I’ve joined the GAP team to help create an online interface for reading and visualizing GAP texts, tentatively titled “GapVis.”

In the next few posts, I’ll set out the work that I have done in three parts: first, I’ll identify and explain some of the problems we encountered when trying to adapt the HESTIA NarrativeMap to GAP; then I’ll outline the architectural and technical choices we’ve made to address those challenges; and finally I’ll discuss some of the features of the new GapVis interface. The first two posts will be a bit more technical, and are mainly for fellow Digital Humanities coders – so if the terms “API”, “component”, and “framework” make your eyes roll back in your head, feel free to come back for post 3, which will be more for the lay reader.

For the last month or two, I’ve been working on adapting and expanding the prototype work I did on the HESTIA project into a fully-fledged Javascript-based web app capable of presenting a rich, multi-layered interface for any text run through the Edinburgh Geoparser. You can see the working version here, and the code is available on Github. Note that only two works are currently available at the moment, and given the experimental nature of the project, we included some features that older browsers (e.g. IE8 or lower) won’t support.

My original work on the HESTIA project was intended primarily as a proof-of-concept expanding my timemap.js library to represent a narrative sequence, and it was tightly tied to the specific text we were working with, the Histories of Herodotus. When I began to look at expanding this work into a generalized application that could present any text, and especially when we began to discuss a range of new features and visualizations we wanted to add, it quickly became clear that I was going to need to build the new application from the ground up. Well, not entirely from the ground up – there are a range of frameworks now available for building Javascript-based web applications, and after comparing several options I settled on Backbone.js as the basis for the new app.

Backbone offers a nice structure for building Model classes that sync easily with a RESTful API, which the GAP project was already creating, as well as a framework for managing dynamic views, UI events, and browser history (i.e. making the URL in the address bar change with the application state). At the same time, it offers a great deal of flexibility and extensibility, and is minimally prescriptive about how you should use it. This means you can use it in almost any way you want, but there’s a certain learning curve as you try to figure out how to integrate Backbone into your project.

For example, in the interface we came up with, many user actions need to have multiple effects on the interface: Clicking on the “next page” button shows the next page, but it also updates the page number, advances the timeline, and changes the URL. Backbone offers a basic pattern for handling user actions, but doesn’t in and of itself tell you how to manage the cross-references and function calls required to update various pieces of the interface, which might all be managed by different parts of your code. To address this, I created a global State model that all of the pieces of the application can both update (when the user does something) and listen to, updating themselves when the model is changed to reflect the new state. This is a common pattern, and once I started working with it I saw that Backbone offered some great tools to support it, but I had to come to it myself.

Despite the learning curve, Backbone has turned out to be a really useful framework, and it’s made it easier to make some of the nifty features we’ve built into the application. I’ll give a bit more detail on the architecture in the next post, but in the meantime, I encourage you to check it out, click around, and tell me what breaks :).