Merge pull request #509 from openannotation/clean-up-markdown-tags

Clean up markdown and tags modules

Author: tilgovi

doc/api/ui.rst

@@ -5,3 +5,9 @@ annotator.ui package
 
 .. include:: ui/main.rst
    :start-line: 5
+
+.. include:: ui/markdown.rst
+   :start-line: 5
+
+.. include:: ui/tags.rst
+   :start-line: 5

doc/api/ui/main.rst

@@ -19,5 +19,23 @@ annotator.ui package
 
          A DOM element to which to bind event listeners. Defaults to
          ``document.body``, allowing annotation of the whole document.
+    
+      .. attribute:: options.editorExtensions
+    
+         An array of editor extensions. See the
+         :class:`~annotator.ui.editor.Editor` documentation for details of editor
+         extensions.
+    
+      .. attribute:: options.viewerExtensions
+    
+         An array of viewer extensions. See the
+         :class:`~annotator.ui.viewer.Viewer` documentation for details of viewer
+         extensions.
+    
+      .. attribute:: options.viewerRenderer
+    
+         An annotation renderer for the viewer. See the
+         :class:`~annotator.ui.viewer.Viewer` documentation for details of
+         renderers.
 
 

doc/api/ui/markdown.rst

@@ -0,0 +1,21 @@
+.. default-domain: js
+
+annotator.ui.markdown package
+=============================
+
+..  function:: annotator.ui.markdown.renderer(annotation)
+    
+    A renderer for the :class:`~annotator.ui.viewer.Viewer` which interprets
+    annotation text as `Markdown`_ and uses the `Showdown`_ library if present in
+    the page to render annotations with Markdown text as HTML.
+    
+    .. _Markdown: https://daringfireball.net/projects/markdown/
+    .. _Showdown: https://github.com/showdownjs/showdown
+    
+    **Usage**::
+    
+        app.include(annotator.ui.main, {
+            viewerRenderer: annotator.ui.markdown.renderer
+        });
+
+

doc/api/ui/tags.rst

@@ -0,0 +1,30 @@
+.. default-domain: js
+
+annotator.ui.tags package
+=========================
+
+..  function:: annotator.ui.tags.viewerExtension(viewer)
+    
+    An extension for the :class:`~annotator.ui.viewer.Viewer` which displays any
+    tags stored as an array of strings in the annotation's ``tags`` property.
+    
+    **Usage**::
+    
+        app.include(annotator.ui.main, {
+            viewerExtensions: [annotator.ui.tags.viewerExtension]
+        })
+
+
+..  function:: annotator.ui.tags.editorExtension(editor)
+    
+    An extension for the :class:`~annotator.ui.editor.Editor` which allows
+    editing a set of space-delimited tags, retrieved from and saved to the
+    annotation's ``tags`` property.
+    
+    **Usage**::
+    
+        app.include(annotator.ui.main, {
+            viewerExtensions: [annotator.ui.tags.viewerExtension]
+        })
+
+

src/ui/main.js

@@ -6,8 +6,6 @@ var util = require('../util');
 var adder = require('./adder');
 var editor = require('./editor');
 var highlighter = require('./highlighter');
-var markdown = require('./markdown');
-var tags = require('./tags');
 var textselector = require('./textselector');
 var viewer = require('./viewer');
 
