# Technical Documentation: RaspberryPiFoundation/blockly
> ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/RaspberryPiFoundation/blockly)
### Overview (README.md)
# Blockly
Blockly is a library that adds a visual code editor to web apps. The Blockly editor uses interlocking, graphical blocks to represent code concepts like variables, logical expressions, loops, and more. It allows users to apply programming principles without having to worry about syntax or the intimidation of a blinking cursor on the command line. All code is [free and open source](https://github.com/raspberrypifoundation/blockly/blob/develop/LICENSE).
## Getting Started with Blockly
Blockly has many resources for learning how to use the library. You can [try a live demo](https://raspberrypifoundation.github.io/blockly/packages/blockly/demos/code/index.html) or [visit our developer site](https://docs.blockly.com) to read the documentation on how to get started, configure Blockly, and integrate it into your application. The developer site also contains links to:
- [Getting Started article](https://docs.blockly.com/guides/get-started/what-is-blockly/)
- [Getting Started codelab](https://docs.blockly.com/codelabs/getting-started/codelab-overview/)
- [More codelabs](https://docs.blockly.com/codelabs/)
- [Demos and plugins](https://raspberrypifoundation.github.io/blockly-samples/)
### Installing Blockly
If you're starting a new project using Blockly, you can bootstrap it
using our [`create-package` tool](https://www.npmjs.com/package/@blockly/create-package):
```bash
npx @blockly/create-package app my-cool-blockly-app --typescript
```
Or, if you're adding Blockly to an existing project, just [install it with npm](https://www.npmjs.com/package/blockly):
```bash
npm install blockly
```
### Getting Help
- [Report a bug](https://docs.blockly.com/guides/contribute/get-started/write_a_good_issue/) or file a feature request on GitHub
- Ask a question, or search others' questions, on our [developer forum](https://groups.google.com/forum/#!forum/blockly). You can also drop by to say hello and show us your prototypes; collectively we have a lot of experience and can offer hints which will save you time. We actively monitor the forums and typically respond to questions within 2 working days.
### blockly-samples
We have a number of [examples](https://github.com/raspberrypifoundation/blockly-samples/tree/main/examples) which demonstrate various techniques to include and extend the Blockly library. These examples can be found in another repository called [blockly-samples](https://github.com/raspberrypifoundation/blockly-samples).
### Plugins
A plugin is a self-contained piece of code that adds functionality to Blockly. Plugins can add fields, define themes, create renderers, and much more. For more information, see the [Plugins documentation](https://docs.blockly.com/guides/programming/plugin_overview/).
## Contributing to Blockly
Want to make Blockly better? We welcome contributions to Blockly in the form of pull requests, bug reports, documentation, answers on the forum, and more! Check out our [Contributing Guidelines](https://docs.blockly.com/guides/contribute/) for more information. You might also want to look for issues tagged "[Help Wanted](https://github.com/raspberrypifoundation/blockly/labels/help%20wanted)" which are issues we think would be great for external contributors to help with.
## Releases
We release new versions on npm and GitHub releases, and then update our [docs](https://docs.blockly.com) and [demo pages](https://raspberrypifoundation.github.io/blockly-samples/). If there are breaking regressions, such as a crash when performing a standard action or a rendering issue that makes Blockly unusable, we will cherry-pick fixes into patch releases. The [releases page](https://github.com/raspberrypifoundation/blockly/releases) has a list of all releases.
We use [semantic versioning](https://semver.org/). Releases that have breaking changes or are otherwise not backwards compatible will have a new major version. Patch versions are reserved for bug-fix patches between scheduled releases.
We now have a [beta release on npm](https://www.npmjs.com/package/blockly?activeTab=versions). If you'd like to test the upcoming release, or try out a not-yet-released new API, you can use the beta channel with:
```bash
npm install blockly@beta
```
As it is a beta channel, it may be less stable, and the APIs there are subject to change.
### Branches
Most development happens in the **[main](https://github.com/raspberrypifoundation/blockly/tree/main)** branch. Pull requests should typically be made against main. This branch should be stable; features that aren't ready yet should be merged to a feature branch instead. Once something is in main we expect it to be part of the next release. However, features and APIs here are subject to change until they are released. If you're working on a production application using Blockly, you should use the release from npm or the GitHub release page, not the `main` branch.
Larger changes may have their own branches until they are good enough for people to try out. These will be developed separately until we think they are almost ready for release. They will be merged into main when ready.
### New APIs
Once a new API is released, it is considered beta until the following release. We generally try to avoid changing an API after it has been released, but sometimes we need to make changes after seeing how an API is used. If an API has been around for at least two releases we'll do our best to avoid breaking it.
Unreleased APIs may change radically. Anything that is in `main` but not released is subject to change without warning.
## Issues and Milestones
We typically triage all bugs within 1 week, which includes adding any appropriate labels and assigning it to a milestone. Please keep in mind, we are a small team so even feature requests that everyone agrees on may not be prioritized.
## Accessibility
Although Blockly is built around drag-and-drop, it is fully usable with the
keyboard alone. Blockly is also accessible to screenreader users by default. We
provide [Accessibility Conformance Reports](https://docs.blockly.com/guides/app-integration/accessibility/compliance/)
in the VPAT format that outline Blockly's conformance to WCAG 2.2 Level AA.
---
### Packages Docs README (`packages/docs/README.md`)
# Blockly Documentation Website
This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
## Installation
Run `npm install` at the root of the blockly repo, then all other commands from the `packages/docs` directory.
```bash
npm install
cd packages/docs
```
## Local development
```bash
npm start
```
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
## Build
```bash
npm run build
```
This command generates static content into the `build` directory and can be served using any static contents hosting service.
## Test your build locally
```bash
npm run serve
```
The build folder is now served at http://localhost:3000/
## Formatting and linting
```bash
# check formatting:
npm run format-check
# fix formatting:
npm run format
# check linting:
npm run lint
# fix linting:
npm run lint-fix
```
Prettier is used for formatting JavaScript files (the `format` script).
ESlint is used for linting `.md` and `.mdx` files due to poor support for these in Prettier (the `lint` script).
## Generating reference docs
The API reference pages are auto-generated from the Blockly TypeScript source
using [TypeDoc](https://www.npmjs.com/package/typedoc). Typedoc automatically
generates MDX files into `/docs/reference/` when Docusaurus starts.
TypeDoc generates the API docs based on the latest Blockly release, not the
current code. If you would like to see unreleased or beta changes reflected
in your local docs site, run `npm run reference:refresh`. This will overwrite a
file called `blockly_api.json` which TypeDoc uses to generate the docs. Then,
you can run docs again to see updates to the API docs.
If you regenerate `blockly_api.json`, please do not commit it in a PR. This
file is committed automatically as part of our release process.
---
### Packages Docs Docs Codelabs Index (`packages/docs/docs/codelabs/index.mdx`)
---
title: Welcome to the Blockly Codelabs
pagination_next: null
pagination_prev: null
---
import { CodelabGrid, CodelabCard } from '@site/src/components/CodelabCards';
import Image from '@site/src/components/Image';
Blockly Codelabs provide a guided, tutorial, hands-on coding experience of Blockly.
---
### Packages Docs Docs Codelabs Context Menu Option Codelab Overview (`packages/docs/docs/codelabs/context-menu-option/codelab-overview.mdx`)
---
pagination_prev: null
description: Overview of the "Customizing context menus" codelab.
---
# Customizing context menus
## 1. Codelab overview
### What you'll learn
In this codelab you will learn how to:
- Add a context menu option to the workspace.
- Add a context menu option to all blocks.
- Use precondition functions to hide or disable context menu options.
- Take an action when a menu option is selected.
- Customize ordering and display text for context menu options.
### What you'll build
A very simple Blockly workspace with a few new context menu options.
### What you'll need
- A browser.
- A text editor.
- Basic knowledge of HTML, CSS, and JavaScript.
- node.js and npm installed ([instructions](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)).
- Comfort using the command line/terminal.
You can find the code for the [completed context menu codelab](https://github.com/RaspberryPiFoundation/blockly/tree/main/packages/docs/docs/codelabs/context-menu-option/complete-code) on GitHub.
This codelab is focused on Blockly's context menus. Non-relevant concepts and code are glossed over and are provided for you to simply copy and paste.
---
### Packages Docs Docs Codelabs Css Codelab Overview (`packages/docs/docs/codelabs/css/codelab-overview.mdx`)
---
pagination_prev: null
description: Overview of the "Use CSS in Blockly" codelab.
---
import Image from '@site/src/components/Image';
# Use CSS in Blockly
## 1. Codelab overview
### What you'll learn
In this codelab you will learn how to use CSS to customize the colours of:
- Components
- Categories
- Blocks
If you don't need the fine-grained control provided by CSS, consider using
themes instead. For more information, see the
[Customizing your themes](/codelabs/theme-extension-identifier/codelab-overview)
codelab.
### What you'll build
A simple Blockly workspace that uses the same Halloween colours as the [Customizing your themes](/codelabs/theme-extension-identifier/codelab-overview) codelab.
You can find the code for the [completed CSS codelab](https://github.com/RaspberryPiFoundation/blockly/tree/main/packages/docs/docs/codelabs/css/complete-code) on GitHub.
### What you'll need
- A browser.
- A text editor.
- Basic knowledge of HTML, CSS, SVG, and JavaScript.
- Basic knowledge of your browser's developer tools.
- node.js and npm installed ([instructions](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)).
- Comfort using the command line/terminal.
- Basic understanding of Blockly, including workspace components, category toolboxes, block definitions, and themes.
This codelab is focused on using CSS with Blockly. Non-relevant concepts are glossed over and provided for you to simply copy and paste.
---
### Packages Docs Docs Codelabs Custom Generator Block Generator Overview (`packages/docs/docs/codelabs/custom-generator/block-generator-overview.mdx`)
---
description: Introduction to block generators.
---
# Build a custom generator
## 4. Block generator overview
At its core, a block generator is a function that takes in a block (and optionally the language generator instance), translates the block into code, and returns that code as a string.
Each language generator has a property called `forBlock`, which is a dictionary object where all block generator functions must be placed. For instance, here is the code to add a block generator for blocks of type `sample_block` on a language generator object (`sampleGenerator`).
```js
sampleGenerator.forBlock['sample_block'] = function (block, generator) {
return 'my code string';
};
```
### Statement blocks
Statement blocks represent code that does not return a value.
A statement block's generator simply returns a string.
For example, this code defines a block generator that always returns the same function call.
```js
sampleGenerator.forBlock['left_turn_block'] = function (block, generator) {
return 'turnLeft()';
};
```
### Value blocks
Value blocks represent code that returns a value.
A value block's generator returns an array containing a string and a [precedence value](/guides/create-custom-blocks/code-generation/operator-precedence). The built-in generators have predefined operator precedence values exported as an `Order` enum.
This code defines a block generator that always returns `1 + 1`:
```js
sampleGenerator.forBlock['two_block'] = function (block, generator) {
return ['1 + 1', Order.ADDITION];
};
```
### Operator precedence
Operator precedence rules determine how the correct order of operations is maintained during parsing. In Blockly's generators, operator precedence determines when to add parentheses.
--> Read more about [operator precedence in JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Operator_Precedence).
--> Read more about [operator precedence in Blockly](/guides/create-custom-blocks/code-generation/operator-precedence).
Since JSON does not allow values that are expressions, the code does not need to consider operator precedence for the generator being built in this codelab. The same value can be used everywhere a precedence value is required. Since parentheses never need to be added to the JSON, call this value `ATOMIC`.
In `src/generators/json.js`, declare a new enum called `Order` and add the `ATOMIC` value:
```js
const Order = {
ATOMIC: 0,
};
```
---
### Packages Docs Docs Codelabs Custom Generator Codelab Overview (`packages/docs/docs/codelabs/custom-generator/codelab-overview.mdx`)
---
pagination_prev: null
description: Overview of the "Build a custom generator" codelab.
---
import Image from '@site/src/components/Image';
# Build a custom generator
## 1. Codelab overview
### What you'll learn
- How to create a custom language generator.
- How to create block generator definitions for existing blocks.
- How to create block generator definitions for new blocks.
- How to use a custom generator in an application.
### What you'll build
You will build a JSON generator that implements the [JSON language spec](https://www.json.org/json-en.html).
The complete code used in this codelab can be viewed in the `blockly` repository under [packages/docs/docs/codelabs/custom-generator](https://github.com/RaspberryPiFoundation/blockly/tree/main/packages/docs/docs/codelabs/custom-generator/complete-code).
### What you'll need
- Familiarity with JSON and the JSON specification.
- Basic understanding of blocks and toolboxes in Blockly.
- NPM installed ([instructions](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)).
- Comfort using the command line/terminal.
---
### Packages Docs Docs Codelabs Custom Mutator Codelab Overview (`packages/docs/docs/codelabs/custom-mutator/codelab-overview.mdx`)
---
pagination_prev: null
description: Overview of the "Build a custom mutator" codelab.
---
import Image from '@site/src/components/Image';
# Build a custom mutator
## 1. Codelab overview
### What you'll learn
- What mutators are and when to use them
- How to create a custom mutator
- How to use context menus to create a custom mutator UI
- When and how to fire events during a mutation
### What you'll build
A custom list mutator that uses the context menu to add and remove items.
### What you'll need
- Basic understanding of Blockly blocks, toolboxes, and workspaces.
- Understanding of context menus in Blockly.
- NPM installed ([instructions](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)).
- Comfort using the command line/terminal.
---
### Packages Docs Docs Codelabs Custom Renderer Codelab Overview (`packages/docs/docs/codelabs/custom-renderer/codelab-overview.mdx`)
---
pagination_prev: null
description: Overview of the "Build custom renderers" codelab.
---
# Build custom renderers
## 1. Codelab overview
### What you'll learn
- How to define and register a custom renderer.
- How to override renderer constants.
- How to change the shape of connection notches.
- How to set a connection's shape based on its type checks.
### What you'll build
This codelab builds a custom renderer which adjusts renderer constants and uses different connection shapes depending on the input types.
The complete code used in this codelab can be viewed in the `blockly` repository under [packages/docs/docs/codelabs/custom-renderer](https://github.com/RaspberryPiFoundation/blockly/tree/main/packages/docs/docs/codelabs/custom-renderer/complete-code).
### What you'll need
- Basic understanding of renderers and toolboxes in Blockly.
- NPM installed ([instructions](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)).
- Comfort using the command line/terminal.
---
### Packages Docs Docs Codelabs Custom Toolbox Codelab Overview (`packages/docs/docs/codelabs/custom-toolbox/codelab-overview.mdx`)
---
pagination_prev: null
description: Overview of the "Customizing a Blockly toolbox" codelab.
---
import Image from '@site/src/components/Image';
# Customizing a Blockly toolbox
## 1. Codelab overview
### What you'll learn
This codelab will focus on customizing the Blockly toolbox.
In this codelab you will learn:
1. How to add a background color to a toolbox category.
1. How to change the look of a selected category.
1. How to add a custom CSS classes to a toolbox category.
1. How to change the structure of your category HTML.
1. How to add a custom toolbox item.
### What you'll build
Over the course of this codelab you will customize your toolbox categories as well
as create a custom toolbox item.
The resulting toolbox is shown below.
The code samples are written in ES6 syntax. You can find the code for the [completed custom toolbox](https://github.com/RaspberryPiFoundation/blockly/tree/main/packages/docs/docs/codelabs/custom-toolbox/complete-code) on GitHub.
### What you'll need
- A browser.
- A text editor.
- Basic knowledge of HTML, CSS, and JavaScript.
- node.js and npm installed ([instructions](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)).
- Comfort using the command line/terminal.
- Basic understanding of the [Blockly toolbox](/guides/configure/toolboxes/toolbox).
Throughout this codelab we will be talking about toolbox definitions.
It may help to review the related [toolbox definition documentation] before starting this codelab.
---
### Packages Docs Docs Codelabs Getting Started Codelab Overview (`packages/docs/docs/codelabs/getting-started/codelab-overview.mdx`)
---
pagination_prev: null
description: Overview of the "Getting started with Blockly" codelab.
---
import Image from '@site/src/components/Image';
# Getting started with Blockly
## 1. Codelab overview
### What you'll learn
This codelab will teach you how to modify a simple web app to include the [Blockly](/guides/get-started/what-is-blockly) visual programming library.
### What is Blockly?
Blockly is a library for building block programming apps.
Block programming allows users to create scripts and programs by using visual blocks, even if they do not know any programming language.
Blockly includes everything you need for defining and rendering blocks in a drag-n-drop editor. Each block represents a chunk of code that can be easily stacked and translated into code.
### What you'll build
A version of Blockly's sample app, built from scratch.
### What you'll need
- A browser
- A text editor
- npm installed ([instructions](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)).
- Basic knowledge of HTML, CSS and JavaScript
This codelab is focused on Blockly. The app structure, non-relevant concepts and code are glossed over and are provided for you to simply copy and paste.
---
### Packages Docs Docs Codelabs Theme Extension Identifier Codelab Overview (`packages/docs/docs/codelabs/theme-extension-identifier/codelab-overview.mdx`)
---
pagination_prev: null
description: Overview of the "Customizing your themes" codelab.
---
import Image from '@site/src/components/Image';
# Customizing your themes
## 1. Codelab overview
### What you'll learn
In this codelab you will learn how to:
- Add component styles.
- Add a category style.
- Add a block style.
### What you'll build
You'll start from the Blockly sample app and give it a custom "Halloween" theme,
customizing the colours of the workspace components, the toolbox categories, and
the blocks themselves.
The code samples are written in ES6 syntax. You can find the code for the
[completed theme codelab](https://github.com/RaspberryPiFoundation/blockly/tree/main/packages/docs/docs/codelabs/theme-extension-identifier/complete-code)
on GitHub.
### What you'll need
- A browser.
- A text editor.
- Basic knowledge of HTML, CSS, and JavaScript.
- node.js and npm installed ([instructions](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)).
- Comfort using the command line/terminal.
This codelab is focused on Blockly's theme extension. Non-relevant concepts
are glossed over and provided for you to simply copy and paste.
---
### Packages Docs Docs Codelabs Validation And Warnings Codelab Overview (`packages/docs/docs/codelabs/validation-and-warnings/codelab-overview.mdx`)
---
pagination_prev: null
description: Overview of the "Block validation and warnings" codelab.
---
import Image from '@site/src/components/Image';
# Block validation and warnings
## 1. Codelab overview
### What you'll learn
This codelab will show you how to ensure that custom blocks either:
1. have everything they need to be able to generate valid code, or
1. display a visual warning to the user that the block is currently invalid.
### What you'll build
In this codelab, you'll create a new custom block type that generates a list of numbers counting up within a given range. The block will validate itself and display a warning if the first number in the range is greater than the last number:
You can find the code for the [completed custom block](https://github.com/RaspberryPiFoundation/blockly/tree/main/packages/docs/docs/codelabs/validation-and-warnings/complete-code) on GitHub.
### What you'll need
- A browser.
- A text editor.
- Basic knowledge of HTML, CSS, and JavaScript.
- node.js and npm installed ([instructions](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)).
- Comfort using the command line/terminal.
- Basic understanding of the [Blockly toolbox](/guides/configure/toolboxes/toolbox).
- Basic understanding of [using JSON to define custom blocks](/guides/create-custom-blocks/define/structure-json).
---
### Packages Docs Docs Guides Contribute Index (`packages/docs/docs/guides/contribute/index.mdx`)
---
description: How to contribute (not just code!) to Blockly.
title: Contribute to Blockly
image: images/blockly_banner.png
---
# Contribute to Blockly
Blockly is an open-source project with a strong community, and we welcome your
contributions.
## How you can help
- [File bugs or feature requests](/guides/contribute/get-started/write_a_good_issue)
- [Fix issues](/guides/contribute/get-started/write_a_good_pr)
- [Add tests](/guides/contribute/core/unit_testing)
- [Write codelabs](/guides/contribute/core/write_a_codelab)
- [Write plugins](/guides/contribute/core/plugins/add_a_plugin)
- [Answer questions](https://groups.google.com/g/blockly)
## Where to start
- If you're new to open source development, or you want to get more background
knowledge, head over to the
[Getting Started contributing](/guides/contribute/get-started)
guides.
- If you are ready to jump in, check out the
[Contributing to Core](/guides/contribute/core) or
[Contributing to Samples](/guides/contribute/samples) guides.
### Talk to us!
Join our
[forum for developers](https://groups.google.com/g/blockly) and
say hello. Show us your prototypes early; collectively we have a lot of
experience and can offer hints which will save you time. Plus, we always love to
hear about new projects and use cases for Blockly!
---
### Packages Docs Docs Guides Create Custom Blocks Overview (`packages/docs/docs/guides/create-custom-blocks/overview.mdx`)
---
description: Introduction to creating custom blocks.
title: Custom blocks overview
image: images/blockly_banner.png
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
# Custom blocks overview
Blockly comes with a large number of predefined blocks, from mathematical
functions to looping structures. However, most applications need to define and
implement custom blocks for their domain. For example, a drawing application
might need blocks to draw lines and circles and a robotics application might
need blocks to move an arm and manipulate a claw.
To define and use a new type of block, you need three things:
- **Block definition**: Defines the look and feel of a block type as well as
certain behaviors.
- **Block-code generator**: Generates the code string for blocks of this type.
It is always written in JavaScript, even if the target language is not
JavaScript.
- **Toolbox reference**: A reference to the block type in the toolbox, so
users can add it to the workspace.
## Block definition
A **block definition** defines the look and feel of a block, such as its text,
fields, connections, and colour. It can also define block-specific behavior,
such as a block-specific event handler. For example, this block:
can be defined in JSON or JavaScript as follows:
```js
Blockly.common.defineBlocksWithJsonArray([{
"type": "string_length",
"message0": 'length of %1',
"args0": [
{
"type": "input_value",
"name": "VALUE",
"check": "String"
}
],
"output": "Number",
"colour": 160,
"tooltip": "Returns number of letters in the provided text.",
"helpUrl": "http://www.w3schools.com/jsref/jsref_length_string.asp"
}]);
```
```js
Blockly.Blocks['string_length'] = {
init: function() {
this.appendValueInput('VALUE')
.setCheck('String')
.appendField('length of');
this.setOutput(true, 'Number');
this.setColour(160);
this.setTooltip('Returns number of letters in the provided text.');
this.setHelpUrl('http://www.w3schools.com/jsref/jsref_length_string.asp');
}
};
```
For more information about block definitions and how they work, see [What's a
block
definition?](/guides/create-custom-blocks/define/block-definitions).
## Block-code generators
To transform a block into code, you need separate generator functions for each
language you want to generate. For example, here is a generator that generates
JavaScript:
```js
javascriptGenerator.forBlock['string_length'] = function (block, generator) {
// String or array length.
var argument0 =
generator.valueToCode(block, 'VALUE', Order.FUNCTION_CALL) || "''";
return [argument0 + '.length', Order.MEMBER];
};
```
The generator function accepts the block being processed and a language
generator. It generates code for any blocks attached to inputs (such as the
`VALUE` input in the example) and any fields, and then concatenates the
resulting strings into a larger expression.
For more information, see [Block-code
generators](/guides/create-custom-blocks/code-generation/block-code).
## Toolbox reference
After you have defined your block type, use the type name to reference it in a
toolbox:
```js
var toolbox = {
"kind": "categoryToolbox",
"name": "Text"
"contents": [
{
"kind": "block",
"type": "string_length"
},
]
};
```
```html
WHY IS THERE DISPLAY: NONE HERE?
...
```
For more information, see [Define a flyout
toolbox](/guides/configure/toolboxes/flyout) or [Define a category
toolbox](/guides/configure/toolboxes/category).
---
### Packages Docs Docs Guides Design App Overview (`packages/docs/docs/guides/design/app-overview.mdx`)
---
description: Discusses how Blockly is used in applications.
title: Introduction to Blockly applications
image: images/blockly_banner.png
---
import Image from '@site/src/components/Image';
# Introduction to Blockly applications
A Blockly application is a web application that contains a Blockly editor
(workspace). This document gives examples of what Blockly applications are used
for and looks at typical UI features.
If you haven't already done so, be sure to read the [visual
glossary](/guides/get-started/workspace-anatomy) and [basic application
steps](/guides/get-started/workspace-creation) before continuing with
this document.
## What do Blockly applications do?
Blockly applications help users write programs in a variety of fields, from
video games to robotics to data analysis. Users **write their programs using
blocks**, which the application uses to **generate text-based code**, such as
JavaScript or Python. The application then **runs the generated code directly**
or the user **downloads and runs it on another platform**, such as a robot or
hand-held video game controller.
Here are some examples of the kinds of programs users write with Blockly
applications:
- **Puzzle solutions, animation, or music:** The generated code solves a
puzzle (like a maze), displays an animation, or plays music. For an example,
see [Code.org's Music Lab](https://studio.code.org/projects/music/new).
- **Video games:** The generated code runs a video game. For example, create
the first two levels of "Whack the Mole" in [MakeCode
Arcade](https://arcade.makecode.com/) and download the game to a controller
or play it in the simulator.
- **Robotics:** The generated code directs a robot. For example, program a
robot with [Ozoblockly](https://games.ozoblockly.com/shapetracer-freeform)
and download it to a real robot or run it in the simulator.
- **Drawing:** The generated code draws a 2D or 3D drawing. For an example,
see [BlocksCAD](https://www.blockscad3d.com/editor/).
- **Data analysis:** The generated code analyzes data and creates a graph. For
an example, see [this demonstration of the Dialogic
Platform](https://dialogiconderzoek.nl/diadashboard/platform/demo1.gif).
- **Application-specific code:** The generated code performs a task specific
to a particular application. For example, [Blockly Developer Tools](https://raspberrypifoundation.github.io/blockly-samples/examples/developer-tools/index.html)
is a tool for designing new Blockly blocks. It generates block definition
code, which users copy and paste into their own Blockly application.
## User interfaces
A good way to understand the typical components of Blockly applications is to
look at their user interfaces.
### Basic UI components
Almost all Blockly applications share a few basic components: a Blockly editor
(workspace), an output panel, and a "Run" button. For example, here is the UI of
the [Maze](https://blockly.games/maze?level=4) in Blockly Games.
A few Blockly applications omit the "Run" button and instead update the output
panel every time the user makes a change. For example, the
[Graph](https://raspberrypifoundation.github.io/blockly-samples/examples/graph-demo/index.html)
application in Blockly's samples has two output panels (one for the graph and
one for the equation) that it updates on every change.
Some applications don't have an output panel. This is most common in hardware
applications, such as those for programming robots. While some of these
applications include a hardware simulator, many of them just let users download
and run the generated code directly on the target device.
### Additional UI components
Most applications have additional UI components. Some of these meet general
needs, such as saving the user's work, while others fulfill application-specific
needs, such as designing a GUI. Here are some examples:
- [Scratch](https://scratch.mit.edu/), an application for creating animations
and video games, has graphics and sound editors; panels to create new
sprites and backdrops; and file, edit, and settings menus:
- [MakeCode Arcade](https://www.microsoft.com/en-us/makecode), an application
for creating video games, has output controls, code and graphics editors, a
settings menu, and download and save buttons. Its output panel simulates a
handheld game controller.
- [MIT App Inventor](https://appinventor.mit.edu/), an application for
creating phone apps, has separate screens for its GUI designer and Blockly
editor, as well as file, connection, build, and settings menus. Instead of
an output panel, users test generated code on their phone.
Which additional components you should include depends on your application's
goals and the abilities of your users. Some common components are:
- Administration:
- File management (new, open, save, save as, delete)
- Account management (create, login, logout)
- Settings (language, UI configuration)
- Programming:
- Edit commands (undo, redo, copy, cut, paste, duplicate)
- GUI designer
- Graphics and sound editors
- Code editor or read-only code display
- Testing
- Output configuration (start/stop, playback speed, volume, screenshot,
etc.)
- Debugger (breakpoints, run, step, block highlighting)
- Set test parameters
- Hardware
- Connection (USB, Bluetooth, QR code)
- Configuration (choose model, choose accessories, assign component names)
- Control (manually control robot, record robot position)
- Download code
- Help
- Documentation
- Interactive tutorials
- Context-sensitive help
## Where do I go from here?
If you're still thinking about your application, continue reading about [design
considerations](/guides/design/applications).
If you want to see what it's like to build a simple application, try the
[Getting started with Blockly
codelab](/codelabs/getting-started/codelab-overview).
And if you're ready to write your application:
- [Build your editor](/guides/configure/configuration_struct)
- [Build your blocks](/guides/create-custom-blocks/overview)
- [Build your application](/guides/app-integration/run-code)
---
### Packages Docs Docs Guides Get Started Sample App Overview (`packages/docs/docs/guides/get-started/sample-app-overview.mdx`)
# Blockly Sample App
## Purpose
The Blockly sample app illustrates how to use Blockly together with common programming tools like node/npm, webpack, typescript, eslint, and others. You can use it as the starting point for your own application and modify it as much as you'd like. It contains basic infrastructure for running, building, testing, etc. that you can use even if you don't understand how to configure the related tool yet. When your needs outgrow the functionality provided here, you can replace the provided configuration or tool with your own.
## Quick Start
1. [Install](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) npm if you haven't before.
2. Run [`npx @blockly/create-package app `](https://www.npmjs.com/package/@blockly/create-package) to clone this application to your own machine.
3. Run `npm install` to install the required dependencies.
4. Run `npm run start` to run the development server and see the app in action.
5. If you make any changes to the source code, just save your changes and refresh the browser while the server is running to see them.
## Tooling
The application uses many of the same tools that the Blockly team uses to develop Blockly itself. Following is a brief overview, and you can read more about them on our [developer site](/guides/contribute/core/development_tools).
- Structure: The application is built as an npm package. You can use npm to manage the dependencies of the application.
- Modules: ES6 modules to handle imports to/exports from other files.
- Building/bundling: Webpack to build the source code and bundle it into one file for serving.
- Development server: webpack-dev-server to run locally while in development.
- Testing: Mocha to run unit tests.
- Linting: Eslint to lint the code and ensure it conforms with a standard style.
- UI Framework: Does not use a framework. For more complex applications, you may wish to integrate a UI framework like React or Angular.
You can disable, reconfigure, or replace any of these tools at any time, but they are preconfigured to get you started developing your Blockly application quickly.
## Structure
- `package.json` contains basic information about the app. This is where the scripts to run, build, etc. are listed.
- `package-lock.json` is used by npm to manage dependencies
- `webpack.config.js` is the configuration for webpack. This handles bundling the application and running our development server.
- `src/` contains the rest of the source code.
- `dist/` contains the packaged output (that you could host on a server, for example). This is ignored by git and will only appear after you run `npm run build` or `npm run start`.
### Source Code
To get an in-depth overview of the sample app's source code, see the [getting started codelab](/codelabs/getting-started/codelab-overview/) which goes through the process of creating this app.
Here is a briefer overview of the files in the source code:
- `index.html` contains the skeleton HTML for the page. This file is modified during the build to import the bundled source code output by webpack.
- `index.js` is the entry point of the app. It configures Blockly and sets up the page to show the blocks, the generated code, and the output of running the code in JavaScript.
- `serialization.js` has code to save and load the workspace using the browser's local storage. This is how your workspace is saved even after refreshing or leaving the page. You could replace this with code that saves the user's data to a cloud database instead.
- `toolbox.js` contains the toolbox definition for the app. The current toolbox contains nearly every block that Blockly provides out of the box. You probably want to replace this definition with your own toolbox that uses your custom blocks and only includes the default blocks that are relevant to your application.
- `blocks/text.js` has code for a custom text block, just as an example of creating your own blocks. You probably want to delete this block, and add your own blocks in this directory.
- `generators/javascript.js` contains the JavaScript generator for the custom text block. You'll need to include block generators for any custom blocks you create, in whatever programming language(s) your application will use.
## Serving
To run your app locally, run `npm run start` to run the development server. This mode generates source maps and ingests the source maps created by Blockly, so that you can debug using unminified code.
To deploy your app so that others can use it, run `npm run build` to run a production build. This will bundle your code and minify it to reduce its size. You can then host the contents of the `dist` directory on a web server of your choosing. If you're just getting started, try using [GitHub Pages](https://pages.github.com/).
---
### Packages Docs Docs Guides Programming Plugin Overview (`packages/docs/docs/guides/programming/plugin_overview.mdx`)
---
description: Plugins, their types, and how to use them.
title: Plugins
image: images/blockly_banner.png
---
import Image from '@site/src/components/Image';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
# Plugins
A plugin is a self-contained piece of code that adds functionality to Blockly.
For example, it might add a custom field, define a new theme, or provide a
custom renderer. Plugins are generally packaged and distributed through npm.
:::note
The [`BlocklyOptions`
object](/guides/configure/configuration_struct#the-options-dictionary)
has a `plugins` property for injecting classes that [customize Blockly
behavior](/guides/configure/customization). While these classes may
be implemented as plugins, this is not required and they are otherwise
unrelated.
:::
For a quick introduction to plugins, see our [Plugins Overview talk
(2021)](https://www.youtube.com/watch?v=rg-V0w7UZFc&list=PLSIUOFhnxEiCjoIwJ0jAdwpTZET73CK7d&index=3).
If you want to create your own plugin, see [Add a
plugin](/guides/contribute/core/plugins/add_a_plugin).
## First- and third-party plugins
_First-party plugins_ are supported by the Blockly team and published under the
`@blockly` scope on npm. They are designed to be usable in a wide range of
Blockly applications.
_Third-party plugins_ are maintained and published independently. They may be
more complex, more experimental, or targeted to a narrower range of Blockly
applications.
## Find a plugin
* Visit [Blockly Plugins &
Demos](https://raspberrypifoundation.github.io/blockly-samples/#plugins), which has live
demos of first-party plugins.
* Search npm for
[`keyword:blockly-plugin`](https://www.npmjs.com/search?q=keyword%3Ablockly-plugin).
Plugins with the scope `@blockly` are published by the Blockly team. For
broader results, search for
[`keyword:blockly`](https://www.npmjs.com/search?q=keyword%3Ablockly) or
[`blockly`](https://www.npmjs.com/search?q=blockly).
* See the [`packages/plugins/`](https://github.com/RaspberryPiFoundation/blockly/tree/main/packages/plugins)
directory on GitHub, which is the location of first-party plugins.
Each plugin has a README that describes its behaviour and intended use.
## Install a plugin
We recommend installing plugins with a package manager like npm or yarn. This
makes it easy to receive updates.
* **Install a plugin with a package manager**
```shell
npm install @blockly/field-angle
```
```shell
yarn add @blockly/field-angle
```
* **Install a plugin without a package manager**
```html
```
You can also clone the GitHub repository that contains the plugin. For
first-party plugins, this is
[`blockly`](https://github.com/RaspberryPiFoundation/blockly/tree/main).
Check the plugin's README to see if there are any additional installation
instructions.
## Use a plugin
Each plugin is different, so see the plugin's README for information on how to
use that plugin. The following example shows how to use the
[`@blockly/field-angle`
plugin](https://www.npmjs.com/package/@blockly/field-angle):
1. Import code from the plugin. How you do this depends on how you installed
the plugin.
```js
import Blockly from 'blockly';
import {registerFieldAngle} from '@blockly/field-angle';
```
You do not need to use an `import` statement.
```js
import {registerFieldAngle} from 'path/to/plugin';
```
1. Initialize the plugin as needed. Plugins that provide custom fields often
require you to register the field:
```js
registerFieldAngle();
```
1. Use the plugin.
```js
Blockly.common.defineBlocksWithJsonArray([
{
type: "my_angle_block",
message0: "%1 degrees",
args0: [
{
// Use @blockly/field-angle.
type: "field_angle",
name: "FIELDNAME",
value: 45,
},
],
output: null,
style: 'math_blocks'
},
]);
```
## Plugin versions
Blockly uses [semantic versioning](https://semver.org), which requires breaking
changes to use a new major version.
Any new plugin that
monkey patches core will have a major version of 0 to [signify initial
development](https://semver.org/#spec-item-4).
Most plugins include the `blockly` package as a
[`peerDependency`](https://docs.npmjs.com/cli/v11/configuring-npm/package-json#peerdependencies)
rather than a `dependency`. This is because we assume that you have already
installed Blockly. (It doesn't make sense to use a plugin without using
Blockly.) Starting with Blockly v13, first-party plugins share an exact version
number with core Blockly. This means that in order to use a certain plugin, all
you can simply check your Blockly version and use the same plugin version.
What if I'm using a major version of Blockly that's older than v13?
Keeping Blockly up-to-date is strongly recommended, so that you get the newest
features and fixes. However, if you can't upgrade Blockly, you can use the
following npm command to list all of the pre-v13 versions of a plugin alongside
the minimum Blockly version that they support:
```
npm view '@blockly/block-plus-minus@<13' peerDependencies.blockly
```
Just replace block-plus-minus with the name of whichever plugin you'd like to
use.
When you add a plugin to your application's `package.json`, the default is to
include a caret before the version:
```json
"dependencies": {
"@blockly/field-angle": "^13.2.1"
}
```
This will let npm install any minor version at or above the listed version, so
version `13.3.1` or `13.2.6` works, but a new major version such as `14.0.1` would
not. When you update to a major version of Blockly, you should update your plugins
as well.
### Keeping plugins up to date with Dependabot
[Dependabot](https://github.com/dependabot) is a popular GitHub tool for
automated dependency updates. If your project is hosted on GitHub, you can use
Dependabot to ensure that Blockly and its plugins are updated together.
To start with, your project's `dependabot.yml` file might look something like
this:
```
updates:
- package-ecosystem: 'npm'
directory: '/'
target-branch: 'main'
schedule:
interval: 'weekly'
```
In `dependabot.yml`, you can group Blockly and its plugins together using
Dependabot's [groups option](https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference#groups--).
For example:
```
updates:
- package-ecosystem: 'npm'
directory: '/'
target-branch: 'main'
schedule:
interval: 'weekly'
groups:
blockly: # You can give this group a different name if you'd like
patterns:
- 'blockly'
- '@blockly/*' # You can use the wildcard (*) notation to specify any plugin
```
---
### Packages Docs Docs Codelabs Context Menu Option Complete Code README (`packages/docs/docs/codelabs/context-menu-option/complete-code/README.md`)
# Completed code
The finished code for the [Customizing context menus](../codelab-overview.mdx) codelab.
## Run it
To run the complete code, navigate to the `complete-code` folder in your terminal, then run:
```bash
npm install # downloads the libraries the app needs (one time)
npm start # opens the app at http://localhost:...
```
New to npm? See [installing node & npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).
---
### Packages Docs Docs Codelabs Css Complete Code README (`packages/docs/docs/codelabs/css/complete-code/README.md`)
# Completed code
The finished code for the [Use CSS in Blockly](../codelab-overview.mdx) codelab.
## Run it
To run the complete code, navigate to the `complete-code` folder in your terminal, then run:
```bash
npm install # downloads the libraries the app needs (one time)
npm start # opens the app at http://localhost:...
```
New to npm? See [installing node & npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).
---
### Packages Docs Docs Codelabs Custom Generator Complete Code README (`packages/docs/docs/codelabs/custom-generator/complete-code/README.md`)
# Completed code
The finished code for the [Build a custom generator](../codelab-overview.mdx) codelab.
## Run it
To run the complete code, navigate to the `complete-code` folder in your terminal, then run:
```bash
npm install # downloads the libraries the app needs (one time)
npm start # opens the app at http://localhost:...
```
New to npm? See [installing node & npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).
---
### Packages Docs Docs Codelabs Custom Mutator Complete Code README (`packages/docs/docs/codelabs/custom-mutator/complete-code/README.md`)
# Blockly Sample App
## Purpose
This app illustrates how to use Blockly together with common programming tools like node/npm, webpack, typescript, eslint, and others. You can use it as the starting point for your own application and modify it as much as you'd like. It contains basic infrastructure for running, building, testing, etc. that you can use even if you don't understand how to configure the related tool yet. When your needs outgrow the functionality provided here, you can replace the provided configuration or tool with your own.
## Quick Start
1. [Install](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) npm if you haven't before.
2. Run [`npx @blockly/create-package app `](https://www.npmjs.com/package/@blockly/create-package) to clone this application to your own machine.
3. Run `npm install` to install the required dependencies.
4. Run `npm run start` to run the development server and see the app in action.
5. If you make any changes to the source code, just refresh the browser while the server is running to see them.
## Tooling
The application uses many of the same tools that the Blockly team uses to develop Blockly itself. Following is a brief overview, and you can read more about them on our [developer site](https://docs.blockly.com/guides/contribute/core/development_tools/).
- Structure: The application is built as an npm package. You can use npm to manage the dependencies of the application.
- Modules: ES6 modules to handle imports to/exports from other files.
- Building/bundling: Webpack to build the source code and bundle it into one file for serving.
- Development server: webpack-dev-server to run locally while in development.
- Testing: Mocha to run unit tests.
- Linting: Eslint to lint the code and ensure it conforms with a standard style.
- UI Framework: Does not use a framework. For more complex applications, you may wish to integrate a UI framework like React or Angular.
You can disable, reconfigure, or replace any of these tools at any time, but they are preconfigured to get you started developing your Blockly application quickly.
## Structure
- `package.json` contains basic information about the app. This is where the scripts to run, build, etc. are listed.
- `package-lock.json` is used by npm to manage dependencies
- `webpack.config.js` is the configuration for webpack. This handles bundling the application and running our development server.
- `src/` contains the rest of the source code.
- `dist/` contains the packaged output (that you could host on a server, for example). This is ignored by git and will only appear after you run `npm run build` or `npm run start`.
### Source Code
- `index.html` contains the skeleton HTML for the page. This file is modified during the build to import the bundled source code output by webpack.
- `index.js` is the entry point of the app. It configures Blockly and sets up the page to show the blocks, the generated code, and the output of running the code in JavaScript.
- `serialization.js` has code to save and load the workspace using the browser's local storage. This is how your workspace is saved even after refreshing or leaving the page. You could replace this with code that saves the user's data to a cloud database instead.
- `toolbox.js` contains the toolbox definition for the app. The current toolbox contains nearly every block that Blockly provides out of the box. You probably want to replace this definition with your own toolbox that uses your custom blocks and only includes the default blocks that are relevant to your application.
- `blocks/text.js` has code for a custom text block, just as an example of creating your own blocks. You probably want to delete this block, and add your own blocks in this directory.
- `generators/javascript.js` contains the JavaScript generator for the custom text block. You'll need to include block generators for any custom blocks you create, in whatever programming language(s) your application will use.
## Serving
To run your app locally, run `npm run start` to run the development server. This mode generates source maps and ingests the source maps created by Blockly, so that you can debug using unminified code.
To deploy your app so that others can use it, run `npm run build` to run a production build. This will bundle your code and minify it to reduce its size. You can then host the contents of the `dist` directory on a web server of your choosing. If you're just getting started, try using [GitHub Pages](https://pages.github.com/).
---
### Packages Docs Docs Codelabs Custom Renderer Complete Code README (`packages/docs/docs/codelabs/custom-renderer/complete-code/README.md`)
# Completed code
The finished code for the [Build a custom renderer](../codelab-overview.mdx) codelab.
## Run it
To run the complete code, navigate to the `complete-code` folder in your terminal, then run:
```bash
npm install # downloads the libraries the app needs (one time)
npm start # opens the app at http://localhost:...
```
New to npm? See [installing node & npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).
---
### Packages Docs Docs Codelabs Custom Toolbox Complete Code README (`packages/docs/docs/codelabs/custom-toolbox/complete-code/README.md`)
# Completed code
The finished code for the [Customizing a Blockly toolbox](../codelab-overview.mdx) codelab.
## Run it
To run the complete code, navigate to the `complete-code` folder in your terminal, then run:
```bash
npm install # downloads the libraries the app needs (one time)
npm start # opens the app at http://localhost:...
```
New to npm? See [installing node & npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).
---
### Packages Docs Docs Codelabs Getting Started Complete Code README (`packages/docs/docs/codelabs/getting-started/complete-code/README.md`)
# Completed code
The finished code for the [Getting started](../codelab-overview.mdx) codelab.
## Run it
To run the complete code, navigate to the `complete-code` folder in your terminal, then run:
```bash
npm install # downloads the libraries the app needs (one time)
npm start # opens the app at http://localhost:...
```
New to npm? See [installing node & npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).
---
### Packages Docs Docs Codelabs Theme Extension Identifier Complete Code README (`packages/docs/docs/codelabs/theme-extension-identifier/complete-code/README.md`)
# Completed code
The finished code for the [Customizing your themes](../codelab-overview.mdx) codelab.
## Run it
To run the complete code, navigate to the `complete-code` folder in your terminal, then run:
```bash
npm install # downloads the libraries the app needs (one time)
npm start # opens the app at http://localhost:...
```
New to npm? See [installing node & npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).
---
### Packages Docs Docs Codelabs Validation And Warnings Complete Code README (`packages/docs/docs/codelabs/validation-and-warnings/complete-code/README.md`)
# Completed code
The finished code for the [block validation and warnings](../codelab-overview.mdx) codelab.
## Run it
To run the complete code, navigate to the `complete-code` folder in your terminal, then run:
```bash
npm install # downloads the libraries the app needs (one time)
npm start # opens the app at http://localhost:...
```
New to npm? See [installing node & npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).
---
### Packages Docs Docs Guides Contribute Core Index (`packages/docs/docs/guides/contribute/core/index.mdx`)
---
description: Learn how to contribute changes to Blockly Core.
title: Contribute to core
image: images/blockly_banner.png
---
# Contribute to core
The [Blockly](https://github.com/RaspberryPiFoundation/blockly) core repository contains the
code that is needed to run any Blockly-based application. It also contains the documentation, including codelabs.
## Need to Know
Here is a quick overview of facts about Blockly core you need to know in order
to create a PR.
- The working branch is **main** and all PRs should be made against
main.
- You must fill out the pull request template with the requested information.
- Code must conform to Blockly's [style guide](style_guide)
- Use [conventional commits](/guides/contribute/get-started/commits)
in your commit messages and pull request titles.
- PR summaries and comments should be human written, and AI usage is not allowed
on issues labeled `good first issue`. Consult the [AI policy](/guides/contribute/core/ai_policy)
for more information.
- User-visible strings must be in the `/msg/messages.js` file so they may be
translated. Less than 6% of the world speaks English natively.
- Text on blocks should generally be all lowercase (just like the keywords in
most programming languages).
- Maintain backwards compatibility. There are a _lot_ of Blockly apps out
there, don't break everyone else.
- Any new code files must be prefixed with the Apache License v2.0:
```js
/**
* @license
* Copyright Raspberry Pi Foundation
* SPDX-License-Identifier: Apache-2.0
*/
```
## Make and Verify a Change
1. Run `npm install` to install dependencies.
1. Run `npm run start` to start up a server running the playground. You can use
this page to test the existing behavior. See the
[playground](/guides/contribute/get-started/playground) page for
more information.
1. Make any necessary changes to the code.
1. If you've left the server running, refresh to see your changes. Otherwise,
restart the server and verify the code behaves as expected and there are no
errors or warnings in the console.
1. Run `npm run build` and ensure there are no build errors.
1. Write automated tests. Usually, these will be mocha tests in the
`tests/mocha` directory, but we may ask you for other types of tests.
1. Run `npm run format` to format the code and automatically fix some lint
problems.
1. Run `npm test` to run the automated tests. This also runs `eslint`.
1. If there are lint errors, run `npm run lint-fix` to fix the problems that
are autofixable. Address any remaining lint warnings or errors.
1. If all tests pass, you are ready to open a PR against **main** with your
changes.
---
### Packages Docs Docs Guides Contribute Get Started Index (`packages/docs/docs/guides/contribute/get-started/index.mdx`)
---
description: Learn about contributing to Blockly.
title: Get started contributing to Blockly
image: images/blockly_banner.png
---
# Get started contributing to Blockly
Blockly is open source and is primarily maintained by a small team. We welcome
contributions from developers outside the core team; there is no way for us to
build every requested feature or fix every reported bug without our community.
:::info
This section contains general guides on contributing to Blockly. These guides
are generally intended for those who are new to Blockly or new to open-source
development.
:::
For information specific to Blockly that you should read before making a
contribution, see the
[Contributing to Core](/guides/contribute/core) and
[Contributing to Samples](/guides/contribute/samples) sections.
## Which repository?
A **repository** contains all the files for a single project. Blockly has two
repositories: blockly and blockly-samples.
**[Blockly](https://github.com/RaspberryPiFoundation/blockly)** is the
repository for the Blockly library. Use this repository if you want to make a
change to core Blockly behaviour in a way that will apply to all users of the
library. Blockly core also contains the documentation, including the codelabs
and codelab solutions.
**[Blockly samples](https://github.com/raspberrypifoundation/blockly-samples)**
is the repository for examples that show uses of the Blockly library. Use this
repository if you want to create or modify a sample.
### Pre work: Understand Git and GitHub basics
We use Git and GitHub for managing version control, collaboration, and distribution
of Blockly. If you're new to Git and GitHub, work through GitHub's
[quickstart](https://docs.github.com/en/free-pro-team@latest/github/getting-started-with-github/quickstart)
tutorials to get comfortable with the basics.
To learn about the rest of Blockly's development tools, see the [Contribute to Core](/guides/contribute/core/)
documentation.
### Setup
These are the one-time setup steps you'll need to get started:
1. **Install** [Git](https://github.com/git-guides/install-git) and [Node](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
1. **Fork and clone the repository.** GitHub has a wonderful tutorial about
[forking a repo](https://help.github.com/en/github/getting-started-with-github/fork-a-repo#fork-an-example-repository).
To apply it to blockly, just replace every instance of
**octocat/Spoon-Knife** with **RaspberryPiFoundation/blockly** or
**RaspberryPiFoundation/blockly-samples**, depending on which repository you want to work
in.
### Step by step
These are the general steps you will follow any time you make a change.
1. **Sync your fork.** GitHub provides a tutorial for
[syncing a fork](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/syncing-a-fork).
1. **Check out the `main` branch** by running `git checkout main` in a
terminal.
1. **Install** dependencies and build tools by running `npm install` in the
root directory.
1. **Create a new branch** by running `git checkout -b myBranchName` in a
terminal. The branch name should help you remember what you're working on.
1. **Make your changes.**
1. **Validate your changes,** following the guide for
[core](/guides/contribute/core) or
[samples](/guides/contribute/samples).
1. **Add your changes** to a commit with `git add your/file/path`.
1. **Save your changes** with `git commit -m "fix: My commit message"`.
[Read more about commit messages](commits).
1. **Push your changes** to GitHub with `git push origin myBranchName`.
1. **Open a pull request** when your code is ready. A member of the Blockly
team will review your changes and merge them into Blockly if they are
approved. For more information see
[PR Review Process](/guides/contribute/get-started/write_a_good_pr#read-the-review).
---
### Packages Docs Docs Guides Create Custom Blocks Code Generation Overview (`packages/docs/docs/guides/create-custom-blocks/code-generation/overview.mdx`)
---
description: What code generation is, and how to implement it.
title: Code generation
image: images/blockly_banner.png
---
# Code generation
Code generation is the process of turning the blocks on a workspace into a
string of code that can be executed.
Code generation is extremely important, because it is what allows your blocks to
actually _do_ things, like evaluate arithmetic expressions, move a character
through a maze, or configure an online shop!
You can't "run" blocks directly. Instead you generate code strings, and then
execute those.
## Language code generators
To generate code, you have to pick what text-based language you want to
generate. This is because each language has its own code generator.
A **language code generator** (commonly called a **code generator**) is a class
that handles the rules for generating code that are specific to a given
language, but not specific to an individual block. For example, it handles
things like formatting comments, indenting statements, and quoting strings.
Blockly provides 5 built-in code generators:
- JavaScript ES5
- Python 3
- Lua 5.1
- Dart 2
- PHP 7
If this list doesn't include the language you want to generate code for, you can
create a custom language code generator. For a simple example, see the [Build a
custom generator][custom-code-generator] codelab, which creates a JSON language
code generator. For a more complex example, see the [JavaScript code
generator][js-code-generator]. Note that you also need to write block-code
generators for any built-in blocks that you want to use.
## Block-code generators
Each block is responsible for generating its own code. When you create a block,
you need to write a separate block-code generator for each language you want to
support.
A **block-code generator** is a function that returns the code for that block as
a string. For example, a block that compares two numbers returns a string of the
form `'a < b'` and a block that represents an if statement returns a string of
the form `'if (...) {\n...\n};\n'`.
```js
import { javascriptGenerator } from 'blockly/javascript';
import { pythonGenerator } from 'blockly/python';
// Write block-code generators for JavaScript and Python.
javascriptGenerator.forBlock['my_custom_block'] = function (block, generator) {
/* ... */
};
pythonGenerator.forBlock['my_custom_block'] = function (block, generator) {
/* ... */
};
```
Block-code generators are called by language code generators.
For more information, see [Block-code
generators](/guides/create-custom-blocks/code-generation/block-code).
## Generate and run code
Your application can generate code at any time. For example, it might generate
code when the end-user clicks a button or every time the user makes a change.
After you've generated the code, you need to figure out how to execute it.
Deciding how to execute it is very application-specific, and outside the scope
of Blockly.
For more information, see [Generate and run
code](/guides/app-integration/run-code).
[custom-code-generator]: /codelabs/custom-generator/codelab-overview
[js-code-generator]: https://github.com/RaspberryPiFoundation/blockly/blob/main/packages/blockly/generators/javascript/javascript_generator.ts
---
### Packages Docs Docs Guides Create Custom Blocks Fields Overview (`packages/docs/docs/guides/create-custom-blocks/fields/overview.mdx`)
---
description: What field are, which kinds are provided by default, and how to customize them.
title: Fields
image: images/blockly_banner.png
---
# Fields
Fields are used to define most UI elements on a block. Examples of fields
include string labels, images, inputs for literal data such as strings and
numbers, and rich editors like date pickers and angle pickers. The simplest
example of a field is the `math_number` block, which uses a `field_number` to
let the user type a number.
:::note
If you need to show meta-information about a block, you probably want an
icon instead. Read more about [Fields vs Icons][fields-vs-icons].
:::
Blockly provides several fields by default to handle a variety of user input.
These can be customized through field-specific configuration or with validators,
which tell a field how to handle specific content in a standard editor.
→ More info on [Built-in fields](/guides/create-custom-blocks/fields/built-in-fields/overview).
→ More info on [Validators](/guides/create-custom-blocks/fields/validators).
If you need a fully custom field it takes a bit more work and you'll want to
read most of the fields documentation. Start by learning about the parts
that make up a field or the overview of creating custom fields.
→ More info on the [anatomy of a field](/guides/create-custom-blocks/fields/anatomy-of-a-field).
→ More info on [creating custom fields](/guides/create-custom-blocks/fields/customizing-fields/overview).
[fields-vs-icons]: /guides/create-custom-blocks/fields/fields-vs-icons
---
### Packages Docs Docs Guides Create Custom Blocks Icons Overview (`packages/docs/docs/guides/create-custom-blocks/icons/overview.mdx`)
---
description: What icons are, and how to customize them.
title: Icons
image: images/blockly_banner.png
---
# Icons
Icons are used to define certain UI elements that show or define "meta"
information about a block. Usually this means they act as a clickable button
that opens a pop up with more information or an editor.
→ More info on [Fields vs Icons][fields-vs-icons].
Blockly provides some built-in icons that fulfill common use cases, like adding
comments or warnings to blocks. You can check out the [reference
documentation][icons-reference] for more information about those.
Blockly also lets you define your own custom icons if the built-in ones don't
serve your use case. For example, you might want an icon that displays version
or copyright information in a pop-up bubble.
→ More info on [Creating custom icons][custom-icons].
[fields-vs-icons]: /guides/create-custom-blocks/fields/fields-vs-icons
[custom-icons]: /guides/create-custom-blocks/icons/creating-custom-icons/basic-implementation
[icons-reference]: /reference/namespaces/icons
---
### Packages Docs Docs Guides Create Custom Blocks Procedures Overview (`packages/docs/docs/guides/create-custom-blocks/procedures/overview.mdx`)
---
description: Overview of how Blockly conceptualizes procedures.
title: Procedures
image: images/blockly_banner.png
---
# Procedures
In computer science terms, a procedure is a reusable bit of code that performs a
specific task.
Blockly implements procedures as a set of blocks that generate code for defining
a procedure, and calling it.
→ More info on [using the blocks](/guides/create-custom-blocks/procedures/using-procedures).
→ More info on [creating custom procedure blocks](/guides/create-custom-blocks/procedures/creating-custom-procedure-blocks).
→ More info on [creating custom procedure models](/guides/create-custom-blocks/procedures/creating-custom-procedure-data-models), which allow you to add new functionality like typed parameters.
## Built-in vs plugin
Blockly provides two implementations of procedure blocks.
One exists in the plugin [@blockly/block-shareable-procedures][shareable-procedures],
which implements procedure blocks that rely on a backing data model. This allows
you to do things with your procedure blocks such as having the definition
block exist in one workspace, and the call block exist in another. The plugin is
the recommended implementation of procedure blocks.
The other is the legacy implementation, provided in Blockly core. These blocks
don't have a backing data model, and all information about procedures comes
from the blocks themselves. The only way a workspace knows which procedures
are available is by inspecting the procedure definition blocks contained in
that workspace. These blocks continue to be supported for backwards
compatibility, but most developers should be able to use the new blocks
provided by the plugin.
- If you are using XML serialization, you can use the new blocks, but they
won't be shareable across workspaces. That feature requires extra serialization
that is only provided by the JSON serializer. When using XML, the new blocks
will behave identically to the legacy blocks.
[Learn more about upgrading to JSON](https://docs.google.com/document/d/1wv5ORrO4icVHeU15FLSn37mdNLyJpQbMTo7mmTqsGl0/edit?usp=sharing).
- If you have defined custom procedure blocks, they need to be
[updated](/guides/create-custom-blocks/procedures/creating-custom-procedure-blocks)
to work with the new data models.
- If you have defined custom procedure definition blocks, _but are using the
built-in procedure call block_, you need to continue using the legacy caller
block until you [update](/guides/create-custom-blocks/procedures/creating-custom-procedure-blocks)
your definition block.
[shareable-procedures]: https://www.npmjs.com/package/@blockly/block-shareable-procedures
---
### Packages Docs Docs Guides Create Custom Blocks Renderers Overview (`packages/docs/docs/guides/create-custom-blocks/renderers/overview.mdx`)
---
description: What a renderer is, built-in renderers, and how to create a custom one.
title: Renderers
image: images/blockly_banner.png
---
# Renderers
The shape of a block is determined by a renderer, based on the
[block's definition][block-definition] (that is, its fields and connections).
## Built-in renderers
Blockly provides three built-in renderers, each of which give a slightly
different feel to the program.
| Renderer | Description | Image |
| -------- | ------------------------------------------------------------------------------------------------------------------- | ------------------- |
| Thrasos | The recommended renderer. It is a more modern take on the geras renderer, with more even spacing and solid borders. | ![thrasos][thrasos] |
| Geras | The default renderer. It is the original renderer that Blockly was built with. | ![geras][geras] |
| Zelos | A renderer based on Scratch-3.0 block design. | ![zelos][zelos] |
To use one of these renderers, pass the name into the configuration options:
```js
Blockly.inject('blocklyDiv', {
renderer: 'thrasos',
});
```
## Custom renderers
If you want to give your program a different look and feel than any of the
built-in renderers, you can also create a custom renderer. To get started the
Blockly team recommends you:
1. Read through the [renderer concept docs][concept] to learn
how all of the components of a renderer fit together.
2. Complete the [custom renderer codelab][custom-renderer-codelab] to
get hands-on practice with custom rendering.
3. Add the [debug renderer][debug-renderer] to your project.
4. Customize your renderer.
[block-definition]: /guides/create-custom-blocks/define/block-definitions
[concept]: /guides/create-custom-blocks/renderers/concepts/overview
[custom-renderer-codelab]: /codelabs/custom-renderer/codelab-overview
[debug-renderer]: https://www.npmjs.com/package/@blockly/dev-tools#debug-renderer
[thrasos]: /images/rendering/renderers/thrasos.png
[geras]: /images/rendering/renderers/geras.png
[zelos]: /images/rendering/renderers/zelos.png
---
### Packages Docs Docs Guides Create Custom Blocks Fields Built In Fields Overview (`packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/overview.mdx`)
---
title: Built-in fields
image: images/blockly_banner.png
---
# Built-in fields
Blockly provides a number of prebuilt fields that you can use when defining a
block. There are also a number of fields available as
[plugins](/guides/programming/plugin_overview).
Built-in fields:
- [Checkbox](/guides/create-custom-blocks/fields/built-in-fields/checkbox)
- [Dropdown](/guides/create-custom-blocks/fields/built-in-fields/dropdown)
- [Image](/guides/create-custom-blocks/fields/built-in-fields/image)
- [Label](/guides/create-custom-blocks/fields/built-in-fields/label)
- [Serializable label](/guides/create-custom-blocks/fields/built-in-fields/label-serializable)
- [Number](/guides/create-custom-blocks/fields/built-in-fields/number)
- [Text input](/guides/create-custom-blocks/fields/built-in-fields/text-input)
- [Variables](/guides/create-custom-blocks/fields/built-in-fields/variable)
Plugin fields:
- [Angle picker](https://www.npmjs.com/package/@blockly/field-angle)
- [Bitmap](https://www.npmjs.com/package/@blockly/field-bitmap)
- [Colour picker](https://www.npmjs.com/package/@blockly/field-colour)
- [Colour picker with HSV sliders](https://www.npmjs.com/package/@blockly/field-colour-hsv-sliders)
- [Date](https://www.npmjs.com/package/@blockly/field-date)
- [Dropdown grid](https://www.npmjs.com/package/@blockly/field-grid-dropdown)
- [Dependent dropdown](https://www.npmjs.com/package/@blockly/field-dependent-dropdown)
- [Multiline text input](https://www.npmjs.com/package/@blockly/field-multilineinput)
- [Number slider](https://www.npmjs.com/package/@blockly/field-slider)
For a full list of plugin fields, see [Blockly Plugins & Demos][blockly-demos].
[blockly-demos]: https://raspberrypifoundation.github.io/blockly-samples/#fields
---
### Packages Docs Docs Guides Create Custom Blocks Fields Customizing Fields Overview (`packages/docs/docs/guides/create-custom-blocks/fields/customizing-fields/overview.mdx`)
---
description: Methods for customizing fields.
title: Custom fields
image: images/blockly_banner.png
---
# Custom fields
While Blockly provides many useful fields, your application may have a
specialized case. Here are a few steps to take when customizing fields:
1. Read the documentation of any fields similar to what you require; they may
provide a useful interface for customization. For example,
[dropdowns](/guides/create-custom-blocks/fields/built-in-fields/dropdown) have a lot of hidden functionality.
2. Consider using a [validator](/guides/create-custom-blocks/fields/validators) to solve your problem.
Validators allow you to only accept certain values, modify input, or trigger
functionality when a field's value changes.
3. Consider [extending a field](/guides/create-custom-blocks/fields/customizing-fields/extending).
If there is a field that represents the value type you require, but you want to
modify its [editor](/guides/create-custom-blocks/fields/anatomy-of-a-field#editor-display), its
[appearance](/guides/create-custom-blocks/fields/anatomy-of-a-field#on-block-display), or the
[text](/guides/create-custom-blocks/fields/customizing-fields/creating#text) it
displays, you can [create a subclass](/guides/create-custom-blocks/fields/customizing-fields/extending#subclassing)
that inherits the bulk of the functionality, while overriding the specific parts
you want to change.
4. [Create a new field type](/guides/create-custom-blocks/fields/customizing-fields/creating).
While this is the most powerful option, it is also the most time consuming, and
should generally only be used if you need to store a new value type.
---
### Packages Docs Docs Guides Create Custom Blocks Renderers Concepts Overview (`packages/docs/docs/guides/create-custom-blocks/renderers/concepts/overview.mdx`)
---
description: An overview of important renderer concepts.
title: Renderer concepts
image: images/blockly_banner.png
---
import Image from '@site/src/components/Image';
# Renderer concepts
Before you start building a custom renderer, it is helpful to understand the
different components that make up a renderer, as well as how a block gets
broken up into rows and elements.
## Renderer components
A renderer is built up of several different components. Each component has a
unique job to maximize code reuse and extensibility.
### Renderer
The [renderer][renderer] is a factory class that bundles all of the other
components together.
### Constant provider
The [constant provider][constants] is a collection of numbers, and shapes used
by all of the other components, as well as built-in fields.
### Render info
The [render info][render-info] decides how it a block should be laid out based
on its definition, and then creates a collection of
[measurables](#block-measurables) and data about the block which the
[drawer][drawer] uses to create SVG paths.
### Path Object
The [path object][path-object] contains the SVG elements that live in the dom
and make up the block.
### Drawer
The [drawer][drawer] (as in "one-who-draws") builds SVG [paths][paths] based on
the [render info][render-info] and applies them to the
[path object][path-object].
## Block measurables
A measurable is a rectangle representing a region of a block. Measurables are
what the [render info][render-info] uses to define the layout of the block.
Some measurables also include extra data (such as the visual thing they are
representing), or helper methods that the render info can use to figure out how
to lay out the block.
Different renderers may create custom measurables to change these data or
helper methods.
### Rows
A [row][row] is a horizontal collection of [elements][element] and
[element spacers][element-spacer].
### Row spacers
A [row spacer][row-spacer] is an empty vertical space that goes between two
rows.
### Elements
An [element][element] represents a visual thing on a block. These include
[fields][field], [icons][icon], connections, etc.
### Element spacers
An [element spacer][element-spacer] is an empty space that goes between elements
in a row.
[renderer]: /guides/create-custom-blocks/renderers/concepts/renderer
[constants]: /guides/create-custom-blocks/renderers/concepts/constants
[render-info]: /guides/create-custom-blocks/renderers/concepts/info
[path-object]: /guides/create-custom-blocks/renderers/concepts/path-object
[drawer]: /guides/create-custom-blocks/renderers/concepts/drawer
[paths]: https://developer.mozilla.org/en-US/docs/Web/SVG/Tutorial/Paths
[row]: /guides/create-custom-blocks/renderers/concepts/rows
[element]: /guides/create-custom-blocks/renderers/concepts/elements
[row-spacer]: /guides/create-custom-blocks/renderers/concepts/rows#row-spacer
[element-spacer]: /guides/create-custom-blocks/renderers/concepts/elements#element-spacer
[field]: /guides/create-custom-blocks/fields/overview
[icon]: /guides/create-custom-blocks/icons/overview
[row-image]: /images/rendering/debug-renderer/row.png
[row-spacer-image]: /images/rendering/debug-renderer/row-spacer.png
[element-image]: /images/rendering/debug-renderer/element.png
[element-spacer-image]: /images/rendering/debug-renderer/element-spacer.png
---
### Packages Docs AGENTS (`packages/docs/AGENTS.md`)
# packages/docs — developer documentation site
A Docusaurus site. Built as the `blockly-docs` Nx project; it is not released to npm.
Repo-wide conventions are in the [root `AGENTS.md`](../../AGENTS.md).
## Commands
Run from `packages/docs/`, or from the repo root as `npm run build-docs`.
```bash
npm start # build the API reference, then serve the site locally
npm run build # production build
npm run serve # serve an already-built site
npm run clear # clear the Docusaurus cache
npm run lint # ESLint over docs/**/*.mdx
npm run lint-fix
```
## Things to know
- **`docs/reference/` is generated** by TypeDoc during the Docusaurus build, and is
gitignored. Never edit those files directly — fix the TSDoc in `packages/blockly/core/`
instead.
- **The reference is built from `blockly_api.json`, not from the current source.** That
file is a snapshot of the core library's API committed during a release, so the site
documents the released API rather than whatever is on `main`. To preview your own TSDoc
changes, run `npm run reference:refresh` to regenerate it locally — then leave it out of
your commit, since only a release should update it.
- **Markdown and MDX here are linted, not Prettier-formatted.** `packages/docs/**/*.md`
and `*.mdx` are listed in `.prettierignore` and handled by ESLint with
`eslint-plugin-mdx` instead, so `npm run format` will not touch them.
- Prose wrapping is preserved rather than reflowed, so existing line breaks in prose are
intentional — don't rewrap paragraphs you aren't otherwise changing.
---
### Packages Docs Static Robots (`packages/docs/static/robots.txt`)
# Algolia-Crawler-Verif: 836ECEE0BC07004B
# Allow the Algolia Crawler to access the entire site
User-agent: Algolia Crawler
Allow: /
User-agent: *
Allow: /
---
### Packages Docs Docs Codelabs Context Menu Option Add A Context Menu Item (`packages/docs/docs/codelabs/context-menu-option/add-a-context-menu-item.mdx`)
---
description: How to add a context menu item to the registry.
---
import Image from '@site/src/components/Image';
# Customizing context menus
## 3. Add a context menu item
In this section you will create a very basic `Blockly.ContextMenuRegistry.RegistryItem`, then register it to display when you open a context menu on the workspace, a block, or a comment.
### The RegistryItem
A context menu consists of one or more menu options that a user can select. Blockly stores information about menu option as items in a registry. You can think of the _registry items_ as templates for constructing _menu options_. When the user opens a context menu, Blockly retrieves all of the registry items that apply to the current context and uses them to construct a list of menu options.
Each item in the registry has several properties:
- `displayText`: The text to show in the menu. Either a string, or HTML, or a function that returns either of the former.
- `preconditionFn`: Function that returns one of `'enabled'`, `'disabled'`, or `'hidden'` to determine whether and how the menu option should be rendered.
- `callback`: A function called when the menu option is selected.
- `id`: A unique string id for the item.
- `weight`: A number that determines the sort order of the option. Options with higher weights appear later in the context menu.
We will discuss these in detail in later sections of the codelab.
### Make a RegistryItem
Add a function to `src/index.js` named `registerHelloWorldItem`. Create a new registry item in your function:
```js
function registerHelloWorldItem() {
const helloWorldItem = {
displayText: 'Hello World',
preconditionFn: function (scope) {
return 'enabled';
},
callback: function (scope) {},
id: 'hello_world',
weight: 100,
};
}
```
Call your function in `src/index.js`, before the UI element setup and `Blockly.inject` call:
```js
registerHelloWorldItem();
// Set up UI elements and inject Blockly
const codeDiv = document.getElementById('generatedCode').firstChild;
// ...
const ws = Blockly.inject(blocklyDiv, {toolbox});
```
### Register it
Next, register your item with Blockly:
```js
function registerHelloWorldItem() {
const helloWorldItem = {
// ...
};
Blockly.ContextMenuRegistry.registry.register(helloWorldItem);
}
```
:::note
You will never need to make a new `ContextMenuRegistry`. Always use the singleton `Blockly.ContextMenuRegistry.registry`.
:::
### Enable comment context menus
This codelab demonstrates context menus on workspaces, blocks, and comments. Blockly registers the workspace and block options by default, but the comment options (including the **Add Comment** option you'll use to create comments while testing) must be registered separately. Add this call to `src/index.js`, before the `Blockly.inject` call:
```js
Blockly.ContextMenuItems.registerCommentOptions();
```
### Test it
Refresh the running page (or run `npm start`) and open a context menu on the workspace (right-click with a mouse, or press `Ctrl+Enter` (Windows) or `Command+Enter` (Mac) if you are navigating Blockly with the keyboard). You should see a new option labeled "Hello World" at the bottom of the context menu.
Next, drag a block onto the workspace and open a context menu on the block. You'll see "Hello World" at the bottom of the block's context menu. Finally, open a context menu on the workspace and create a comment, then open a context menu on the comment's header. "Hello World" should be at the bottom of the context menu.
---
### Packages Docs Docs Codelabs Context Menu Option Callback (`packages/docs/docs/codelabs/context-menu-option/callback.mdx`)
---
description: How to add a callback to a context menu item.
---
import Image from '@site/src/components/Image';
# Customizing context menus
## 7. Callback
The callback function determines what happens when you select the context menu option. Like the precondition, it can use the `scope` argument to access the Blockly component on which the context menu was invoked.
It is also passed a `PointerEvent` which is the original event that triggered opening the context menu (not the event that selected the current option). This lets you, for example, figure out where on the workspace the context menu was opened so you can create a new element there.
As an example, update the help item's `callback` to add a block to the workspace when selected:
```js
callback: function(scope) {
Blockly.serialization.blocks.append({
'type': 'text',
'fields': {
'TEXT': 'Now there is a block'
}
}, scope.focusedNode);
},
```
### Test it
- Refresh the running page and open a context menu on the workspace.
- Select the **Help** option.
- A text block should appear in the top left of the workspace.
---
### Packages Docs Docs Codelabs Context Menu Option Display Text (`packages/docs/docs/codelabs/context-menu-option/display-text.mdx`)
---
description: How to set the display text of a context menu item.
---
import Image from '@site/src/components/Image';
# Customizing context menus
## 8. Display text
So far the `displayText` has always been a simple string, but it can also be HTML, or a function that returns either of the former. Using a function can be useful when you want a context-dependent message.
When defined as a function `displayText` accepts a `scope` argument, just like `callback` and `preconditionFn`.
As an example, add this registry item. The display text depends on the block type.
```js
function registerDisplayItem() {
const displayItem = {
displayText: function (scope) {
if (scope.focusedNode.type.startsWith('text')) {
return 'Text block';
} else if (scope.focusedNode.type.startsWith('controls')) {
return 'Controls block';
} else {
return 'Some other block';
}
},
preconditionFn: function (scope) {
return scope.focusedNode instanceof Blockly.BlockSvg
? 'enabled'
: 'hidden';
},
callback: function (scope) {},
id: 'display_text_example',
weight: 100,
};
Blockly.ContextMenuRegistry.registry.register(displayItem);
}
```
As usual, remember to call `registerDisplayItem()` in `src/index.js`, before `Blockly.inject`.
### Test it
- Refresh the running page and open context menus on various blocks.
- The last context menu option's text should vary based on the block type.
---
### Packages Docs Docs Codelabs Context Menu Option Precondition Blockly State (`packages/docs/docs/codelabs/context-menu-option/precondition-blockly-state.mdx`)
---
description: How to include a context menu item based on Blockly's state.
---
import Image from '@site/src/components/Image';
# Customizing context menus
## 6. Precondition: Blockly state
Disabling your context menu options half of the time is not useful, but you may want to show or hide an option based on what the user is doing. For example, let's show a **Help** option in the context menu if the user doesn't have any blocks on the workspace. Add this code in `src/index.js`:
```js
function registerHelpItem() {
const helpItem = {
displayText: 'Help! There are no blocks',
preconditionFn: function (scope) {
if (!(scope.focusedNode instanceof Blockly.WorkspaceSvg)) return 'hidden';
if (!scope.focusedNode.getTopBlocks().length) {
return 'enabled';
}
return 'hidden';
},
callback: function (scope) {},
id: 'help_no_blocks',
weight: 100,
};
Blockly.ContextMenuRegistry.registry.register(helpItem);
}
```
Don't forget to call `registerHelpItem()` in `src/index.js`, before `Blockly.inject`.
### Test it
- Refresh the running page and open a context menu on the workspace. You should see an option labeled "Help! There are no blocks".
- Add a block to the workspace and open a context menu on the workspace again. The **Help** option should be gone.
---
### Packages Docs Docs Codelabs Context Menu Option Precondition External State (`packages/docs/docs/codelabs/context-menu-option/precondition-external-state.mdx`)
---
description: How to include a context menu item based on an external condition.
---
import Image from '@site/src/components/Image';
# Customizing context menus
## 5. Precondition: External state
Use of the `preconditionFn` is not limited to checking the type of the Blockly component that the context menu was invoked on. You can use it to check for conditions entirely outside of Blockly. For instance, let's disable `helloWorldItem` for the second half of every minute:
```js
preconditionFn: function (scope) {
if (
scope.focusedNode instanceof Blockly.WorkspaceSvg ||
scope.focusedNode instanceof Blockly.BlockSvg
) {
const now = new Date(Date.now());
if (now.getSeconds() < 30) {
return 'enabled';
}
return 'disabled';
}
return 'hidden';
},
```
### Test it
Refresh the running page, check your watch, and open a context menu on the workspace to confirm the timing. The option will always be in the menu, but will sometimes be greyed out.
---
### Packages Docs Docs Codelabs Context Menu Option Precondition Node Type (`packages/docs/docs/codelabs/context-menu-option/precondition-node-type.mdx`)
---
description: How to include a context menu item based on the node type.
---
import Image from '@site/src/components/Image';
# Customizing context menus
## 4 . Precondition: Node type
Each registry item has a `preconditionFn`. It is called by Blockly to decide whether and how to display an option on a context menu. You'll use it to display the "Hello, World" option on workspace and block context menus, but not on comment context menus.
### The scope argument
The `scope` argument is an object that is passed to `preconditionFn`. You'll use the `scope.focusedNode` property to determine which object the context menu was invoked on. Why a focused node? Because Blockly keeps track of where the user is -- that is, what node (component) the user is focused on -- and opens the context menu on that node.
### Return value
The return value of `preconditionFn` is `'enabled'`, `'disabled'`, or `'hidden'`. An **enabled** option is shown with black text and is selectable. A **disabled** option is shown with grey text and is not selectable. A **hidden** option is not included in the context menu at all.
### Write the function
You can now test `scope.focusedNode` to display the "Hello World" option in workspace and block context menus, but not on any others. Change `preconditionFn` to:
```js
const helloWorldItem = {
...
preconditionFn: function (scope) {
if (
scope.focusedNode instanceof Blockly.WorkspaceSvg ||
scope.focusedNode instanceof Blockly.BlockSvg
) {
return 'enabled';
}
return 'hidden';
},
...
};
```
Notice that the code tests for where context menus are allowed, rather than where they are not allowed. This is because custom code (such as a plugin) can add context menus to any Blockly component that can be focused. Thus, testing for specific types rather than allowing all (or all but certain types) ensures that context menus are not shown on more components than you anticipated.
### Test it
Open a context menu on the workspace, a block, and a comment. You should see a "Hello World" option on the workspace and block context menus, but not on the comment context menu.
---
### Packages Docs Docs Codelabs Context Menu Option Separators (`packages/docs/docs/codelabs/context-menu-option/separators.mdx`)
---
description: How to add a separator to a context menu.
---
import Image from '@site/src/components/Image';
# Customizing context menus
## 10. Separators
You can use separators to break your context menu into different sections.
Separators differ from other items in two ways: They cannot have `displayText`, `preconditionFn`, or `callback` properties and they can only be scoped with the `scopeType` property. The latter accepts an enum value of `Blockly.ContextMenuRegistry.ScopeType.WORKSPACE`, `Blockly.ContextMenuRegistry.ScopeType.BLOCK`, or `Blockly.ContextMenuRegistry.ScopeType.COMMENT`.
Use the `weight` property to position the separator. You'll use a weight of `99` to position the separator just above the other options you added, all of which have a weight of `100`.
You need to add a separate item for each separator:
```js
function registerSeparators() {
const workspaceSeparator = {
id: 'workspace_separator',
scopeType: Blockly.ContextMenuRegistry.ScopeType.WORKSPACE,
weight: 99,
separator: true,
};
Blockly.ContextMenuRegistry.registry.register(workspaceSeparator);
const blockSeparator = {
id: 'block_separator',
scopeType: Blockly.ContextMenuRegistry.ScopeType.BLOCK,
weight: 99,
separator: true,
};
Blockly.ContextMenuRegistry.registry.register(blockSeparator);
}
```
As usual, remember to call `registerSeparators()` in `src/index.js`, before `Blockly.inject`.
### Test it
Open a context menu on the workspace and a block and check that the separator line is there.
---
### Packages Docs Docs Codelabs Context Menu Option Setup (`packages/docs/docs/codelabs/context-menu-option/setup.mdx`)
---
description: Setting up the "Customizing context menus" codelab.
---
import Image from '@site/src/components/Image';
# Customizing context menus
## 2. Setup
### Create the application
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.
1. Run `npx @blockly/create-package app context-menu-option-codelab` in your terminal. This will create a Blockly application in the folder `context-menu-option-codelab`.
1. Use `cd` to move into the new directory: `cd context-menu-option-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.
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.
### Change the storage key
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 `serialization.js`, change the value of `storageKey` to some unique string. `contextMenuWorkspace` will work:
```js
// Use a unique storage key for this codelab
const storageKey = 'contextMenuWorkspace';
```
### Explore the starter code
Take a moment to explore the code you just created in the `context-menu-option-codelab` folder. If you'd like a more in-depth explanation of all of the code in the sample app, check out the [getting started codelab](/codelabs/getting-started/codelab-overview) which goes through creating this sample app from scratch.
For a briefer outline of the code, visit the [sample app overview](/guides/get-started/sample-app-overview/) page for an overview of the included files and tooling.
---
### Packages Docs Docs Codelabs Context Menu Option Summary (`packages/docs/docs/codelabs/context-menu-option/summary.mdx`)
---
pagination_next: null
description: Summary of the "Customizing context menus" codelab.
---
# Customizing context menus
## 11. Summary
In this codelab you have learned how to create and modify context menu options. You have learned about scope, preconditions, callbacks, and display text.
You can find the code for the [completed context menu codelab](https://github.com/RaspberryPiFoundation/blockly/tree/main/packages/docs/docs/codelabs/context-menu-option/complete-code) on GitHub.
### Additional information
- [Context menu documentation](/guides/configure/context-menus)
- You can also define [block context menus](/guides/configure/context-menus#customize-per-block) directly on a block definition, which is equivalent to adding a precondition based on the type of the block.
---
### Packages Docs Docs Codelabs Context Menu Option Weight And Id (`packages/docs/docs/codelabs/context-menu-option/weight-and-id.mdx`)
---
description: How to set the weight and ID of a context menu item.
---
# Customizing context menus
## 9. Weight and id
The last two properties of a registry item are `weight` and `id`.
### Weight
The `weight` property is a number that determines the order of the options in the context menu. A higher number means your option will be lower in the list.
Test this by updating the `weight` property on one of your new registry items and confirming that the corresponding option moves to the top or bottom of the list.
Note that weight does not have to be positive or integer-valued.
### Id
Every registry item has an `id` that can be used to unregister it. You can use this to get rid of registry items that you don't want.
For instance, you can remove the item that deletes all blocks on the workspace:
```js
Blockly.ContextMenuRegistry.registry.unregister('workspaceDelete');
```
### Default items
For a list of the default registry items that Blockly provides, look at [contextmenu_items.ts](https://github.com/RaspberryPiFoundation/blockly/blob/main/packages/blockly/core/contextmenu_items.ts). Each entry contains both the `id` and the `weight`.
---
### Packages Docs Docs Codelabs Css Blocks (`packages/docs/docs/codelabs/css/blocks.mdx`)
---
title: Use CSS in Blockly - Blocks
description: Styling blocks with CSS
---
import Image from '@site/src/components/Image';
# Use CSS in Blockly
## 6. Blocks
In this section, you will create CSS rules to assign the colours used by the [blocks section](/codelabs/theme-extension-identifier/customize-block-styles) of the themes codelab to the logic, loops, text, and lists blocks. This is a bit more complex than setting component or category colours and you'll do it in several steps.
### Block fill and stroke
Your first step is to set the `fill` and `stroke` of the logic blocks.
Note that setting the `fill` and `stroke` is specific to the
[renderer](/guides/create-custom-blocks/renderers/overview)
you are using. (In this codelab, you are using the Thrasos renderer.) An
important consequence of this is that you need different CSS for different
renderers.
#### Identify the block element
Drag an `if do` block onto the workspace and find it with the element inspector:
```