Merge pull request #2340 from hypothesis/fix-guest-embedding

Fix guest embedding

docs/hacking/customized-embedding.rst

@@ -1,26 +1,44 @@
 Customized embedding
 ####################
 
-By default, Hypothesis instantiates the ``Annotator.Host`` class defined in
-the injected code loaded by ``embed.js``. It is possible to change this by
-assigning an alternate constructor to ``window.hypothesisRole``. To customize
-the plugins that are loaded, define a function ``window.hypothesisConfig`` which
-returns an options object. This is then passed to the constructor as the
-second argument::
+To customize the plugins that are loaded, define a function ``window.hypothesisConfig``
+which returns an options object::
+
 
     window.hypothesisConfig = function () {
       return {
         app: 'https://example.com/custom_sidebar_iframe',
-        Toolbar: {container: '.toolbar-wrapper'}
+        Toolbar: {container: '.toolbar-wrapper'},
+        BucketBar: {container: '.bucketbar-wrapper'}
       };
     };
 
-With the exception of ``app``, the properties for the options object are the
-names of Annotator plugins and their values are the options passed to the
-individual plugin constructors.
+In the above example, the Toolbar will be attached to the element with the
+``.toolbar-wrapper`` class, and the BucketBar to the element with the ``.bucketbar-wrapper``
+class.
+
+The full range of possibilities here is still in need of documentation and we
+would appreciate any help to improve that.
+
+With the exception of ``app`` and ``constructor``, the properties for the options object
+are the names of Annotator plugins and their values are the options passed to the individual
+plugin constructors.
 
 The ``app`` property should be a url pointing to the HTML document that will be
 embedded in the page.
 
-The full range of possibilities here is still in need of documentation and we
-would appreciate any help to improve that.
+The ``constructor`` property should be used in when you want to annotate an iframe on a host
+document. By instantiating the ``Annotator.Guest`` class inside the iframe you can capture
+selection data from the frame which will be accessible by a host annotator in a parent document.
+By default, Hypothesis instantiates the ``Annotator.Host`` class defined in the injected code
+loaded by ``embed.js``. It is possible to change this by assigning an alternate ``constructor``
+in the options object returned by ``window.hypothesisConfig``. For example::
+
+
+	window.hypothesisConfig = function () {
+		return {
+			constructor: Annotator.Guest
+		};
+	};
+
+An Annotator Host can connect to multiple guests.

h/static/scripts/annotator/main.js

@@ -47,22 +47,13 @@ require('./plugin/textquote');
 require('./plugin/textposition');
 require('./plugin/textrange');
 
-var Klass = Annotator.Host;
-var docs = 'https://github.com/hypothesis/h/blob/master/README.rst#customized-embedding';
+var docs = 'https://h.readthedocs.org/en/latest/hacking/customized-embedding.html';
 var options = {
   app: jQuery('link[type="application/annotator+html"]').attr('href'),
   BucketBar: {container: '.annotator-frame'},
   Toolbar: {container: '.annotator-frame'}
 };
 
-if (window.hasOwnProperty('hypothesisRole')) {
-  if (typeof window.hypothesisRole === 'function') {
-    Klass = window.hypothesisRole;
-  } else {
-    throw new TypeError('hypothesisRole must be a constructor function, see: ' + docs);
-  }
-}
-
 // Simple IE autodetect function
 // See for example https://stackoverflow.com/questions/19999388/jquery-check-if-user-is-using-ie/21712356#21712356
 var ua = window.navigator.userAgent;
@@ -81,5 +72,10 @@ if (window.hasOwnProperty('hypothesisConfig')) {
 }
 
 Annotator.noConflict().$.noConflict(true)(function () {
+  var Klass = Annotator.Host;
+  if (options.hasOwnProperty('constructor')) {
+    Klass = options.constructor;
+    delete options.constructor;
+  }
   window.annotator = new Klass(document.body, options);
 });