feat: add top level save and load functions for JSO serialization (…

…#5132)

* Add top-level serialization API

* Add using JSO system in serializer tests

* Make compiler happy

core/requires.js

@@ -82,5 +82,4 @@ goog.require('Blockly.zelos.Renderer');
 // Classic is the default theme.
 goog.require('Blockly.Themes.Classic');
 
-goog.require('Blockly.serialization.blocks');
-goog.require('Blockly.serialization.variables');
+goog.require('Blockly.serialization.workspaces');

core/serialization/blocks.js

@@ -17,6 +17,8 @@ goog.module.declareLegacyNamespace();
 const Block = goog.requireType('Blockly.Block');
 // eslint-disable-next-line no-unused-vars
 const Connection = goog.requireType('Blockly.Connection');
+// eslint-disable-next-line no-unused-vars
+const Workspace = goog.requireType('Blockly.Workspace');
 const Xml = goog.require('Blockly.Xml');
 const inputTypes = goog.require('Blockly.inputTypes');
 
@@ -255,3 +257,14 @@ const saveConnection = function(connection) {
   }
   return state;
 };
+
+/**
+ * Loads the block represented by the given state into the given workspace.
+ * @param {!State} state The state of a block to deserialize into the workspace.
+ * @param {!Workspace} workspace The workspace to add the block to.
+ */
+// eslint-disable-next-line no-unused-vars
+const load = function(state, workspace) {
+  // Temporarily NOP while connecting things together.
+};
+exports.load = load;

core/serialization/workspaces.js

@@ -0,0 +1,80 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview Contains top-level functions for serializing workspaces to
+ *     plain JavaScript objects.
+ */
+'use strict';
+
+goog.module('Blockly.serialization.workspaces');
+goog.module.declareLegacyNamespace();
+
+// eslint-disable-next-line no-unused-vars
+const Workspace = goog.require('Blockly.Workspace');
+const blocks = goog.require('Blockly.serialization.blocks');
+const variables = goog.require('Blockly.serialization.variables');
+
+
+/**
+ * Returns the state of the workspace as a plain JavaScript object.
+ * @param {!Workspace} workspace The workspace to serialize.
+ * @return {!Object<string, *>} The serialized state of the workspace.
+ */
+const save = function(workspace) {
+  const state = Object.create(null);
+
+  // TODO: Switch this to use plugin serialization system (once it is built).
+  const variableState = [];
+  const vars = workspace.getAllVariables();
+  for (let i = 0; i < vars.length; i++) {
+    variableState.push(variables.save(vars[i]));
+  }
+  if (variableState.length) {
+    state['variables'] = variableState;
+  }
+
+  const blockState = [];
+  for (let block of workspace.getTopBlocks(false)) {
+    blockState.push(
+        blocks.save(block, {addCoordinates: true}));
+  }
+  if (blockState.length) {
+    // This is an object to support adding language version later.
+    state['blocks'] = {
+      'blocks': blockState
+    };
+  }
+
+  return state;
+};
+exports.save = save;
+
+/**
+ * Loads the variable represented by the given state into the given workspace.
+ * @param {!Object<string, *>} state The state of the workspace to deserialize
+ *     into the workspace.
+ * @param {!Workspace} workspace The workspace to add the new state to.
+ */
+const load = function(state, workspace) {
+  // TODO: Switch this to use plugin serialization system (once it is built).
+  // TODO: Add something for clearing the state before deserializing.
+
+  if (state['variables']) {
+    const variableStates = state['variables'];
+    for (let i = 0; i < variableStates.length; i++) {
+      variables.load(variableStates[i], workspace);
+    }
+  }
+
+  if (state['blocks']) {
+    const blockStates = state['blocks']['blocks'];
+    for (let i = 0; i < blockStates.length; i++) {
+      blocks.load(blockStates[i], workspace);
+    }
+  }
+};
+exports.load = load;

tests/mocha/serializer_test.js

@@ -1730,14 +1730,16 @@ Serializer.testSuites = [
 ];
 
 var runSerializerTestSuite = (serializer, deserializer, testSuite) => {
+  const workspaces = Blockly.serialization.workspaces;
 
   const createTestFunction = function(test) {
     return function() {
       Blockly.Xml.domToWorkspace(
           Blockly.Xml.textToDom(test.xml), this.workspace);
       if (serializer && deserializer) {
-        // TODO: Add support for custom serializeers and deserializers.
-        //    Will be added once we have the JSO format working.
+        const save = serializer(workspaces.save(this.workspace));
+        this.workspace.clear();
+        workspaces.load(deserializer(save), this.workspace);
       }
       var newXml = Blockly.Xml.workspaceToDom(this.workspace);
       chai.assert.equal(Blockly.Xml.domToText(newXml), test.xml);
@@ -1770,3 +1772,5 @@ var runSerializerTestSuite = (serializer, deserializer, testSuite) => {
 };
 
 runSerializerTestSuite(null, null, Serializer);
+Serializer.skip = true;
+runSerializerTestSuite(state => state, state => state, Serializer);