Blockly Samples

The blockly-samples repository is organized into two primary sections for developers looking to extend or implement Blockly:

• Plugins: Self-contained code modules designed to add specific new functionality to the core Blockly library.
• Examples: Complete, self-contained sample projects that demonstrate various techniques for including, configuring, and extending Blockly in an application.

For interactive, live demonstrations of most available plugins, visit the Blockly Samples GitHub Pages site.

The sample app uses a standard modern web development stack to manage the Blockly lifecycle:

Using with other plugins

This plugin includes its own MetricsManager. If you are using multiple plugins that provide their own MetricsManager, you must create a custom implementation that combines their features. Your implementation must satisfy the isCacheable type guard in ScrollMetricsManager.ts to ensure content metrics are available during a drag.

Using with custom draggables

Custom objects implementing Blockly.IDraggable are compatible with the plugin but do not support autoscrolling by default. To enable autoscrolling for your custom objects, implement the AutoScrollable interface on them.

To allow custom draggable objects to be added to the backpack, implement the Backpackable interface. This interface requires a method that converts the object into a FlyoutItemInfo object.

Note: As of Blockly core v11, flyouts only support displaying blocks, buttons, and labels.

The @blockly/shadow-block-converter plugin automatically converts shadow blocks into regular blocks when a user edits them.

Key Behaviors:

• Persistence: Shadow blocks behave like a persistent default value. If a user moves or deletes the newly created regular block, the original shadow block will automatically reappear.
• Independence: The converted regular block is a new instance with a unique ID, though it maintains the same properties and shape as the original shadow block.
• Ancestor Handling: If the shadow block was attached to ancestor blocks that were also shadows, those ancestors will also be recreated as regular blocks.
• Descendant Handling: If the shadow block had descendant blocks, they will be recreated with new IDs but will remain shadow blocks.

The minimap inherits RTL and theme properties from the provided workspace.

To customize the appearance, use the following CSS classes:

• .blockly-minimap: Controls the minimap container (e.g., box-shadow).
• .blockly-focus-region: Controls the highlight region that shows the current viewport (e.g., fill color).

To configure keyboard panning distance, use setKeyboardPanStep(stepPixels). The default is 40 workspace pixels per keypress.

// Set pan distance to 80px per arrow press
minimap.setKeyboardPanStep(80);

The minimap is a single tab stop. When focused, the arrow keys pan the main workspace. Modifier keys (Ctrl, Alt, Shift, Meta) are passed through without triggering a pan.

| Key          | Action                  |
| ------------ | ----------------------- |
| `ArrowUp`    | Pan the workspace up    |
| `ArrowDown`  | Pan the workspace down    |
| `ArrowLeft`  | Pan the workspace left    |
| `ArrowRight` | Pan the workspace right |

The user experience is designed to minimize distraction during collaborative sessions.

Visual Feedback

• No Real-time Movement: Users do not see blocks physically moving across the screen in real-time. Instead, they see blocks update their locations/states once the synchronization is complete.
• Presence Markers: To show where other users are active, the system uses color-coded markers.
• Marker Behavior: Markers indicate when a remote user has:
  • Selected a specific block.
  • Is currently editing a field.

Each user is assigned a unique color (e.g., yellow, blue, or green) to distinguish their presence on the workspace.