okfn/annotator — pull request #338 by nickstenning (2014-03-29 15:28:19+00:00)
Title: Embed jQuery in the built annotator

Rather than depending on an externally loaded jQuery, this commit causes
Annotator to embed its own copy of jQuery within its own closure, using
this for DOM manipulations.

This has a number of advantages, and a number of disadvantages. The
advantages first:

- We don't have to sniff the current page or execution context to
determine whether jQuery has been loaded and issue a somewhat obscure
warning when it's not.
- We can depend on whatever version of jQuery we like, regardless of the
state of the outside world. Up until now, we were relying primarily on
the jQuery project's good approach to backwards compatibility, but
even with their conservative deprecation schedule, we have been bitten
a number of times by depending on old jQuery features as the rest of
the web upgraded.
- Our impact on pages we load into is minimised. Previously, the
bookmarklet had to load jQuery, unbind it, and restore the page's copy
with jQuery.noConflict() (if it existed). Now the bookmarklet (and and
future browser extension) can simply load Annotator.
- Code is more explicit -- the '$' token isn't assumed to come from the
page context.

There are of course a few disadvantages:

- In the ideal case, a page author would already have included jQuery
(at the correct version) and keeping the dependency external would
have saved them from having to load jQuery twice.
- The tests are now slightly slower, as a result of having to build
jQuery into our compressed source files.

Overall, I think this is a net positive change, as it makes deploying a
working copy of Annotator easier. In the long run, I'd like us to reduce
our dependency on jQuery completely, removing it altogether if possible,
and this is a first step in decoupling that process from the concerns of
3rd-party developers and integrators.