docs: refactor getting-started codelab to be based on sample app by zspriggs · Pull Request #10074 · RaspberryPiFoundation/blockly

zspriggs · 2026-06-26T16:48:05Z

The basics

I validated my changes

The details

Proposed Changes

Refactors the getting-started codelab to be based on the existing sample app rather than the custom music-maker app.
The content has remained the same where possible, with slightly more elaboration throughout on what the copy & paste code is actually doing.
The codelab goes over largely the same topics, but focuses more on important Blockly concepts than configuring a specific page.
Adds the sample app README to the getting started docs, so that the existence of the sample app is more visible and the overview can be referenced from the codelabs.

gonfunko · 2026-06-26T16:58:03Z

This also fixes RaspberryPiFoundation/blockly-samples#1752

maribethb

Sorry it's a lot of comments but overall the structure is great and I've mostly suggested some wording changes or minor reorganization!

maribethb · 2026-07-02T14:45:40Z

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC


Here and elsewhere, please update copyright to 2026 and Raspberry Pi Foundation

(old files stay as they are, but new files get new info)

I wasn't sure whether to keep the old license since I just copied the exact same code from the sample app. It's a new file wrt this codelab, but not a new file for Blockly. Happy to update but just want to double check that's what I should do (since the same will be the case for all the other codelabs)

maribethb · 2026-07-02T16:18:23Z

+For example: 
 - `scrollbars`: Whether to show scrollbars in the workspace.
 - `horizontalLayout`: Whether to display the toolbox horizontally or vertically in the workspace.
 - `toolboxPosition`: Whether to show the toolbox at the top or bottom of the workspace.


it's only top or bottom if we were using the horizontal layout. in this case, we're not, so this is kind of confusing. you also might want to explain the default values for these since it's not obvious horizontalLayout will be false, scrollbars will be true, etc.

Yes good point, I fixed this! Also, taking a closer look at this this made me realize that some of the default options are different between flyout & category toolboxes. With the goal being consistency across codelabs, I think that not clarifying this could cause some confusion when someone moves on to the real sample app after this codelab and sees a trash can and scrollbars when those things weren't in the workspace in this codelab. There's a few ways I could address this but I ended up just adding a couple lines at the end of the codelab about the difference, lmk if that looks good

maribethb · 2026-07-02T16:19:26Z

+- `maxBlocks`: The maximum number of blocks that may be created in the workspace. 

-The `options` struct gives you significant control over your Blockly instance. You can pass options to set Blockly's theme, modify scrolling behaviour, set the renderer, and more. For more information, head over to Blockly's developer site and check out the [configuration](/guides/configure/configuration_struct#the-options-dictionary) section.
+You can also pass options to set Blockly's theme, modify scrolling behaviour, set the renderer, and more. For more information, see the [configuration](/guides/configure/configuration_struct#the-options-dictionary) documentation.


For people new to blockly, the theme and renderer probably don't mean anything. I would either link to the documentation for those topics, or make this more general and say you can control the appearance of blockly.

maribethb · 2026-07-02T16:20:37Z

-/>
-
-Drag and drop the available loop block to the workspace to test it out.
+/>   


I would add some instructions to drag the blocks around so they can see it already works with basic interactions.

Done, I also realized it might be helpful to give a shout to keyboard nav here so I added that as well

maribethb · 2026-07-02T16:24:35Z

-  alt="image"
-  className="codelabImage"
-/>
+Now, you'll add a custom block to the workspace. 


I think I would add a sentence explaining why we're using custom blocks. Something like, Blockly ships with several basic blocks for writing numbers, strings, and loops. But the real power of a Blockly application comes from your custom blocks. You can define blocks that are related to your application, such as one that plays a song, makes a robot move on the screen, or reports the temperature from a connected sensor.

maribethb · 2026-07-02T16:47:50Z

+
+addText('Hello, World!');
 ```



Add a step here to register the block code generator with the javascript generator. be explicit that's what the object.assign is doing.

maribethb · 2026-07-02T16:49:04Z

 ```

-### The full code
+### Write the function


Set up code execution environment, or something more descriptive because it's not clear what "the function" is

maribethb · 2026-07-02T16:50:24Z


-The end result should look like this:
+The `runCode` function uses Blockly's javascriptGenerator to generate the code for the blocks on the workspace. 
+Then it displays the code in the codeDiv, resets the outputDiv, and evaluates the JavaScript code. 


Make it clear that executing the code is the responsibility of the application. Blockly just turns blocks into code. What you do with that code is up to you. For this sample app, we'll display the code in a div, and we'll use eval to run it.

maribethb · 2026-07-02T16:54:12Z

-
-Once the button behavior is defined by the user, it needs to be saved for later use. The saved code must be per button, since buttons can be programmed to play different sounds.
+You now have a Blockly workspace. However, if you reload the page, you'll find that any blocks you've dragged into the workspace will disappear.
+Your users likely won't want their blocks to vanish, but you can fix this by saving the state of the workspace in local browser storage. 


nit: saving to local storage is just one way to handle storage and probably not the one most real apps would use.

Your users likely won't want their blocks to vanish, but you can fix this by saving the state of the workspace and loading it back in next time they visit the site. For this codelab, we'll save that state to local browser storage.

maribethb · 2026-07-02T17:10:53Z

 *.komodoproject
 /nbproject/private/
 tsdoc-metadata.json
+.vscode


nit: add the trailing newline

zspriggs added 7 commits June 22, 2026 16:35

docs: remove old codelab and start new getting-started codelab

5e885bc

docs: refactor getting-started codelab

42b4332

docs: edit codelab

59c43c8

docs: continue editing new getting-started, add images

7f78d1b

docs: finish new getting-started, delete old, add sample app to docs

8fb3e10

docs: typo fixes and rm old images

6ace1ac

chore: rm .vscode and add to .gitignore

add0853

zspriggs requested a review from a team as a code owner June 26, 2026 16:48

zspriggs requested a review from mikeharv June 26, 2026 16:48

github-actions Bot assigned mikeharv Jun 26, 2026

github-actions Bot added the PR: docs label Jun 26, 2026

chore: formatting

581fbd5

zspriggs mentioned this pull request Jun 26, 2026

fix: wrap eval in try/catch RaspberryPiFoundation/blockly-samples#2733

Merged

1 task

mikeharv requested a review from maribethb June 29, 2026 16:22

github-actions Bot assigned maribethb Jun 29, 2026

mikeharv removed their request for review June 29, 2026 16:22

mikeharv removed their assignment Jun 29, 2026

zspriggs mentioned this pull request Jun 30, 2026

Add old getting-started code into examples RaspberryPiFoundation/blockly-samples#2734

Closed

maribethb reviewed Jul 2, 2026

View reviewed changes

zspriggs added 2 commits July 2, 2026 17:59

docs: add suggested changes

89d5b38

docs: finish changes

33b2979

Uh oh!

Conversation

zspriggs commented Jun 26, 2026

The basics

The details

Proposed Changes

Uh oh!

gonfunko commented Jun 26, 2026

Uh oh!

maribethb left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants