hypothesis.js
hypothesis.js is injected into the page by embed.js using either the browser's plugin API or (in the case of the bookmarklet) the DOM API. (embed.js was in turn injected by the browser plugin or bookmarklet).
hypothesis.js is the "bootstrap" code that connects up and starts the various components of the Hypothesis app.
app: jQuery('link[type="application/annotator+html"]').attr('href'),
Here we find the <link rel="sidebar" ... that embed.js injected into the page. We pass it into the constructor method of Annotator.Host below.
window.annotator = new Klass(document.body, options);
Calling the Annotator.Host construct, passing an options object including our sidebar link.
Annotator.noConflict().$.noConflict(true);
Having created our Annotator instance and added our custom plugins etc to it, we inject Annotator into the page.
layout.app_inject_urls
app_inject_urls is the list of scripts and stylesheets that we're going to inject into the page. This comes from layouts.py, which in turn gets it from assets.yaml.
Most importantly these URLs to be injected include a minified version of hypothesis.js.
var baseUrl = document.createElement('link'); baseUrl.rel = 'sidebar'; baseUrl.href = '{{ app_uri or request.resource_url(context, 'app.html') }}'; baseUrl.type = 'application/annotator+html'; document.head.appendChild(baseUrl);
Finally, we inject a <link rel="sidebar" type="application/annotator+html" href=".../app.html"> into the <head> of the document. This is the HTML page for the contents of the sidebar/iframe. This link will be picked up by hypothesis.js later.
if (resources.length) { var url = resources.shift(); var ext = url.split('?')[0].split('.').pop(); var fn = (ext === 'css' ? injectStylesheet : injectScript); fn(url, next); }
This loop is where we actually call injectScript() or injectStylesheet() on each of the resource URLs defined above.
var injectScript = inject.script || function injectScript(src, fn) {
And we do the same thing for injecting scripts as we did for injecting stylesheets - we either use the function passed in by the browser plugin, or when called by the bookmarklet we fall back on the DOM API.
var injectStylesheet = inject.stylesheet || function injectStylesheet(href, fn) {
hypothesisInstall() will use the inject.stylesheet() function passed in to it to inject stylesheets into the page or, if no function was passed in, it'll fallback on the default function defined inline here.
The default method just uses the DOM's appendChild() method, but this method may fail if the site we're trying to annotate uses the Content Security Policy.
That's why when we're using one of the browser plugins rather than the bookmarklet, we pass in the browser API's method for injecting a stylesheet instead.
This is why the bookmarklet doesn't currently work on GitHub, for example, but the Chrome plugin does.
embed.js
embed.js is responsible for "embedding" the different components of the Hypothesis frontend application into the page.
First, either bookmarklet.js or one of the browser plugins injects a <script> tag to embed.js into the page, then embed.js runs.
This way the code in embed.js is shared across all bookmarklets and browser plugins, and the bookmarklets and plugins themselves have very little code.
app.appendTo(@frame)
And we inject our <iframe> into ... the frame? (@frame is a <div> that wraps our <iframe>, it's defined and injected into the page in guest.coffee).
app = $('<iframe></iframe>') .attr('name', 'hyp_sidebar_frame') .attr('seamless', '') .attr('src', src)
Finally, this is where we create the <iframe> element that is the Hypothesis sidebar!
embed = document.createElement('script'); embed.setAttribute('src', embedUrl); document.body.appendChild(embed);
Here we construct the actual <script> element, set its src URL, and inject it into the page using the DOM's appendChild() method.
var embedUrl = '{{request.resource_url(context, "embed.js")}}';
The whole job of the bookmarket is to inject a <script src=".../embed.js"> element into the current page. The src URL of this script element points to embed.js, another Pyramid template rendered by the server-side Hypothesis app.
bookmarklet.js
bookmarklet.js is the Pyramid template (rendered by our server-side Pyramid app) for the Hypothesis bookmarklet. This little bit of JavaScript (after being rendered by Pyramid) is what the user actually drags to their bookmarks bar as a bookmarklet.