Older Browser Support in Annotator

Bill Hunt is a developer with the OpenGov Foundation, his article below is cross-posted from there.

The Annotator Problem: New Tech in Older Web Browsers

A few months ago, The OpenGov Foundation was awarded a grant from Hypothes.is’ Open Annotation Fund to add cross-browser support for Annotator, the tool powering inline annotation on government policy documents – like legislation and regulations – with Madison. For the civic technology community, this is no small obstacle: new, life-improving technologies often founder on the shoals of out-dated web browsers and operating systems. Some context: in the United States, for every person surfing the web with Chrome last month, two were not, according to StatCounter.

At the April 2014 I Annotate conference in San Francisco, we identified many older browsers, particularly Internet Explorer (IE), that simply could not run Annotator; therefore, large swaths of the world could not harness Madison. Since many citizens and government offices use older versions of Windows and Internet Explorer, in order to achieve our open government goals with Madison, we needed to modify the Annotator software package to support all of our users, not just those with new computers running the latest Internet browsers.

Creating an Assessment

The first task was to assess the scope of the problem. In today’s current web browser landscape, where does Annotator work as it should? Where does it break? Since Annotator has a built-in test suite, the fastest way to answers was to run the tests in every browser we wanted Annotator to work. To get a more comprehensive view, we needed to create an automated test runner and find a way to run our tests across multiple browsers.

For this, we used SauceLabs to create virtualized browsers to run our test suite against, since it contains almost every platform we care about. The SauceLabs API provided an easy way of creating these test runs, and the grunt-saucelabs package gave us an easy way to interface with them via Grunt. We investigated other solutions, but none were nearly as stable and mature. SauceLabs can also easily be integrated with most continuous integration tools, though we did not go that direction on this project.

Browser Testing Begins, Fails Immediately

While trying to run the initial tests in most versions of IE and older versions of Safari, the tests simply wouldn’t go. There were clearly major issues to investigate. Several of these problems turned out to be related to the way we ran the tests–some help from SauceLabs set us on the right track.

Next, we discovered that several of the testing libraries in use – including Chai and Sinon – didn’t offer out-of-the-box support for IE version 8. For Chai, we are only using the assert method for testing, and were able to make a straight replacement for assertive-chai. Implementing the bundled sinon-ie library solved the Sinon issue.

That was the easy part.

Patching for Features, Shim Libraries

The main problem with older browsers attempting to run Annotator is that they were written before current Internet standards became widely adopted, or in some cases, before those standards were even created. As a result, older browsers simply lack features from modern tools, or define and handle those features differently. In many cases, there are shim libraries available to make these features work properly, but not always.

In IE8, for example, the console api is only available if the Developer Tools window is open. When the window is closed (the default), using any of the console functions will cause an error. Since console sends the error messages in Annotator, it had to be replaced when not available. Since only a few lines of code are needed to replace console with an empty object, we wrote a custom shim to solve the problem. Similarly, there are a few calls to constants on the DOM Node constructor which is not present in IE. We therefore created a replacement Node object and hard coded those values.

As to other Annotator aspects, there are some very well established shim libraries to add support for commonly-used features. The ECMAScript-5 shim library adds support for many of the functions added by ECMA 5 to Javascript; mainly this is to complete the many Array functions we use, such as map and reduce. Douglas Crockford’s excellent JSON library allows us to manipulate JSON. Last, we used Rangy to provide a consistent interface to the getSelection and createRange document APIs. Also needed was a patch for Object.keys support for one of our dependencies: backbone-event-standalone.

Passing the Tests (Mostly)

With that done, most tests passed. However, Annotator still didn’t work perfectly in older browsers. A few features still eluded our tests, such as the handling of click events, which were inconsistent across browsers. We also had to do some tweaks to the CSS, as the rgba() css function, used for creating transparent colors, was not available. An opaque fallback color was used in those cases. The only other issue was CORS support, which we were able to manually enable in jQuery.

Wrapping Up & What’s Next

By the time we completed all of this work, we had run out of time for further improvements, like continuous integration and Selenium-based acceptance testing. And since the existing tests do not provide complete coverage, passing every test doesn’t guarantee that Annotator works perfectly in every browser, every time. While it will be up to the Annotator community to maintain and extend this project, we made significant progress. Thanks to the Open Annotation Fund and Hypothes.is, millions more Internet users can put Madison to work where they live, in whichever web browser they want or need to use.