blockly 12.3.0 → 12.4.0

package/demos/blockfactory/block_exporter_controller.js

@@ -0,0 +1,311 @@
+/**
+ * @license
+ * Copyright 2016 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview Javascript for the Block Exporter Controller class. Allows
+ * users to export block definitions and generator stubs of their saved blocks
+ * easily using a visual interface. Depends on Block Exporter View and Block
+ * Exporter Tools classes. Interacts with Export Settings in the index.html.
+ */
+
+'use strict';
+
+/**
+ * BlockExporter Controller Class
+ * @param {!BlockLibrary.Storage} blockLibStorage Block Library Storage.
+ * @constructor
+ */
+function BlockExporterController(blockLibStorage) {
+  // BlockLibrary.Storage object containing user's saved blocks.
+  this.blockLibStorage = blockLibStorage;
+  // Utils for generating code to export.
+  this.tools = new BlockExporterTools();
+  // The ID of the block selector, a div element that will be populated with the
+  // block options.
+  this.selectorID = 'blockSelector';
+  // Map of block types stored in block library to their corresponding Block
+  // Option objects.
+  this.blockOptions = this.tools.createBlockSelectorFromLib(
+      this.blockLibStorage, this.selectorID);
+  // View provides the block selector and export settings UI.
+  this.view = new BlockExporterView(this.blockOptions);
+};
+
+/**
+ * Set the block library storage object from which exporter exports.
+ * @param {!BlockLibraryStorage} blockLibStorage Block Library Storage object
+ *    that stores the blocks.
+ */
+BlockExporterController.prototype.setBlockLibraryStorage =
+    function(blockLibStorage) {
+  this.blockLibStorage = blockLibStorage;
+};
+
+/**
+ * Get the block library storage object from which exporter exports.
+ * @return {!BlockLibraryStorage} blockLibStorage Block Library Storage object
+ *    that stores the blocks.
+ */
+BlockExporterController.prototype.getBlockLibraryStorage =
+    function(blockLibStorage) {
+  return this.blockLibStorage;
+};
+
+/**
+ * Get selected blocks from block selector, pulls info from the Export
+ * Settings form in Block Exporter, and downloads code accordingly.
+ */
+BlockExporterController.prototype.export = function() {
+  // Get selected blocks' information.
+  var blockTypes = this.view.getSelectedBlockTypes();
+  var blockXmlMap = this.blockLibStorage.getBlockXmlMap(blockTypes);
+
+  // Pull block definition(s) settings from the Export Settings form.
+  var wantBlockDef = document.getElementById('blockDefCheck').checked;
+  var definitionFormat = document.getElementById('exportFormat').value;
+  var blockDef_filename = document.getElementById('blockDef_filename').value;
+
+  // Pull block generator stub(s) settings from the Export Settings form.
+  var wantGenStub = document.getElementById('genStubCheck').checked;
+  var language = document.getElementById('exportLanguage').value;
+  var generatorStub_filename = document.getElementById(
+      'generatorStub_filename').value;
+
+  if (wantBlockDef) {
+    // User wants to export selected blocks' definitions.
+    if (!blockDef_filename) {
+      // User needs to enter filename.
+      var msg = 'Please enter a filename for your block definition(s) download.';
+      BlocklyDevTools.Analytics.onWarning(msg);
+      alert(msg);
+    } else {
+      // Get block definition code in the selected format for the blocks.
+      var blockDefs = this.tools.getBlockDefinitions(blockXmlMap,
+          definitionFormat);
+      // Download the file, using .js file ending for JSON or Javascript.
+      FactoryUtils.createAndDownloadFile(
+          blockDefs, blockDef_filename, 'javascript');
+      BlocklyDevTools.Analytics.onExport(
+          BlocklyDevTools.Analytics.BLOCK_DEFINITIONS,
+          {
+            format: (definitionFormat === 'JSON' ?
+                BlocklyDevTools.Analytics.FORMAT_JSON :
+                BlocklyDevTools.Analytics.FORMAT_JS)
+          });
+    }
+  }
+
+  if (wantGenStub) {
+    // User wants to export selected blocks' generator stubs.
+    if (!generatorStub_filename) {
+      // User needs to enter filename.
+      var msg = 'Please enter a filename for your generator stub(s) download.';
+      BlocklyDevTools.Analytics.onWarning(msg);
+      alert(msg);
+    } else {
+
+      // Get generator stub code in the selected language for the blocks.
+      var genStubs = this.tools.getGeneratorCode(blockXmlMap,
+          language);
+
+      // Download the file.
+      FactoryUtils.createAndDownloadFile(
+          genStubs, generatorStub_filename + '.js', 'javascript');
+      BlocklyDevTools.Analytics.onExport(
+          BlocklyDevTools.Analytics.GENERATOR, { format: BlocklyDevTools.Analytics.FORMAT_JS });
+    }
+  }
+
+};
+
+/**
+ * Update the Exporter's block selector with block options generated from blocks
+ * stored in block library.
+ */
+BlockExporterController.prototype.updateSelector = function() {
+  // Get previously selected block types.
+  var oldSelectedTypes = this.view.getSelectedBlockTypes();
+
+  // Generate options from block library and assign to view.
+  this.blockOptions = this.tools.createBlockSelectorFromLib(
+      this.blockLibStorage, this.selectorID);
+  this.addBlockOptionSelectHandlers();
+  this.view.setBlockOptions(this.blockOptions);
+
+  // Select all previously selected blocks.
+  for (var i = 0, blockType; blockType = oldSelectedTypes[i]; i++) {
+    if (this.blockOptions[blockType]) {
+      this.view.select(blockType);
+    }
+  }
+
+  this.view.listSelectedBlocks();
+};
+
+/**
+ * Tied to the 'Clear Selected Blocks' button in the Block Exporter.
+ * Deselects all blocks in the selector and updates text accordingly.
+ */
+BlockExporterController.prototype.clearSelectedBlocks = function() {
+  this.view.deselectAllBlocks();
+  this.view.listSelectedBlocks();
+};
+
+/**
+ * Tied to the 'All Stored' button in the Block Exporter 'Select' dropdown.
+ * Selects all blocks stored in block library for export.
+ */
+BlockExporterController.prototype.selectAllBlocks = function() {
+  var allBlockTypes = this.blockLibStorage.getBlockTypes();
+  for (var i = 0, blockType; blockType = allBlockTypes[i]; i++) {
+    this.view.select(blockType);
+  }
+  this.view.listSelectedBlocks();
+};
+
+/**
+ * Returns the category XML containing all blocks in the block library.
+ * @return {Element} XML for a category to be used in toolbox.
+ */
+BlockExporterController.prototype.getBlockLibraryCategory = function() {
+  return this.tools.generateCategoryFromBlockLib(this.blockLibStorage);
+};
+
+/**
+ * Add select handlers to each block option to update the view and the selected
+ * blocks accordingly.
+ */
+BlockExporterController.prototype.addBlockOptionSelectHandlers = function() {
+  var self = this;
+
+  // Click handler for a block option. Toggles whether or not it's selected and
+  // updates helper text accordingly.
+  var updateSelectedBlockTypes_ = function(blockOption) {
+    // Toggle selected.
+    blockOption.setSelected(!blockOption.isSelected());
+
+    // Show currently selected blocks in helper text.
+    self.view.listSelectedBlocks();
+  };
+
+  // Returns a block option select handler.
+  var makeBlockOptionSelectHandler_ = function(blockOption) {
+    return function() {
+      updateSelectedBlockTypes_(blockOption);
+      self.updatePreview();
+    };
+  };
+
+  // Assign a click handler to each block option.
+  for (var blockType in this.blockOptions) {
+    var blockOption = this.blockOptions[blockType];
+    // Use an additional closure to correctly assign the tab callback.
+    blockOption.dom.addEventListener(
+        'click', makeBlockOptionSelectHandler_(blockOption));
+  }
+};
+
+/**
+ * Tied to the 'All Used' button in the Block Exporter's 'Select' button.
+ * Selects all blocks stored in block library and used in workspace factory.
+ */
+BlockExporterController.prototype.selectUsedBlocks = function() {
+  // Deselect all blocks.
+  this.view.deselectAllBlocks();
+
+  // Get list of block types that are in block library and used in workspace
+  // factory.
+  var storedBlockTypes = this.blockLibStorage.getBlockTypes();
+  var sharedBlockTypes = [];
+  // Keep list of custom block types used but not in library.
+  var unstoredCustomBlockTypes = [];
+
+  for (var i = 0, blockType; blockType = this.usedBlockTypes[i]; i++) {
+    if (storedBlockTypes.includes(blockType)) {
+      sharedBlockTypes.push(blockType);
+    } else if (!StandardCategories.coreBlockTypes.includes(blockType)) {
+      unstoredCustomBlockTypes.push(blockType);
+    }
+  }
+
+  // Select each shared block type.
+  for (var i = 0, blockType; blockType = sharedBlockTypes[i]; i++) {
+    this.view.select(blockType);
+  }
+  this.view.listSelectedBlocks();
+
+  if (unstoredCustomBlockTypes.length > 0) {
+    // Warn user to import block definitions and generator code for blocks
+    // not in their Block Library nor Blockly's standard library.
+    var blockTypesText = unstoredCustomBlockTypes.join(', ');
+    var customWarning = 'Custom blocks used in workspace factory but not ' +
+        'stored in block library:\n ' + blockTypesText +
+        '\n\nDon\'t forget to include block definitions and generator code ' +
+        'for these blocks.';
+    alert(customWarning);
+  }
+};
+
+/**
+ * Set the array that holds the block types used in workspace factory.
+ * @param {!Array<string>} usedBlockTypes Block types used in
+ */
+BlockExporterController.prototype.setUsedBlockTypes =
+    function(usedBlockTypes) {
+  this.usedBlockTypes = usedBlockTypes;
+};
+
+/**
+ * Updates preview code (block definitions and generator stubs) in the exporter
+ * preview to reflect selected blocks.
+ */
+BlockExporterController.prototype.updatePreview = function() {
+  // Generate preview code for selected blocks.
+  var blockDefs = this.getBlockDefinitionsOfSelected();
+  var genStubs = this.getGeneratorStubsOfSelected();
+
+  // Update the text areas containing the code.
+  FactoryUtils.injectCode(blockDefs, 'blockDefs_textArea');
+  FactoryUtils.injectCode(genStubs, 'genStubs_textArea');
+};
+
+/**
+ * Returns a map of each selected block's type to its corresponding XML.
+ * @return {!Object} A map of each selected block's type (a string) to its
+ * corresponding XML element.
+ */
+BlockExporterController.prototype.getSelectedBlockXmlMap = function() {
+  var blockTypes = this.view.getSelectedBlockTypes();
+  return this.blockLibStorage.getBlockXmlMap(blockTypes);
+};
+
+/**
+ * Get block definition code in the selected format for selected blocks.
+ * @return {string} The concatenation of each selected block's language code
+ * in the format specified in export settings.
+ */
+BlockExporterController.prototype.getBlockDefinitionsOfSelected = function() {
+  // Get selected blocks' information.
+  var blockXmlMap = this.getSelectedBlockXmlMap();
+
+  // Get block definition code in the selected format for the blocks.
+  var definitionFormat = document.getElementById('exportFormat').value;
+  return this.tools.getBlockDefinitions(blockXmlMap, definitionFormat);
+};
+
+/**
+ * Get generator stubs in the selected language for selected blocks.
+ * @return {string} The concatenation of each selected block's generator stub
+ * in the language specified in export settings.
+ */
+BlockExporterController.prototype.getGeneratorStubsOfSelected = function() {
+  // Get selected blocks' information.
+  var blockXmlMap = this.getSelectedBlockXmlMap();
+
+  // Get generator stub code in the selected language for the blocks.
+  var language = document.getElementById('exportLanguage').value;
+  return this.tools.getGeneratorCode(blockXmlMap, language);
+};

package/demos/blockfactory/block_exporter_tools.js

@@ -0,0 +1,212 @@
+/**
+ * @license
+ * Copyright 2016 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview Javascript for the BlockExporter Tools class, which generates
+ * block definitions and generator stubs for given block types.  Also generates
+ * toolbox XML for the exporter's workspace.  Depends on the FactoryUtils for
+ * its code generation functions.
+ */
+'use strict';
+
+/**
+ * Block Exporter Tools Class
+ * @constructor
+ */
+function BlockExporterTools() {
+  // Create container for hidden workspace.
+  this.container = document.createElement('div');
+  this.container.id = 'blockExporterTools_hiddenWorkspace';
+  this.container.style.display = 'none';  // Hide the hidden workspace.
+  document.body.appendChild(this.container);
+  /**
+   * Hidden workspace for the Block Exporter that holds pieces that make
+   * up the block
+   * @type {Blockly.Workspace}
+   */
+  this.hiddenWorkspace = Blockly.inject(this.container.id,
+      {collapse: false,
+       media: '../../media/'});
+};
+
+/**
+ * Get Blockly Block object from XML that encodes the blocks used to design
+ * the block.
+ * @param {!Element} xml XML element that encodes the blocks used to design
+ *    the block. For example, the block XMLs saved in block library.
+ * @return {!Blockly.Block} Root block (factory_base block) which contains
+ *    all information needed to generate block definition or null.
+ * @private
+ */
+BlockExporterTools.prototype.getRootBlockFromXml_ = function(xml) {
+  // Render XML in hidden workspace.
+  this.hiddenWorkspace.clear();
+  Blockly.Xml.domToWorkspace(xml, this.hiddenWorkspace);
+  // Get root block.
+  var rootBlock = this.hiddenWorkspace.getTopBlocks()[0] || null;
+  return rootBlock;
+};
+
+/**
+ * Return the given language code of each block type in an array.
+ * @param {!Object} blockXmlMap Map of block type to XML.
+ * @param {string} definitionFormat 'JSON' or 'JavaScript'
+ * @return {string} The concatenation of each block's language code in the
+ *    desired format.
+ */
+BlockExporterTools.prototype.getBlockDefinitions =
+    function(blockXmlMap, definitionFormat) {
+  var blockCode = [];
+  for (var blockType in blockXmlMap) {
+    var xml = blockXmlMap[blockType];
+    if (xml) {
+      // Render and get block from hidden workspace.
+      var rootBlock = this.getRootBlockFromXml_(xml);
+      if (rootBlock) {
+        // Generate the block's definition.
+        var code = FactoryUtils.getBlockDefinition(blockType, rootBlock,
+            definitionFormat, this.hiddenWorkspace);
+        // Add block's definition to the definitions to return.
+      } else {
+        // Append warning comment and write to console.
+        var code = '// No block definition generated for ' + blockType +
+          '. Could not find root block in XML stored for this block.';
+        console.log('No block definition generated for ' + blockType +
+          '. Could not find root block in XML stored for this block.');
+      }
+    } else {
+      // Append warning comment and write to console.
+      var code = '// No block definition generated for ' + blockType +
+        '. Block was not found in Block Library Storage.';
+      console.log('No block definition generated for ' + blockType +
+        '. Block was not found in Block Library Storage.');
+    }
+    blockCode.push(code);
+  }
+
+  // Surround json with [] and comma separate items.
+  if (definitionFormat === "JSON") {
+    return "[" + blockCode.join(",\n") + "]";
+  }
+  return blockCode.join("\n\n");
+};
+
+/**
+ * Return the generator code of each block type in an array in a given language.
+ * @param {!Object} blockXmlMap Map of block type to XML.
+ * @param {string} generatorLanguage E.g. 'JavaScript', 'Python', 'PHP', 'Lua',
+ *     'Dart'
+ * @return {string} The concatenation of each block's generator code in the
+ * desired format.
+ */
+BlockExporterTools.prototype.getGeneratorCode =
+    function(blockXmlMap, generatorLanguage) {
+  var multiblockCode = [];
+  // Define the custom blocks in order to be able to create instances of
+  // them in the exporter workspace.
+  this.addBlockDefinitions(blockXmlMap);
+
+  for (var blockType in blockXmlMap) {
+    var xml = blockXmlMap[blockType];
+    if (xml) {
+      // Render the preview block in the hidden workspace.
+      var tempBlock =
+          FactoryUtils.getDefinedBlock(blockType, this.hiddenWorkspace);
+      // Get generator stub for the given block and add to  generator code.
+      var blockGenCode =
+          FactoryUtils.getGeneratorStub(tempBlock, generatorLanguage);
+    } else {
+      // Append warning comment and write to console.
+      var blockGenCode = '// No generator stub generated for ' + blockType +
+        '. Block was not found in Block Library Storage.';
+      console.log('No block generator stub generated for ' + blockType +
+        '. Block was not found in Block Library Storage.');
+    }
+    multiblockCode.push(blockGenCode);
+  }
+  return multiblockCode.join("\n\n");
+};
+
+/**
+ * Evaluates block definition code of each block in given object mapping
+ * block type to XML. Called in order to be able to create instances of the
+ * blocks in the exporter workspace.
+ * @param {!Object} blockXmlMap Map of block type to XML.
+ */
+BlockExporterTools.prototype.addBlockDefinitions = function(blockXmlMap) {
+  var blockDefs = this.getBlockDefinitions(blockXmlMap, 'JavaScript');
+  eval(blockDefs);
+};
+
+/**
+ * Generate XML for the workspace factory's category from imported block
+ * definitions.
+ * @param {!BlockLibraryStorage} blockLibStorage Block Library Storage object.
+ * @return {!Element} XML representation of a category.
+ */
+BlockExporterTools.prototype.generateCategoryFromBlockLib =
+    function(blockLibStorage) {
+  var allBlockTypes = blockLibStorage.getBlockTypes();
+  // Object mapping block type to XML.
+  var blockXmlMap = blockLibStorage.getBlockXmlMap(allBlockTypes);
+
+  // Define the custom blocks in order to be able to create instances of
+  // them in the exporter workspace.
+  this.addBlockDefinitions(blockXmlMap);
+
+  // Get array of defined blocks.
+  var blocks = [];
+  for (var blockType in blockXmlMap) {
+    var block = FactoryUtils.getDefinedBlock(blockType, this.hiddenWorkspace);
+    blocks.push(block);
+  }
+
+  return FactoryUtils.generateCategoryXml(blocks,'Block Library');
+};
+
+/**
+ * Generate selector DOM from block library storage. For each block in the
+ * library, it has a block option, which consists of a checkbox, a label,
+ * and a fixed size preview workspace.
+ * @param {!BlockLibraryStorage} blockLibStorage Block Library Storage object.
+ * @param {string} blockSelectorId ID of the div element that will contain
+ *    the block options.
+ * @return {!Object} Map of block type to Block Option object.
+ */
+BlockExporterTools.prototype.createBlockSelectorFromLib =
+    function(blockLibStorage, blockSelectorId) {
+  // Object mapping each stored block type to XML.
+  var allBlockTypes = blockLibStorage.getBlockTypes();
+  var blockXmlMap = blockLibStorage.getBlockXmlMap(allBlockTypes);
+
+  // Define the custom blocks in order to be able to create instances of
+  // them in the exporter workspace.
+  this.addBlockDefinitions(blockXmlMap);
+
+  var blockSelector = document.getElementById(blockSelectorId);
+  // Clear the block selector.
+  var child;
+  while ((child = blockSelector.firstChild)) {
+    blockSelector.removeChild(child);
+  }
+
+  // Append each block option's dom to the selector.
+  var blockOptions = Object.create(null);
+  for (var blockType in blockXmlMap) {
+    // Get preview block's XML.
+    var block = FactoryUtils.getDefinedBlock(blockType, this.hiddenWorkspace);
+    var previewBlockXml = Blockly.Xml.workspaceToDom(this.hiddenWorkspace);
+
+    // Create block option, inject block into preview workspace, and append
+    // option to block selector.
+    var blockOpt = new BlockOption(blockSelector, blockType, previewBlockXml);
+    blockOpt.createDom();
+    blockSelector.appendChild(blockOpt.dom);
+    blockOpt.showPreviewBlock();
+    blockOptions[blockType] = blockOpt;
+  }
+  return blockOptions;
+};

package/demos/blockfactory/block_exporter_view.js

@@ -0,0 +1,101 @@
+/**
+ * @license
+ * Copyright 2016 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview Javascript for the Block Exporter View class. Reads from and
+ * manages a block selector through which users select blocks to export.
+ */
+
+'use strict';
+
+/**
+ * BlockExporter View Class
+ * @param {!Object} blockOptions Map of block types to BlockOption objects.
+ * @constructor
+ */
+function BlockExporterView(blockOptions) {
+  //  Map of block types to BlockOption objects to select from.
+  this.blockOptions = blockOptions;
+};
+
+/**
+ * Set the block options in the selector of this instance of
+ * BlockExporterView.
+ * @param {!Object} blockOptions Map of block types to BlockOption objects.
+ */
+BlockExporterView.prototype.setBlockOptions = function(blockOptions) {
+  this.blockOptions = blockOptions;
+};
+
+/**
+ * Updates the helper text to show list of currently selected blocks.
+ */
+BlockExporterView.prototype.listSelectedBlocks = function() {
+
+  var selectedBlocksText = this.getSelectedBlockTypes().join(",\n ");
+  document.getElementById('selectedBlocksText').textContent = selectedBlocksText;
+};
+
+/**
+ * Selects a given block type in the selector.
+ * @param {string} blockType Type of block to selector.
+ */
+BlockExporterView.prototype.select = function(blockType) {
+  this.blockOptions[blockType].setSelected(true);
+};
+
+/**
+ * Deselects a block in the selector.
+ * @param {!Blockly.Block} block Type of block to add to selector workspace.
+ */
+BlockExporterView.prototype.deselect = function(blockType) {
+  this.blockOptions[blockType].setSelected(false);
+};
+
+
+/**
+ * Deselects all blocks.
+ */
+BlockExporterView.prototype.deselectAllBlocks = function() {
+  for (var blockType in this.blockOptions) {
+    this.deselect(blockType);
+  }
+};
+
+/**
+ * Given an array of selected blocks, selects these blocks in the view, marking
+ * the checkboxes accordingly.
+ * @param {Array<Blockly.Block>} blockTypes Array of block types to select.
+ */
+BlockExporterView.prototype.setSelectedBlockTypes = function(blockTypes) {
+  for (var i = 0, blockType; blockType = blockTypes[i]; i++) {
+    this.select(blockType);
+  }
+};
+
+/**
+ * Returns array of selected blocks.
+ * @return {!Array<string>} Array of all selected block types.
+ */
+BlockExporterView.prototype.getSelectedBlockTypes = function() {
+  var selectedTypes = [];
+  for (var blockType in this.blockOptions) {
+    var blockOption = this.blockOptions[blockType];
+    if (blockOption.isSelected()) {
+      selectedTypes.push(blockType);
+    }
+  }
+  return selectedTypes;
+};
+
+/**
+ * Centers the preview block of each block option in the exporter selector.
+ */
+BlockExporterView.prototype.centerPreviewBlocks = function() {
+  for (var blockType in this.blockOptions) {
+    this.blockOptions[blockType].centerBlock();
+  }
+};