Add serialization of mutators (#5054)

* Add tests for saving extra state

* Add serializing extra state

* Fix backwards compatibility

* Switch to other function declarations

* Handle null returns from hooks

* Remove backwards compatibility

* Remove XML require, and fix type

* Fix JSDoc formatting

core/serialization/blocks.js

@@ -31,6 +31,7 @@ goog.module.declareLegacyNamespace();
  *     movable: (boolean|undefined),
  *     inline: (boolean|undefined),
  *     data: (string|undefined),
+ *     extra-state: *
  * }}
  */
 var State;
@@ -60,6 +61,7 @@ const save = function(block, {addCoordinates = false} = {}) {
     addCoords(block, state);
   }
   addAttributes(block, state);
+  addExtraState(block, state);
 
   return state;
 };
@@ -69,8 +71,7 @@ exports.save = save;
  * Adds attributes to the given state object based on the state of the block.
  * Eg collapsed, disabled, editable, etc.
  * @param {!Blockly.Block} block The block to base the attributes on.
- * @param {!State} state The state object to append
- *     to.
+ * @param {!State} state The state object to append to.
  */
 const addAttributes = function(block, state) {
   if (block.isCollapsed()) {
@@ -103,8 +104,7 @@ const addAttributes = function(block, state) {
 /**
  * Adds the coordinates of the given block to the given state object.
  * @param {!Blockly.Block} block The block to base the coordinates on
- * @param {!State} state The state object to append
- *     to
+ * @param {!State} state The state object to append to
  */
 const addCoords = function(block, state) {
   const workspace = block.workspace;
@@ -112,3 +112,17 @@ const addCoords = function(block, state) {
   state['x'] = Math.round(workspace.RTL ? workspace.getWidth() - xy.x : xy.x);
   state['y'] = Math.round(xy.y);
 };
+
+/**
+ * Adds any extra state the block may provide to the given state object.
+ * @param {!Blockly.Block} block The block to serialize the extra state of.
+ * @param {!State} state The state object to append to.
+ */
+const addExtraState = function(block, state) {
+  if (block.saveExtraState) {
+    const extraState = block.saveExtraState();
+    if (extraState !== null) {
+      state['extraState'] = extraState;
+    }
+  }
+};

tests/mocha/jso_serialization_test.js

@@ -37,7 +37,7 @@ suite('JSO', function() {
     suite('Save Single Block', function() {
 
       function assertProperty(obj, property, value) {
-        chai.assert.equal(obj[property], value);
+        chai.assert.deepEqual(obj[property], value);
       }
 
       function assertNoProperty(obj, property) {
@@ -236,6 +236,44 @@ suite('JSO', function() {
           assertProperty(jso, 'y', 0);
         });
       });
+
+      // Mutators.
+      suite('Extra state', function() {
+        test('Simple value', function() {
+          const block = this.workspace.newBlock('row_block');
+          block.saveExtraState = function() {
+            return 'some extra state';
+          };
+          const jso = Blockly.serialization.blocks.save(block);
+          assertProperty(jso, 'extraState', 'some extra state');
+        });
+
+        test('Object', function() {
+          const block = this.workspace.newBlock('row_block');
+          block.saveExtraState = function() {
+            return {
+              'extra1': 'state1',
+              'extra2': 42,
+              'extra3': true,
+            };
+          };
+          const jso = Blockly.serialization.blocks.save(block);
+          assertProperty(jso, 'extraState', {
+            'extra1': 'state1',
+            'extra2': 42,
+            'extra3': true,
+          });
+        });
+
+        test('Array', function() {
+          const block = this.workspace.newBlock('row_block');
+          block.saveExtraState = function() {
+            return ['state1', 42, true];
+          };
+          const jso = Blockly.serialization.blocks.save(block);
+          assertProperty(jso, 'extraState', ['state1', 42, true]);
+        });
+      });
     });
   });
 });