Merge pull request #506 from openannotation/registry-rejig

Registry rejig

browser.js

@@ -5,14 +5,15 @@ var insertCss = require('insert-css');
 var css = require('./css/annotator.css');
 insertCss(css);
 
-var annotator = require('./src/annotator');
+var app = require('./src/app');
 var ui = require('./src/ui');
 var storage = require('./src/storage');
 var util = require('./src/util');
+var defaultUI = require('./src/plugin/defaultui');
 
 // Core annotator components
-exports.Annotator = annotator.Annotator;
-exports.supported = annotator.supported;
+exports.App = app.App;
+exports.supported = app.supported;
 
 // Access to libraries (for browser installations)
 exports.storage = storage;
@@ -21,6 +22,7 @@ exports.util = util;
 
 // Plugin namespace (for core-provided plugins)
 exports.plugin = {};
+exports.plugin.defaultUI = defaultUI.defaultUI;
 
 // Store a reference to the current annotator object, if one exists.
 var g = util.getGlobal();

demo.html

@@ -46,8 +46,11 @@ <h3>Header Level 3</h3>
               "Either download a tagged release from GitHub, or build the package " +
               "by running `make pkg` (or `./build/tools -a`).");
       } else {
-        var elem = document.getElementById('airlock');
-        var app = new annotator.Annotator(elem);
+        var app = new annotator.App();
+        app.include(annotator.plugin.defaultUI, {
+            element: document.getElementById('airlock')
+        });
+        app.start();
       }
     </script>
   </body>

dev.html

@@ -110,11 +110,12 @@ <h3>Header Level 3</h3>
     <script src="bundle/plugin/filter.js"></script>
 
     <script>
-      var elem = document.getElementById('airlock'),
-          anno = new annotator.Annotator(elem);
-
-      anno.addPlugin(annotator.plugin.Filter());
-      anno.setStorage(annotator.storage.DebugStorage);
+      var elem = document.getElementById('airlock');
+      var app = new annotator.App()
+      .include(annotator.plugin.defaultUI, {element: elem})
+      .include(annotator.plugin.filter)
+      .include(annotator.storage.debugStorage)
+      .start()
     </script>
   </body>
 

doc/api/app.rst

@@ -0,0 +1,71 @@
+.. default-domain: js
+
+annotator package
+=================
+
+..  class:: annotator.App([options])
+
+    App is the coordination point for all annotation functionality. App instances
+    manage the configuration of a particular annotation application, and are the
+    starting point for most deployments of Annotator.
+
+
+..  function:: annotator.App.prototype.include(module[, options])
+
+    Include a plugin module. If an `options` object is supplied, it will be
+    passed to the plugin module at initialisation.
+
+    If the returned plugin has a `configure` function, this will be called with
+    the application registry as its first parameter.
+
+    :param Object module:
+    :param Object options:
+    :returns: The Annotator instance, to allow chained method calls.
+
+
+..  function:: annotator.App.prototype.start()
+
+    Tell the app that configuration is complete. This binds the various
+    components passed to the registry to their canonical names so they can be
+    used by the rest of the application.
+
+    Runs the 'start' plugin hook.
+
+    :returns Promise: Resolved when all plugin 'start' hooks have completed.
+
+
+..  function:: annotator.App.prototype.runHook(name[, args])
+
+    Run the named hook with the provided arguments
+
+    :returns Promise: Resolved when all over the hook handlers are complete.
+
+
+..  function:: annotator.App.prototype.destroy()
+
+    Destroy the App. Unbinds all event handlers and runs the 'destroy' plugin
+    hook.
+
+    :returns Promise: Resolved when destroyed.
+
+
+..  function:: annotator.App.extend(object)
+
+    Create a new object which inherits from the App class.
+
+
+..  function:: annotator.supported([details=false, scope=window])
+
+    Examines `scope` (by default the global window object) to determine if
+    Annotator can be used in this environment.
+
+    :returns Boolean:
+      Whether Annotator can be used in `scope`, if `details` is
+      false.
+    :returns Object:
+      If `details` is true. Properties:
+
+      - `supported`: Boolean, whether Annotator can be used in `scope`.
+      - `details`: Array of String reasons why Annotator cannot be used.
+
+

doc/api/authz.rst

@@ -0,0 +1,41 @@
+.. default-domain: js
+
+annotator.authz package
+=======================
+
+..  data:: annotator.authz.defaultAuthorizationPolicy
+
+    Default authorization policy.
+
+
+..  function:: annotator.authz.defaultAuthorizationPolicy.permits(action,
+                                                  annotation,
+                                                  identity)
+
+    Determines whether the user identified by `identity` is permitted to
+    perform the specified action on the given annotation.
+
+    If the annotation has a "permissions" object property, then actions will
+    be permitted if either of the following are true:
+
+      a) annotation.permissions[action] is undefined or null,
+      b) annotation.permissions[action] is an Array containing `identity`.
+
+    If the annotation has a "user" property, then actions will be permitted
+    only if `identity` matches this "user" property.
+
+    If the annotation has neither a "permissions" property nor a "user"
+    property, then all actions will be permitted.
+
+    :param String action: The action the user wishes to perform.
+    :param annotation:
+    :param identity: The identity of the user.
+
+    :returns Boolean: Whether the action is permitted.
+
+
+..  function:: annotator.authz.defaultAuthorizationPolicy.authorizedUserId(identity)
+
+    Returns the authorized userid for the user identified by `identity`.
+
+