feat(canvas): allow creating planes from descriptors

lib/core/Canvas.js

@@ -369,38 +369,42 @@ Canvas.prototype.getPlane = function(name) {
  * Creates a plane that is used to draw elements on it. If no
  * root element is provided, an implicit root will be used.
  *
- * @param {string} name
+ * @param {string|Object} plane
  * @param {Object|djs.model.Root} [rootElement] optional root element
  *
  * @return {Object} plane descriptor with { layer, rootElement, name }
  */
-Canvas.prototype.createPlane = function(name, rootElement) {
-  if (!name) {
-    throw new Error('must specify a name');
+Canvas.prototype.createPlane = function(plane, rootElement) {
+  if (!plane) {
+    throw new Error('must specify a plane');
+  }
+
+  if (this._planes[plane] || this._planes[plane.name]) {
+    throw new Error('plane <' + plane + '> already exists');
+  }
+
+  if (typeof plane === 'string') {
+    plane = { name: plane };
   }
 
-  if (this._planes[name]) {
-    throw new Error('plane <' + name + '> already exists');
+  if (!plane.layer) {
+    var svgLayer = this.getLayer(plane.name, PLANE_LAYER_INDEX);
+    svgAttr(svgLayer, 'display', 'none');
+
+    plane.layer = svgLayer;
   }
 
-  if (!rootElement) {
-    rootElement = {
-      id: '__implicitroot' + name,
+  if (!plane.rootElement) {
+    plane.rootElement = rootElement || {
+      id: '__implicitroot' + plane.name,
       children: [],
       isImplicit: true
     };
   }
 
-  var svgLayer = this.getLayer(name, PLANE_LAYER_INDEX);
-  svgAttr(svgLayer, 'display', 'none');
+  this._addRoot(plane.rootElement, plane);
 
-  var plane = this._planes[name] = {
-    layer: svgLayer,
-    name: name,
-    rootElement: null
-  };
-
-  this.setRootElementForPlane(rootElement, plane);
+  this._planes[plane.name] = plane;
 
   return plane;
 };
@@ -517,6 +521,8 @@ Canvas.prototype.removePlane = function(plane) {
 
   delete this._planes[plane.name];
 
+  this._removeRoot(plane.rootElement);
+
   if (plane === this._activePlane) {
     this._activePlane = null;
   }
@@ -734,41 +740,55 @@ Canvas.prototype.setRootElementForPlane = function(element, plane, override) {
     this._ensureValid('root', element);
   }
 
-  var currentRoot = plane.rootElement,
-      elementRegistry = this._elementRegistry,
-      eventBus = this._eventBus;
+  var currentRoot = plane.rootElement;
 
   if (currentRoot) {
     if (!override) {
       throw new Error('rootElement already set, need to specify override');
     }
 
-    // simulate element remove event sequence
-    eventBus.fire('root.remove', { element: currentRoot });
-    eventBus.fire('root.removed', { element: currentRoot });
-
-    elementRegistry.remove(currentRoot);
+    this._removeRoot(currentRoot);
   }
 
   if (element) {
-    var gfx = plane.layer;
+    this._addRoot(element, plane);
+  }
+
+  plane.rootElement = element;
 
-    // resemble element add event sequence
-    eventBus.fire('root.add', { element: element });
+  return element;
+};
 
-    elementRegistry.add(element, gfx);
 
-    eventBus.fire('root.added', { element: element, gfx: gfx });
+Canvas.prototype._removeRoot = function(element) {
+  var elementRegistry = this._elementRegistry,
+      eventBus = this._eventBus;
 
-    // associate SVG with root element when active
-    if (plane === this._activePlane) {
-      this._elementRegistry.updateGraphics(element, this._svg, true);
-    }
-  }
+  // simulate element remove event sequence
+  eventBus.fire('root.remove', { element: element });
+  eventBus.fire('root.removed', { element: element });
 
-  plane.rootElement = element;
+  elementRegistry.remove(element);
+};
 
-  return element;
+
+Canvas.prototype._addRoot = function(element, plane) {
+  var elementRegistry = this._elementRegistry,
+      eventBus = this._eventBus;
+
+  var gfx = plane.layer;
+
+  // resemble element add event sequence
+  eventBus.fire('root.add', { element: element });
+
+  elementRegistry.add(element, gfx);
+
+  eventBus.fire('root.added', { element: element, gfx: gfx });
+
+  // associate SVG with root element when active
+  if (plane === this._activePlane) {
+    this._elementRegistry.updateGraphics(element, this._svg, true);
+  }
 };
 
 // add functionality //////////////////////

test/spec/core/CanvasSpec.js

@@ -2232,13 +2232,32 @@ describe('Canvas', function() {
 
     describe('#createPlane', function() {
 
-      it('should expect a name', inject(function(canvas) {
+      it('should expect a plane', inject(function(canvas) {
 
         expect(function() {
 
           // when
           canvas.createPlane();
-        }).to.throw('must specify a name');
+        }).to.throw('must specify a plane');
+      }));
+
+
+      it('should accept a plane descriptor', inject(function(canvas, elementRegistry) {
+
+        // given
+        var plane = {
+          name: 'a',
+          rootElement: { id: 'root' },
+          layer: canvas.getLayer('a')
+        };
+
+        // when
+        canvas.createPlane(plane);
+
+        // then
+        expect(canvas.getPlane('a')).to.exist;
+        expect(canvas.getPlane('a')).to.equal(plane);
+        expect(elementRegistry.get('root')).to.exist;
       }));
 
 
@@ -2389,6 +2408,36 @@ describe('Canvas', function() {
         expect(canvas.getActivePlane().name).to.equal('base');
       }));
 
+
+      it('should remove root element', inject(function(canvas, elementRegistry) {
+
+        // given
+        var rootElement = { id: 'root' };
+        canvas.createPlane('a', rootElement);
+
+        // when
+        canvas.removePlane('a');
+
+        // then
+        expect(elementRegistry.get('root')).not.to.exist;
+      }));
+
+
+      it('should return valid plane descriptor', inject(function(canvas) {
+
+        // given
+        var rootElement = { id: 'root' };
+        canvas.createPlane('a', rootElement);
+
+        // when
+        var plane = canvas.removePlane('a');
+        canvas.createPlane(plane);
+
+        // then
+        expect(canvas.getPlane('a')).to.exist;
+        expect(canvas.getPlane('a').rootElement).to.eql(rootElement);
+      }));
+
     });
 
 
@@ -2417,6 +2466,24 @@ describe('Canvas', function() {
       }));
 
 
+      it('should fill missing plane attributes', inject(function(canvas) {
+
+        // given
+        var plane = {
+          name: 'a'
+        };
+
+        // when
+        canvas.createPlane(plane);
+
+        // then
+        expect(canvas.getPlane('a')).to.exist;
+        expect(canvas.getPlane('a')).to.equal(plane);
+        expect(plane.rootElement).to.exist;
+        expect(plane.layer).to.exist;
+      }));
+
+
       it('should rename the plane', inject(function(canvas) {
 
         // given