@@ -194,20 +192,37 @@ function addPermissionsCheckboxes(editor, app) {
  *
  *      A DOM element to which to bind event listeners. Defaults to
  *      ``document.body``, allowing annotation of the whole document.
+ *
+ *   .. attribute:: options.editorExtensions
+ *
+ *      An array of editor extensions. See the
+ *      :class:`~annotator.ui.editor.Editor` documentation for details of editor
+ *      extensions.
+ *
+ *   .. attribute:: options.viewerExtensions
+ *
+ *      An array of viewer extensions. See the
+ *      :class:`~annotator.ui.viewer.Viewer` documentation for details of viewer
+ *      extensions.
+ *
+ *   .. attribute:: options.viewerRenderer
+ *
+ *      An annotation renderer for the viewer. See the
+ *      :class:`~annotator.ui.viewer.Viewer` documentation for details of
+ *      renderers.
+ *
  */
 function main(options) {
     if (typeof options === 'undefined' || options === null) {
         options = {};
     }
 
-    var element = options.element || util.getGlobal().document.body;
-    // FIXME: restore readOnly mode
-    //
-    // options: # Configuration options
-    //   # Start Annotator in read-only mode. No controls will be shown.
-    //   readOnly: false
+    options.element = options.element || util.getGlobal().document.body;
+    options.editorExtensions = options.editorExtensions || [];
+    options.viewerExtensions = options.viewerExtensions || [];
+
     // Local helpers
-    var makeAnnotation = annotationFactory(element, '.annotator-hl');
+    var makeAnnotation = annotationFactory(options.element, '.annotator-hl');
 
     // Object to hold local state
     var s = {
@@ -222,15 +237,16 @@ function main(options) {
         });
         s.adder.attach();
 
-        s.tags = tags.tags({});
-        s.editor = new editor.Editor({extensions: [s.tags.createEditorField]});
+        s.editor = new editor.Editor({
+            extensions: options.editorExtensions
+        });
         s.editor.attach();
 
         addPermissionsCheckboxes(s.editor, app);
 
-        s.highlighter = new highlighter.Highlighter(element);
+        s.highlighter = new highlighter.Highlighter(options.element);
 
-        s.textselector = new textselector.TextSelector(element, {
+        s.textselector = new textselector.TextSelector(options.element, {
             onSelection: function (ranges, event) {
                 if (ranges.length > 0) {
                     var annotation = makeAnnotation(ranges);
@@ -242,7 +258,7 @@ function main(options) {
             }
         });
 
-        var viewerOpts = {
+        s.viewer = new viewer.Viewer({
             onEdit: function (ann) {
                 // Copy the interaction point from the shown viewer:
                 s.interactionPoint = util.$(s.viewer.element)
@@ -254,28 +270,15 @@ function main(options) {
                 app.annotations['delete'](ann);
             },
             permitEdit: function (ann) {
-                return app.authz.permits(
-                    'update',
-                    ann,
-                    app.ident.who()
-                );
+                return app.authz.permits('update', ann, app.ident.who());
             },
             permitDelete: function (ann) {
-                return app.authz.permits(
-                    'delete',
-                    ann,
-                    app.ident.who()
-                );
+                return app.authz.permits('delete', ann, app.ident.who());
             },
-            extensions: [s.tags.createViewerField],
-            autoViewHighlights: element
-        };
-
-        if (g.Showdown && typeof g.Showdown.converter === 'function') {
-            viewerOpts.renderText = markdown.markdown().convert;
-        }
-
-        s.viewer = new viewer.Viewer(viewerOpts);
+            autoViewHighlights: options.element,
+            extensions: options.viewerExtensions,
+            renderer: options.viewerRenderer
+        });
         s.viewer.attach();
 
         injectDynamicStyle();

src/ui/markdown.js

@@ -1,38 +1,41 @@
+/*package annotator.ui.markdown */
 "use strict";
 
 var util = require('../util');
 
 var g = util.getGlobal();
 var _t = util.gettext;
 
-function markdown() {
-    var converter = null;
+
+/**
+ * function:: renderer(annotation)
+ *
+ * A renderer for the :class:`~annotator.ui.viewer.Viewer` which interprets
+ * annotation text as `Markdown`_ and uses the `Showdown`_ library if present in
+ * the page to render annotations with Markdown text as HTML.
+ *
+ * .. _Markdown: https://daringfireball.net/projects/markdown/
+ * .. _Showdown: https://github.com/showdownjs/showdown
+ *
+ * **Usage**::
+ *
+ *     app.include(annotator.ui.main, {
+ *         viewerRenderer: annotator.ui.markdown.renderer
+ *     });
+ */
+exports.renderer = function renderer(annotation) {
+    var convert = util.escapeHtml;
 
     if (g.Showdown && typeof g.Showdown.converter === 'function') {
-        converter = new g.Showdown.converter();
+        convert = new g.Showdown.converter().makeHtml;
     } else {
-        console.warn(_t("To use the Markdown plugin, you must" +
-        " include Showdown into the page first."));
+        console.warn(_t("To use the Markdown plugin, you must " +
+                        "include Showdown into the page first."));
     }
 
-    // Converts provided text into markdown.
-    //
-    // text - A String of Markdown to render as HTML.
-    //
-    // Examples
-    //
-    // plugin.convert('This is _very_ basic [Markdown](http://daringfireball.com)')
-    // # => Returns "This is <em>very<em> basic <a href="http://...">Markdown</a>"
-    //
-    // Returns HTML string.
-    function convert (text) {
-        text = util.escapeHtml(text || '');
-        return converter ? converter.makeHtml(text) : text;
+    if (annotation.text) {
+        return convert(annotation.text);
+    } else {
+        return "<i>" + _t('No comment') + "</i>";
     }
-
-    return {
-        convert: convert
-    };
-}
-
-exports.markdown = markdown;
+};