Simplify Command API and added docs.

Fixes #825.

collab/DocumentStore.js

@@ -16,20 +16,20 @@ class DocumentStore {
 
     @return {Object} document record
   */
-  createDocument(props, cb) {
+  createDocument(params, cb) {
 
-    if (!props.documentId) {
+    if (!params.documentId) {
       // We generate a documentId ourselves
-      props.documentId = uuid()
+      params.documentId = uuid()
     }
 
-    let exists = this._documentExists(props.documentId);
+    let exists = this._documentExists(params.documentId);
     if (exists) {
       return cb(new Err('DocumentStore.CreateError', {
         message: 'Could not create because document already exists.'
       }))
     }
-    this._createDocument(props)
+    this._createDocument(params)
   }
 
   /*
@@ -48,14 +48,14 @@ class DocumentStore {
   /*
     Update document record
   */
-  updateDocument(documentId, newProps, cb) {
+  updateDocument(documentId, newparams, cb) {
     let exists = this._documentExists(documentId)
     if (!exists) {
       return cb(new Err('DocumentStore.UpdateError', {
         message: 'Document does not exist.'
       }))
     }
-    this._updateDocument(documentId, newProps)
+    this._updateDocument(documentId, newparams)
     cb(null, this._getDocument(documentId))
   }
 
@@ -92,8 +92,8 @@ class DocumentStore {
   // Handy synchronous helpers
   // -------------------------
 
-  _createDocument(props) {
-    this._documents[props.documentId] = props
+  _createDocument(params) {
+    this._documents[params.documentId] = params
   }
 
   _deleteDocument(documentId) {
@@ -105,9 +105,9 @@ class DocumentStore {
     return this._documents[documentId]
   }
 
-  _updateDocument(documentId, props) {
+  _updateDocument(documentId, params) {
     let doc = this._documents[documentId]
-    extend(doc, props)
+    extend(doc, params)
   }
 
   _documentExists(documentId) {

model/transform/createAnnotation.js

@@ -22,18 +22,10 @@ import helpers from '../documentHelpers'
   });
   ```
 */
-
 function createAnnotation(tx, args) {
   let sel = args.selection
   if (!sel) throw new Error('selection is required.')
-  let annoType = args.annotationType
-  let annoData = args.annotationData
   let anno = args.node
-  if (!anno && annoType) {
-    console.warn('DEPRECATED: Use node: {type: "strong"} instead of annotationType: "strong"')
-    anno = { type: annoType }
-    extend(anno, annoData)
-  }
   if (!anno) throw new Error('node is required')
 
   if (!sel.isPropertySelection() && !sel.isContainerSelection() || sel.isCollapsed()) {

packages/base/RedoCommand.js

@@ -2,16 +2,16 @@ import Command from '../../ui/Command'
 
 class Redo extends Command {
 
-  getCommandState(props, context) {
-    let docSession = context.documentSession
+  getCommandState(params) {
+    let docSession = params.documentSession
     return {
       disabled: !docSession.canRedo(),
       active: false
     }
   }
 
-  execute(props, context) {
-    let docSession = context.documentSession
+  execute(params) {
+    let docSession = params.documentSession
     if (docSession.canRedo()) {
       docSession.redo()
       return true

packages/base/UndoCommand.js

@@ -2,16 +2,16 @@ import Command from '../../ui/Command'
 
 class Undo extends Command {
 
-  getCommandState(props, context) {
-    let docSession = context.documentSession
+  getCommandState(params) {
+    let docSession = params.documentSession
     return {
       disabled: !docSession.canUndo(),
       active: false
     }
   }
 
-  execute(props, context) {
-    let docSession = context.documentSession
+  execute(params) {
+    let docSession = params.documentSession
     if (docSession.canUndo()) {
       docSession.undo()
       return true

packages/image/InsertImageCommand.js

@@ -6,10 +6,10 @@ class ImageCommand extends Command {
     super({ name: 'insert-image' })
   }
 
-  getCommandState(props, context) {
+  getCommandState(params, context) {
     let documentSession = context.documentSession
-    let sel = props.selection || documentSession.getSelection()
-    let surface = props.surface || context.surfaceManager.getFocusedSurface()
+    let sel = params.selection || documentSession.getSelection()
+    let surface = params.surface || context.surfaceManager.getFocusedSurface()
     let newState = {
       disabled: true,
       active: false
@@ -25,16 +25,16 @@ class ImageCommand extends Command {
     Inserts (stub) images and triggers a fileupload.
     After upload has completed, the image URLs get updated.
   */
-  execute(props, context) {
-    let state = this.getCommandState(props, context)
+  execute(params, context) {
+    let state = this.getCommandState(params, context)
     // Return if command is disabled
     if (state.disabled) return
 
     let documentSession = context.documentSession
-    let sel = props.selection || documentSession.getSelection()
-    let surface = props.surface || context.surfaceManager.getFocusedSurface()
+    let sel = params.selection || documentSession.getSelection()
+    let surface = params.surface || context.surfaceManager.getFocusedSurface()
     let fileClient = context.fileClient
-    let files = props.files
+    let files = params.files
 
     // can drop images only into container editors
     if (!surface.isContainerEditor()) return

packages/inline-node/EditInlineNodeCommand.js

@@ -3,31 +3,31 @@ import Command from '../../ui/Command'
 class EditInlineNodeCommand extends Command {
   constructor(...args) {
     super(...args)
-    if (!this.params.nodeType) {
+    if (!this.config.nodeType) {
       throw new Error('Every AnnotationCommand must have a nodeType')
     }
   }
 
-  getCommandState(props, context) {
+  getCommandState(params, context) {
     let sel = context.documentSession.getSelection()
     let newState = {
       disabled: true,
       active: false
     }
-    let annos = this._getAnnotationsForSelection(props, context)
+    let annos = this._getAnnotationsForSelection(params, context)
     if (annos.length === 1 && annos[0].getSelection().equals(sel)) {
       newState.disabled = false
       newState.node = annos[0]
     }
     return newState
   }
 
-  execute(props, context) { // eslint-disable-line
+  execute(params, context) { // eslint-disable-line
 
   }
 
-  _getAnnotationsForSelection(props) {
-    return props.selectionState.getAnnotationsForType(this.params.nodeType)
+  _getAnnotationsForSelection(params) {
+    return params.selectionState.getAnnotationsForType(this.config.nodeType)
   }
 
 }

packages/inline-node/InsertInlineNodeCommand.js

@@ -1,16 +1,47 @@
 import Command from '../../ui/Command'
 import insertInlineNode from '../../model/transform/insertInlineNode'
 
+/**
+  Reusable command implementation for inserting inline nodes.
+
+  @class InsertInlineNodeCommand
+
+  @example
+
+  ```
+  class AddXRefCommand extends InsertInlineNodeCommand {
+    createNodeData() {
+      return {
+        attributes: {'ref-type': 'bibr'},
+        targets: [],
+        label: '???',
+        type: 'xref'
+      }
+    }
+  }
+  ```
+
+  In configurator
+  ```
+  config.addCommand('add-xref', AddXRefCommand, {nodeType: 'xref'})
+  ```
+*/
+
+/** INCLUDE_IN_API_DOCS */
 class InsertInlineNodeCommand extends Command {
   constructor(...args) {
     super(...args)
 
-    if (!this.params.nodeType) {
-      throw new Error('Every AnnotationCommand must have a nodeType')
+    if (!this.config.nodeType) {
+      throw new Error('Every InlineInlineNodeCommand must have a nodeType')
     }
   }
 
-  getCommandState(props, context) {
+  /**
+    Determine command state for inline node insertion. Command is enabled
+    if selection is a property selection.
+  */
+  getCommandState(params, context) {
     let sel = context.documentSession.getSelection()
     let newState = {
       disabled: !sel.isPropertySelection(),
@@ -19,8 +50,11 @@ class InsertInlineNodeCommand extends Command {
     return newState
   }
 
-  execute(props, context) {
-    let state = this.getCommandState(props, context)
+  /**
+    Insert new inline node at the current selection
+  */
+  execute(params, context) {
+    let state = this.getCommandState(params, context)
     if (state.disabled) return
     let surface = context.surface || context.surfaceManager.getFocusedSurface()
     if (surface) {
@@ -38,12 +72,12 @@ class InsertInlineNodeCommand extends Command {
 
   createNodeData(tx, args) { // eslint-disable-line
     return {
-      type: this.params.nodeType
+      type: this.config.nodeType
     }
   }
 
-  _getAnnotationsForSelection(props) {
-    return props.selectionState.getAnnotationsForType(this.params.nodeType)
+  _getAnnotationsForSelection(params) {
+    return params.selectionState.getAnnotationsForType(this.config.nodeType)
   }
 
 }

packages/persistence/SaveCommand.js

@@ -5,16 +5,16 @@ class SaveCommand extends Command {
     super({ name: 'save' })
   }
 
-  getCommandState(props, context) {
-    let dirty = context.documentSession.isDirty()
+  getCommandState(params) {
+    let dirty = params.documentSession.isDirty()
     return {
       disabled: !dirty,
       active: false
     }
   }
 
-  execute(props, context) {
-    let documentSession = context.documentSession
+  execute(params) {
+    let documentSession = params.documentSession
     documentSession.save()
     return {
       status: 'saving-process-started'

packages/switch-text-type/SwitchTextTypeCommand.js

@@ -6,26 +6,26 @@ import _clone from 'lodash/clone'
 class SwitchTextTypeCommand extends Command {
 
   // Available text types on the surface
-  getTextTypes(context) {
-    let surface = context.surfaceManager.getFocusedSurface()
+  getTextTypes(params) {
+    let surface = params.surface
     if (surface && surface.isContainerEditor()) {
       return surface.getTextTypes()
     } else {
       return []
     }
   }
 
-  getTextType(context, textTypeName) {
-    let textTypes = this.getTextTypes(context)
+  getTextType(params, textTypeName) {
+    let textTypes = this.getTextTypes()
     return _find(textTypes, function(t) {
       return t.name === textTypeName
     })
   }
 
   // Search which textType matches the current node
   // E.g. {type: 'heading', level: 1} => heading1
-  getCurrentTextType(context, node) {
-    let textTypes = this.getTextTypes(context)
+  getCurrentTextType(params, node) {
+    let textTypes = this.getTextTypes(params)
     let currentTextType
     textTypes.forEach(function(textType) {
       let nodeProps = _clone(textType.data)
@@ -37,14 +37,14 @@ class SwitchTextTypeCommand extends Command {
     return currentTextType
   }
 
-  getCommandState(props, context) {
-    let doc = context.documentSession.getDocument()
-    let sel = context.documentSession.getSelection()
-    let surface = context.surfaceManager.getFocusedSurface()
+  getCommandState(params) {
+    let doc = params.documentSession.getDocument()
+    let sel = params.selection
+    let surface = params.surface
     let node
     let newState = {
       disabled: false,
-      textTypes: this.getTextTypes(context)
+      textTypes: this.getTextTypes(params)
     }
     // Set disabled when not a property selection
     if (!surface || !surface.isEnabled() || sel.isNull()) {
@@ -59,7 +59,7 @@ class SwitchTextTypeCommand extends Command {
       // so we need to guard node
       if (node) {
         if (node.isText() && node.isBlock()) {
-          newState.currentTextType = this.getCurrentTextType(context, node)
+          newState.currentTextType = this.getCurrentTextType(params, node)
         }
         if (!newState.currentTextType) {
           // We 'abuse' the currentTextType field by providing a property
@@ -82,13 +82,11 @@ class SwitchTextTypeCommand extends Command {
 
   /**
     Trigger a switchTextType transaction
-
-    @param {String} textTypeName identifier (e.g. heading1)
   */
-  execute(props, context) {
-    let textType = this.getTextType(context, props.textType)
+  execute(params) {
+    let textType = this.getTextType(params.textType)
     let nodeData = textType.data
-    let surface = context.surfaceManager.getFocusedSurface()
+    let surface = params.surface
     if (!surface) {
       console.warn('No focused surface. Stopping command execution.')
       return