Toolbox Customization Codelab
- - - - - - diff --git a/packages/docs/docs/codelabs/custom-toolbox/complete-code/index.js b/packages/docs/docs/codelabs/custom-toolbox/complete-code/index.js deleted file mode 100644 index adddf0322c4..00000000000 --- a/packages/docs/docs/codelabs/custom-toolbox/complete-code/index.js +++ /dev/null @@ -1,10 +0,0 @@ -'use strict'; - -let workspace = null; - -function start() { - // Create main workspace. - workspace = Blockly.inject('blocklyDiv', { - toolbox: document.getElementById('toolbox-categories'), - }); -} diff --git a/packages/docs/docs/codelabs/custom-toolbox/complete-code/logo_only.svg b/packages/docs/docs/codelabs/custom-toolbox/complete-code/logo_only.svg deleted file mode 100644 index 4616ee99f98..00000000000 --- a/packages/docs/docs/codelabs/custom-toolbox/complete-code/logo_only.svg +++ /dev/null @@ -1,76 +0,0 @@ - - diff --git a/packages/docs/docs/codelabs/custom-toolbox/complete-code/package.json b/packages/docs/docs/codelabs/custom-toolbox/complete-code/package.json new file mode 100644 index 00000000000..d7795717c77 --- /dev/null +++ b/packages/docs/docs/codelabs/custom-toolbox/complete-code/package.json @@ -0,0 +1,29 @@ +{ + "name": "custom-toolbox-codelab", + "version": "1.0.0", + "description": "A sample app using Blockly", + "main": "index.js", + "private": true, + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1", + "build": "webpack --mode production", + "start": "webpack serve --open --mode development" + }, + "keywords": [ + "blockly" + ], + "author": "", + "license": "Apache-2.0", + "devDependencies": { + "css-loader": "^6.7.1", + "html-webpack-plugin": "^5.5.0", + "source-map-loader": "^4.0.1", + "style-loader": "^3.3.1", + "webpack": "^5.93.0", + "webpack-cli": "^5.1.4", + "webpack-dev-server": "^5.0.4" + }, + "dependencies": { + "blockly": "^13.0.0" + } +} diff --git a/packages/docs/docs/codelabs/custom-toolbox/complete-code/src/blocks/text.js b/packages/docs/docs/codelabs/custom-toolbox/complete-code/src/blocks/text.js new file mode 100644 index 00000000000..244eaf1c9d4 --- /dev/null +++ b/packages/docs/docs/codelabs/custom-toolbox/complete-code/src/blocks/text.js @@ -0,0 +1,35 @@ +/** + * @license + * Copyright 2026 Raspberry Pi Foundation + * SPDX-License-Identifier: Apache-2.0 + */ + +import * as Blockly from 'blockly/core'; + +// Create a custom block called 'add_text' that adds +// text to the output div on the sample app. +// This is just an example and you should replace this with your +// own custom blocks. +const addText = { + type: 'add_text', + message0: 'Add text %1', + args0: [ + { + type: 'input_value', + name: 'TEXT', + check: 'String', + }, + ], + previousStatement: null, + nextStatement: null, + colour: 160, + tooltip: '', + helpUrl: '', +}; + +// Create the block definitions for the JSON-only blocks. +// This does not register their definitions with Blockly. +// This file has no side effects! +export const blocks = Blockly.common.createBlockDefinitionsFromJsonArray([ + addText, +]); diff --git a/packages/docs/docs/codelabs/custom-toolbox/complete-code/custom_category_es6.js b/packages/docs/docs/codelabs/custom-toolbox/complete-code/src/custom_category.js similarity index 81% rename from packages/docs/docs/codelabs/custom-toolbox/complete-code/custom_category_es6.js rename to packages/docs/docs/codelabs/custom-toolbox/complete-code/src/custom_category.js index c9c15ec34fd..3a4a0a00d4f 100644 --- a/packages/docs/docs/codelabs/custom-toolbox/complete-code/custom_category_es6.js +++ b/packages/docs/docs/codelabs/custom-toolbox/complete-code/src/custom_category.js @@ -1,6 +1,6 @@ /** * @license - * Copyright 2020 Google LLC + * Copyright 2026 Raspberry Pi Foundation * SPDX-License-Identifier: Apache-2.0 */ @@ -9,6 +9,8 @@ * @author aschmiedt@google.com (Abby Schmiedt) */ +import * as Blockly from 'blockly'; + class CustomCategory extends Blockly.ToolboxCategory { /** * Constructor for a custom category. @@ -34,6 +36,7 @@ class CustomCategory extends Blockly.ToolboxCategory { * @override */ setSelected(isSelected) { + super.setSelected(isSelected); // We do not store the label span on the category, so use getElementsByClassName. const labelDom = this.rowDiv_.getElementsByClassName( 'blocklyToolboxCategoryLabel', @@ -51,12 +54,6 @@ class CustomCategory extends Blockly.ToolboxCategory { labelDom.style.color = 'white'; this.iconDom_.style.color = 'white'; } - // This is used for accessibility purposes. - Blockly.utils.aria.setState( - /** @type {!Element} */ (this.htmlDiv_), - Blockly.utils.aria.State.SELECTED, - isSelected, - ); } /** @@ -65,12 +62,9 @@ class CustomCategory extends Blockly.ToolboxCategory { * @override */ createIconDom_() { - const iconImg = document.createElement('img'); - iconImg.src = './logo_only.svg'; - iconImg.alt = 'Blockly Logo'; - iconImg.width = '25'; - iconImg.height = '25'; - return iconImg; + const icon = document.createElement('span'); + icon.textContent = '🧰'; + return icon; } } diff --git a/packages/docs/docs/codelabs/custom-toolbox/complete-code/src/generators/javascript.js b/packages/docs/docs/codelabs/custom-toolbox/complete-code/src/generators/javascript.js new file mode 100644 index 00000000000..47bca6b2af4 --- /dev/null +++ b/packages/docs/docs/codelabs/custom-toolbox/complete-code/src/generators/javascript.js @@ -0,0 +1,30 @@ +/** + * @license + * Copyright 2026 Raspberry Pi Foundation + * SPDX-License-Identifier: Apache-2.0 + */ + +import { Order } from 'blockly/javascript'; + +// Export all the code generators for our custom blocks, +// but don't register them with Blockly yet. +// This file has no side effects! +export const forBlock = Object.create(null); + +forBlock['add_text'] = function (block, generator) { + const text = generator.valueToCode(block, 'TEXT', Order.NONE) || "''"; + const addText = generator.provideFunction_( + 'addText', + `function ${generator.FUNCTION_NAME_PLACEHOLDER_}(text) { + + // Add text to the output area. + const outputDiv = document.getElementById('output'); + const textEl = document.createElement('p'); + textEl.innerText = text; + outputDiv.appendChild(textEl); +}`, + ); + // Generate the function call for this block. + const code = `${addText}(${text});\n`; + return code; +}; diff --git a/packages/docs/docs/codelabs/custom-toolbox/complete-code/src/index.css b/packages/docs/docs/codelabs/custom-toolbox/complete-code/src/index.css new file mode 100644 index 00000000000..f282700701f --- /dev/null +++ b/packages/docs/docs/codelabs/custom-toolbox/complete-code/src/index.css @@ -0,0 +1,40 @@ +body { + margin: 0; + max-width: 100vw; +} + +pre, +code { + overflow: auto; +} + +#pageContainer { + display: flex; + width: 100%; + max-width: 100vw; + height: 100vh; +} + +#blocklyDiv { + flex-basis: 100%; + height: 100%; + min-width: 600px; +} + +#outputPane { + display: flex; + flex-direction: column; + width: 400px; + flex: 0 0 400px; + overflow: auto; + margin: 1rem; +} + +#generatedCode { + height: 50%; + background-color: rgb(247, 240, 228); +} + +#output { + height: 50%; +} diff --git a/packages/docs/docs/codelabs/custom-toolbox/complete-code/src/index.html b/packages/docs/docs/codelabs/custom-toolbox/complete-code/src/index.html new file mode 100644 index 00000000000..401be7f17a7 --- /dev/null +++ b/packages/docs/docs/codelabs/custom-toolbox/complete-code/src/index.html @@ -0,0 +1,19 @@ + + + + +
+
+
+
diff --git a/packages/docs/docs/codelabs/custom-toolbox/complete-code/src/index.js b/packages/docs/docs/codelabs/custom-toolbox/complete-code/src/index.js
new file mode 100644
index 00000000000..e5c0a925bf5
--- /dev/null
+++ b/packages/docs/docs/codelabs/custom-toolbox/complete-code/src/index.js
@@ -0,0 +1,71 @@
+/**
+ * @license
+ * Copyright 2026 Raspberry Pi Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as Blockly from 'blockly';
+import { blocks } from './blocks/text';
+import { forBlock } from './generators/javascript';
+import { javascriptGenerator } from 'blockly/javascript';
+import { save, load } from './serialization';
+import { toolbox } from './toolbox';
+import './index.css';
+import './toolbox_style.css';
+import './custom_category.js';
+import './toolbox_label.js';
+
+// Register the blocks and generator with Blockly
+Blockly.common.defineBlocks(blocks);
+Object.assign(javascriptGenerator.forBlock, forBlock);
+
+// Set up UI elements and inject Blockly
+const codeDiv = document.getElementById('generatedCode').firstChild;
+const outputDiv = document.getElementById('output');
+const blocklyDiv = document.getElementById('blocklyDiv');
+const ws = Blockly.inject(blocklyDiv, { toolbox });
+
+// This function resets the code and output divs, shows the
+// generated code from the workspace, and evals the code.
+// In a real application, you probably shouldn't use `eval`.
+const runCode = () => {
+ const code = javascriptGenerator.workspaceToCode(ws);
+ codeDiv.innerText = code;
+
+ outputDiv.innerHTML = '';
+
+ // Wrap `eval` in a `try/catch` so that any runtime errors are
+ // logged to the console, instead of failing quietly.
+ try {
+ eval(code);
+ } catch (error) {
+ console.log(error);
+ }
+};
+
+// Load the initial state from storage and run the code.
+load(ws);
+runCode();
+
+// Every time the workspace changes state, save the changes to storage.
+ws.addChangeListener((e) => {
+ // UI events are things like scrolling, zooming, etc.
+ // No need to save after one of these.
+ if (e.isUiEvent) return;
+ save(ws);
+});
+
+// Whenever the workspace changes meaningfully, run the code again.
+ws.addChangeListener((e) => {
+ // Don't run the code when the workspace finishes loading; we're
+ // already running it once when the application starts.
+ // Don't run the code during drags; we might have invalid state.
+ if (
+ e.isUiEvent ||
+ e.type == Blockly.Events.FINISHED_LOADING ||
+ ws.isDragging()
+ ) {
+ return;
+ }
+ runCode();
+});
diff --git a/packages/docs/docs/codelabs/custom-toolbox/complete-code/src/serialization.js b/packages/docs/docs/codelabs/custom-toolbox/complete-code/src/serialization.js
new file mode 100644
index 00000000000..175efa14f39
--- /dev/null
+++ b/packages/docs/docs/codelabs/custom-toolbox/complete-code/src/serialization.js
@@ -0,0 +1,32 @@
+/**
+ * @license
+ * Copyright 2026 Raspberry Pi Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as Blockly from 'blockly/core';
+
+const storageKey = 'customToolboxWorkspace';
+
+/**
+ * Saves the state of the workspace to browser's local storage.
+ * @param {Blockly.Workspace} workspace Blockly workspace to save.
+ */
+export const save = function (workspace) {
+ const data = Blockly.serialization.workspaces.save(workspace);
+ window.localStorage?.setItem(storageKey, JSON.stringify(data));
+};
+
+/**
+ * Loads saved state from local storage into the given workspace.
+ * @param {Blockly.Workspace} workspace Blockly workspace to load into.
+ */
+export const load = function (workspace) {
+ const data = window.localStorage?.getItem(storageKey);
+ if (!data) return;
+
+ // Don't emit events during loading.
+ Blockly.Events.disable();
+ Blockly.serialization.workspaces.load(JSON.parse(data), workspace, false);
+ Blockly.Events.enable();
+};
diff --git a/packages/docs/docs/codelabs/custom-toolbox/complete-code/src/toolbox.js b/packages/docs/docs/codelabs/custom-toolbox/complete-code/src/toolbox.js
new file mode 100644
index 00000000000..49efff4d421
--- /dev/null
+++ b/packages/docs/docs/codelabs/custom-toolbox/complete-code/src/toolbox.js
@@ -0,0 +1,636 @@
+/**
+ * @license
+ * Copyright 2026 Raspberry Pi Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/*
+This toolbox contains nearly every single built-in block that Blockly offers,
+in addition to the custom block 'add_text' this sample app adds.
+You probably don't need every single block, and should consider either rewriting
+your toolbox from scratch, or carefully choosing whether you need each block
+listed here.
+*/
+
+export const toolbox = {
+ kind: 'categoryToolbox',
+ contents: [
+ {
+ kind: 'toolboxlabel',
+ name: 'Custom Toolbox',
+ colour: 'darkslategrey',
+ cssconfig: { label: 'customLabel' },
+ },
+ {
+ kind: 'category',
+ name: 'Logic',
+ categorystyle: 'logic_category',
+ cssconfig: { icon: 'customIcon fa fa-cog' },
+ contents: [
+ {
+ kind: 'block',
+ type: 'controls_if',
+ },
+ {
+ kind: 'block',
+ type: 'logic_compare',
+ },
+ {
+ kind: 'block',
+ type: 'logic_operation',
+ },
+ {
+ kind: 'block',
+ type: 'logic_negate',
+ },
+ {
+ kind: 'block',
+ type: 'logic_boolean',
+ },
+ {
+ kind: 'block',
+ type: 'logic_null',
+ },
+ {
+ kind: 'block',
+ type: 'logic_ternary',
+ },
+ ],
+ },
+ {
+ kind: 'category',
+ name: 'Loops',
+ categorystyle: 'loop_category',
+ contents: [
+ {
+ kind: 'block',
+ type: 'controls_repeat_ext',
+ inputs: {
+ TIMES: {
+ shadow: {
+ type: 'math_number',
+ fields: {
+ NUM: 10,
+ },
+ },
+ },
+ },
+ },
+ {
+ kind: 'block',
+ type: 'controls_whileUntil',
+ },
+ {
+ kind: 'block',
+ type: 'controls_for',
+ inputs: {
+ FROM: {
+ shadow: {
+ type: 'math_number',
+ fields: {
+ NUM: 1,
+ },
+ },
+ },
+ TO: {
+ shadow: {
+ type: 'math_number',
+ fields: {
+ NUM: 10,
+ },
+ },
+ },
+ BY: {
+ shadow: {
+ type: 'math_number',
+ fields: {
+ NUM: 1,
+ },
+ },
+ },
+ },
+ },
+ {
+ kind: 'block',
+ type: 'controls_forEach',
+ },
+ {
+ kind: 'block',
+ type: 'controls_flow_statements',
+ },
+ ],
+ },
+ {
+ kind: 'category',
+ name: 'Math',
+ categorystyle: 'math_category',
+ contents: [
+ {
+ kind: 'block',
+ type: 'math_number',
+ fields: {
+ NUM: 123,
+ },
+ },
+ {
+ kind: 'block',
+ type: 'math_arithmetic',
+ inputs: {
+ A: {
+ shadow: {
+ type: 'math_number',
+ fields: {
+ NUM: 1,
+ },
+ },
+ },
+ B: {
+ shadow: {
+ type: 'math_number',
+ fields: {
+ NUM: 1,
+ },
+ },
+ },
+ },
+ },
+ {
+ kind: 'block',
+ type: 'math_single',
+ inputs: {
+ NUM: {
+ shadow: {
+ type: 'math_number',
+ fields: {
+ NUM: 9,
+ },
+ },
+ },
+ },
+ },
+ {
+ kind: 'block',
+ type: 'math_trig',
+ inputs: {
+ NUM: {
+ shadow: {
+ type: 'math_number',
+ fields: {
+ NUM: 45,
+ },
+ },
+ },
+ },
+ },
+ {
+ kind: 'block',
+ type: 'math_constant',
+ },
+ {
+ kind: 'block',
+ type: 'math_number_property',
+ inputs: {
+ NUMBER_TO_CHECK: {
+ shadow: {
+ type: 'math_number',
+ fields: {
+ NUM: 0,
+ },
+ },
+ },
+ },
+ },
+ {
+ kind: 'block',
+ type: 'math_round',
+ fields: {
+ OP: 'ROUND',
+ },
+ inputs: {
+ NUM: {
+ shadow: {
+ type: 'math_number',
+ fields: {
+ NUM: 3.1,
+ },
+ },
+ },
+ },
+ },
+ {
+ kind: 'block',
+ type: 'math_on_list',
+ fields: {
+ OP: 'SUM',
+ },
+ },
+ {
+ kind: 'block',
+ type: 'math_modulo',
+ inputs: {
+ DIVIDEND: {
+ shadow: {
+ type: 'math_number',
+ fields: {
+ NUM: 64,
+ },
+ },
+ },
+ DIVISOR: {
+ shadow: {
+ type: 'math_number',
+ fields: {
+ NUM: 10,
+ },
+ },
+ },
+ },
+ },
+ {
+ kind: 'block',
+ type: 'math_constrain',
+ inputs: {
+ VALUE: {
+ shadow: {
+ type: 'math_number',
+ fields: {
+ NUM: 50,
+ },
+ },
+ },
+ LOW: {
+ shadow: {
+ type: 'math_number',
+ fields: {
+ NUM: 1,
+ },
+ },
+ },
+ HIGH: {
+ shadow: {
+ type: 'math_number',
+ fields: {
+ NUM: 100,
+ },
+ },
+ },
+ },
+ },
+ {
+ kind: 'block',
+ type: 'math_random_int',
+ inputs: {
+ FROM: {
+ shadow: {
+ type: 'math_number',
+ fields: {
+ NUM: 1,
+ },
+ },
+ },
+ TO: {
+ shadow: {
+ type: 'math_number',
+ fields: {
+ NUM: 100,
+ },
+ },
+ },
+ },
+ },
+ {
+ kind: 'block',
+ type: 'math_random_float',
+ },
+ {
+ kind: 'block',
+ type: 'math_atan2',
+ inputs: {
+ X: {
+ shadow: {
+ type: 'math_number',
+ fields: {
+ NUM: 1,
+ },
+ },
+ },
+ Y: {
+ shadow: {
+ type: 'math_number',
+ fields: {
+ NUM: 1,
+ },
+ },
+ },
+ },
+ },
+ ],
+ },
+ {
+ kind: 'category',
+ name: 'Text',
+ categorystyle: 'text_category',
+ contents: [
+ {
+ kind: 'block',
+ type: 'text',
+ },
+ {
+ kind: 'block',
+ type: 'text_join',
+ },
+ {
+ kind: 'block',
+ type: 'text_append',
+ inputs: {
+ TEXT: {
+ shadow: {
+ type: 'text',
+ fields: {
+ TEXT: '',
+ },
+ },
+ },
+ },
+ },
+ {
+ kind: 'block',
+ type: 'text_length',
+ inputs: {
+ VALUE: {
+ shadow: {
+ type: 'text',
+ fields: {
+ TEXT: 'abc',
+ },
+ },
+ },
+ },
+ },
+ {
+ kind: 'block',
+ type: 'text_isEmpty',
+ inputs: {
+ VALUE: {
+ shadow: {
+ type: 'text',
+ fields: {
+ TEXT: '',
+ },
+ },
+ },
+ },
+ },
+ {
+ kind: 'block',
+ type: 'text_indexOf',
+ inputs: {
+ VALUE: {
+ block: {
+ type: 'variables_get',
+ },
+ },
+ FIND: {
+ shadow: {
+ type: 'text',
+ fields: {
+ TEXT: 'abc',
+ },
+ },
+ },
+ },
+ },
+ {
+ kind: 'block',
+ type: 'text_charAt',
+ inputs: {
+ VALUE: {
+ block: {
+ type: 'variables_get',
+ },
+ },
+ },
+ },
+ {
+ kind: 'block',
+ type: 'text_getSubstring',
+ inputs: {
+ STRING: {
+ block: {
+ type: 'variables_get',
+ },
+ },
+ },
+ },
+ {
+ kind: 'block',
+ type: 'text_changeCase',
+ inputs: {
+ TEXT: {
+ shadow: {
+ type: 'text',
+ fields: {
+ TEXT: 'abc',
+ },
+ },
+ },
+ },
+ },
+ {
+ kind: 'block',
+ type: 'text_trim',
+ inputs: {
+ TEXT: {
+ shadow: {
+ type: 'text',
+ fields: {
+ TEXT: 'abc',
+ },
+ },
+ },
+ },
+ },
+ {
+ kind: 'block',
+ type: 'text_count',
+ inputs: {
+ SUB: {
+ shadow: {
+ type: 'text',
+ },
+ },
+ TEXT: {
+ shadow: {
+ type: 'text',
+ },
+ },
+ },
+ },
+ {
+ kind: 'block',
+ type: 'text_replace',
+ inputs: {
+ FROM: {
+ shadow: {
+ type: 'text',
+ },
+ },
+ TO: {
+ shadow: {
+ type: 'text',
+ },
+ },
+ TEXT: {
+ shadow: {
+ type: 'text',
+ },
+ },
+ },
+ },
+ {
+ kind: 'block',
+ type: 'text_reverse',
+ inputs: {
+ TEXT: {
+ shadow: {
+ type: 'text',
+ },
+ },
+ },
+ },
+ {
+ kind: 'block',
+ type: 'add_text',
+ inputs: {
+ TEXT: {
+ shadow: {
+ type: 'text',
+ fields: {
+ TEXT: 'abc',
+ },
+ },
+ },
+ },
+ },
+ ],
+ },
+ {
+ kind: 'category',
+ name: 'Lists',
+ categorystyle: 'list_category',
+ contents: [
+ {
+ kind: 'block',
+ type: 'lists_create_with',
+ },
+ {
+ kind: 'block',
+ type: 'lists_create_with',
+ },
+ {
+ kind: 'block',
+ type: 'lists_repeat',
+ inputs: {
+ NUM: {
+ shadow: {
+ type: 'math_number',
+ fields: {
+ NUM: 5,
+ },
+ },
+ },
+ },
+ },
+ {
+ kind: 'block',
+ type: 'lists_length',
+ },
+ {
+ kind: 'block',
+ type: 'lists_isEmpty',
+ },
+ {
+ kind: 'block',
+ type: 'lists_indexOf',
+ inputs: {
+ VALUE: {
+ block: {
+ type: 'variables_get',
+ },
+ },
+ },
+ },
+ {
+ kind: 'block',
+ type: 'lists_getIndex',
+ inputs: {
+ VALUE: {
+ block: {
+ type: 'variables_get',
+ },
+ },
+ },
+ },
+ {
+ kind: 'block',
+ type: 'lists_setIndex',
+ inputs: {
+ LIST: {
+ block: {
+ type: 'variables_get',
+ },
+ },
+ },
+ },
+ {
+ kind: 'block',
+ type: 'lists_getSublist',
+ inputs: {
+ LIST: {
+ block: {
+ type: 'variables_get',
+ },
+ },
+ },
+ },
+ {
+ kind: 'block',
+ type: 'lists_split',
+ inputs: {
+ DELIM: {
+ shadow: {
+ type: 'text',
+ fields: {
+ TEXT: ',',
+ },
+ },
+ },
+ },
+ },
+ {
+ kind: 'block',
+ type: 'lists_sort',
+ },
+ {
+ kind: 'block',
+ type: 'lists_reverse',
+ },
+ ],
+ },
+ {
+ kind: 'sep',
+ },
+ {
+ kind: 'category',
+ name: 'Variables',
+ categorystyle: 'variable_category',
+ custom: 'VARIABLE',
+ },
+ {
+ kind: 'category',
+ name: 'Functions',
+ categorystyle: 'procedure_category',
+ custom: 'PROCEDURE',
+ },
+ ],
+};
diff --git a/packages/docs/docs/codelabs/custom-toolbox/complete-code/src/toolbox_label.js b/packages/docs/docs/codelabs/custom-toolbox/complete-code/src/toolbox_label.js
new file mode 100644
index 00000000000..ae1d0388b50
--- /dev/null
+++ b/packages/docs/docs/codelabs/custom-toolbox/complete-code/src/toolbox_label.js
@@ -0,0 +1,40 @@
+/**
+ * @license
+ * Copyright 2026 Raspberry Pi Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as Blockly from 'blockly';
+
+class ToolboxLabel extends Blockly.ToolboxItem {
+ constructor(toolboxItemDef, parentToolbox) {
+ super(toolboxItemDef, parentToolbox);
+ }
+
+ /** @override */
+ init() {
+ // Create the label.
+ this.label = document.createElement('label');
+ // Set the name.
+ this.label.textContent = this.toolboxItemDef_['name'];
+ // Set the color.
+ this.label.style.color = this.toolboxItemDef_['colour'];
+
+ const cssConfig = this.toolboxItemDef_['cssconfig'];
+ // Add the class.
+ if (cssConfig) {
+ this.label.classList.add(cssConfig['label']);
+ }
+ }
+
+ /** @override */
+ getDiv() {
+ return this.label;
+ }
+}
+
+Blockly.registry.register(
+ Blockly.registry.Type.TOOLBOX_ITEM,
+ 'toolboxlabel',
+ ToolboxLabel,
+);
diff --git a/packages/docs/docs/codelabs/custom-toolbox/complete-code/toolbox_style.css b/packages/docs/docs/codelabs/custom-toolbox/complete-code/src/toolbox_style.css
similarity index 94%
rename from packages/docs/docs/codelabs/custom-toolbox/complete-code/toolbox_style.css
rename to packages/docs/docs/codelabs/custom-toolbox/complete-code/src/toolbox_style.css
index 067e90aba74..c5916879067 100644
--- a/packages/docs/docs/codelabs/custom-toolbox/complete-code/toolbox_style.css
+++ b/packages/docs/docs/codelabs/custom-toolbox/complete-code/src/toolbox_style.css
@@ -16,6 +16,7 @@
.customIcon {
color: #fff;
}
+
/* Stacks the icon on top of the label. */
.blocklyTreeRowContentContainer {
display: flex;
@@ -25,3 +26,7 @@
.blocklyToolboxCategory {
height: initial;
}
+
+.customLabel {
+ font-weight: bold;
+}
diff --git a/packages/docs/docs/codelabs/custom-toolbox/complete-code/toolbox_label_es6.js b/packages/docs/docs/codelabs/custom-toolbox/complete-code/toolbox_label_es6.js
deleted file mode 100644
index 401ffa42aac..00000000000
--- a/packages/docs/docs/codelabs/custom-toolbox/complete-code/toolbox_label_es6.js
+++ /dev/null
@@ -1,63 +0,0 @@
-/**
- * @license
- * Copyright 2020 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-/**
- * @fileoverview The toolbox label built during the custom toolbox codelab, in es6.
- * @author aschmiedt@google.com (Abby Schmiedt)
- */
-
-class ToolboxLabel extends Blockly.ToolboxItem {
- /**
- * Constructor for a label in the toolbox.
- * @param {!Blockly.utils.toolbox.ToolboxItemInfo} toolboxItemDef The toolbox
- * item definition. This comes directly from the toolbox definition.
- * @param {!Blockly.IToolbox} parentToolbox The toolbox that holds this
- * toolbox item.
- * @override
- */
- constructor(toolboxItemDef, parentToolbox) {
- super(toolboxItemDef, parentToolbox);
- /**
- * The button element.
- * @type {?HTMLLabelElement}
- */
- this.label = null;
- }
-
- /**
- * Init method for the label.
- * @override
- */
- init() {
- // Create the label.
- this.label = document.createElement('label');
- // Set the name.
- this.label.textContent = this.toolboxItemDef_['name'];
- // Set the color.
- this.label.style.color = this.toolboxItemDef_['colour'];
- // Any attributes that begin with css- will get added to a cssconfig.
- const cssConfig = this.toolboxItemDef_['cssconfig'];
- // Add the class.
- if (cssConfig) {
- this.label.classList.add(cssConfig['label']);
- }
- }
-
- /**
- * Gets the div for the toolbox item.
- * @returns {HTMLLabelElement} The label element.
- * @override
- */
- getDiv() {
- return this.label;
- }
-}
-
-Blockly.registry.register(
- Blockly.registry.Type.TOOLBOX_ITEM,
- 'toolboxlabel',
- ToolboxLabel,
-);
diff --git a/packages/docs/docs/codelabs/custom-toolbox/complete-code/webpack.config.js b/packages/docs/docs/codelabs/custom-toolbox/complete-code/webpack.config.js
new file mode 100644
index 00000000000..1a095648fd7
--- /dev/null
+++ b/packages/docs/docs/codelabs/custom-toolbox/complete-code/webpack.config.js
@@ -0,0 +1,59 @@
+const path = require('path');
+const HtmlWebpackPlugin = require('html-webpack-plugin');
+
+// Base config that applies to either development or production mode.
+const config = {
+ entry: './src/index.js',
+ output: {
+ // Compile the source files into a bundle.
+ filename: 'bundle.js',
+ path: path.resolve(__dirname, 'dist'),
+ clean: true,
+ },
+ // Enable webpack-dev-server to get hot refresh of the app.
+ devServer: {
+ static: './build',
+ },
+ module: {
+ rules: [
+ {
+ // Load CSS files. They can be imported into JS files.
+ test: /\.css$/i,
+ use: ['style-loader', 'css-loader'],
+ },
+ ],
+ },
+ plugins: [
+ // Generate the HTML index page based on our template.
+ // This will output the same index page with the bundle we
+ // created above added in a script tag.
+ new HtmlWebpackPlugin({
+ template: 'src/index.html',
+ }),
+ ],
+};
+
+module.exports = (env, argv) => {
+ if (argv.mode === 'development') {
+ // Set the output path to the `build` directory
+ // so we don't clobber production builds.
+ config.output.path = path.resolve(__dirname, 'build');
+
+ // Generate source maps for our code for easier debugging.
+ // Not suitable for production builds. If you want source maps in
+ // production, choose a different one from https://webpack.js.org/configuration/devtool
+ config.devtool = 'eval-cheap-module-source-map';
+
+ // Include the source maps for Blockly for easier debugging Blockly code.
+ config.module.rules.push({
+ test: /(blockly[/\\].*\.js)$/,
+ use: [require.resolve('source-map-loader')],
+ enforce: 'pre',
+ });
+
+ // Ignore spurious warnings from source-map-loader
+ // It can't find source maps for some Closure modules and that is expected
+ config.ignoreWarnings = [/Failed to parse source map.*blockly/];
+ }
+ return config;
+};
diff --git a/packages/docs/docs/codelabs/custom-toolbox/setup.mdx b/packages/docs/docs/codelabs/custom-toolbox/setup.mdx
index a0e2fe013c6..59fa432e34b 100644
--- a/packages/docs/docs/codelabs/custom-toolbox/setup.mdx
+++ b/packages/docs/docs/codelabs/custom-toolbox/setup.mdx
@@ -8,92 +8,34 @@ import Image from '@site/src/components/Image';
## 2. Setup
-### Download the sample code
+### Create the application
-You can get the sample code for this codelab by either downloading the zip here:
+Use the [`npx @blockly/create-package app`](https://www.npmjs.com/package/@blockly/create-package) command to create a standalone application that contains a sample setup of Blockly, including custom blocks and a display of the generated code and output.
-[Download zip](https://github.com/RaspberryPiFoundation/blockly/archive/main.zip)
+1. Run `npx @blockly/create-package app custom-toolbox-codelab` in your terminal. This will create a Blockly application in the folder `custom-toolbox-codelab`.
+1. Use `cd` to move into the new directory: `cd custom-toolbox-codelab`.
+1. Run `npm start` to start the server and run the sample application.
+1. The sample app will automatically run in the browser window that opens.
-or by cloning this git repo:
+The local address in the address bar of your browser starting with `http://localhost:` shows where your app is.
+If you accidentally close this window or tab, you can re-open this local address to view the app as long as `npm start` is still running.
-```bash
-git clone https://github.com/RaspberryPiFoundation/blockly.git
-```
-
-If you downloaded the source as a zip, unpacking it should give you a root folder named `blockly-main`.
-
-The relevant files are in `packages/docs/docs/codelabs/custom-toolbox`. There are two versions of the app:
-
-- `starter-code/`: The starter code that you'll build upon in this codelab.
-- `complete-code/`: The code after completing the codelab, in case you get lost or want to compare to your version.
-
-Each folder contains:
+The initial application has a toolbox definition included in already included in the `toolbox.js` file.
+This codelab focuses on customizing the *appearance* of a Blockly toolbox rather than the content and categories, but feel free to experiment with customizing the content of the toolbox in `toolbox.js`.
-- `index.js` - The codelab's logic. To start, it just injects a simple workspace.
-- `index.html` - A web page containing a simple blockly workspace.
+### Change the storage key
-To run the code, simply open `starter-code/index.html` in a browser. You should see a Blockly workspace with a toolbox.
-
-
-
-### Define and register a custom category
-
-To start, create a file named `custom_category.js` in the `starter-code`
-directory. Include your new file by adding a script tag to `index.html`.
-
-```html
-
-```
+Before setting up the rest of the application, **change the storage key** used for this codelab application. This will ensure that the workspace is saved in its own storage, separate from the regular sample app, so that it doesn't interfere with other demos.
-In order to create a custom category we will create a new category that extends
-the default `Blockly.ToolboxCategory` class. Add the following code to your
-`custom_category.js` file.
+In `serialization.js`, change the value of `storageKey` to some unique string. `customToolboxWorkspace` will work:
```js
-class CustomCategory extends Blockly.ToolboxCategory {
- /**
- * Constructor for a custom category.
- * @override
- */
- constructor(categoryDef, toolbox, opt_parent) {
- super(categoryDef, toolbox, opt_parent);
- }
-}
+// Use a unique storage key for this codelab
+const storageKey = 'customToolboxWorkspace';
```
-After defining your category you need to tell Blockly that it exists.
-Register your category by adding the below code to the end of `custom_category.js`.
+### Explore the starter code
-```js
-Blockly.registry.register(
- Blockly.registry.Type.TOOLBOX_ITEM,
- Blockly.ToolboxCategory.registrationName,
- CustomCategory,
- true,
-);
-```
-
-By registering our `CustomCategory` with `Blockly.ToolboxCategory.registrationName`
-we are overriding the default category in Blockly. Because we are overriding a
-toolbox item instead of adding a new one, we must pass in `true` as the last
-argument. If this flag is `false`, `Blockly.registry.register` will throw
-an error because we are overriding an existing class.
-
-### The result
-
-To test, open `index.html` in a browser. Your toolbox should look the same as it
-did before.
+Take a moment to explore the code you just created in the `custom-toolbox-codelab` folder. If you'd like a more in-depth explanation of all of the code in the sample app, you can go through the [getting started codelab](/codelabs/getting-started/codelab-overview) which goes through creating this sample app from scratch.
-
+
+
+