Skip to content
This repository was archived by the owner on Jan 27, 2026. It is now read-only.

Update README.md #327

Merged
mikeharv merged 2 commits into from
Jan 27, 2026
Merged

Update README.md #327

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
eea0523
Update README.md
mikeharv Jan 26, 2026
45f8024
fix typo
mikeharv Jan 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
135 changes: 42 additions & 93 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,93 +1,42 @@
# Blockly (Code Studio fork)

[![npm version](https://img.shields.io/npm/v/@code-dot-org/blockly.svg)](https://www.npmjs.com/package/@code-dot-org/blockly)
[![CircleCI](https://circleci.com/gh/code-dot-org/blockly.svg?style=shield)](https://circleci.com/gh/code-dot-org/blockly)

This is a fork of [Blockly](https://code.google.com/p/blockly/), an open source visual programming environment.

Major additions and changes in this fork:

* Modal editor for function blocks ([function_editor.js](./core/ui/function_editor.js))
* Scrolling improvements:
* auto-scroll on block drag ([scroll_on_block_drag_handler.js](./core/ui/block_space/scroll_on_block_drag_handler.js))
* scroll on mouse wheel ([scroll_on_wheel_handler.js](./core/ui/block_space/scroll_on_wheel_handler.js))
* New in-toolbox trashcan
* Addition of "Functional blocks" and "Contract/Variable Editor" ([contract_editor/](./core/ui/contract_editor/)) for use in the CS in Algebra curriculum
* Blocks have "Block Value Types" ([block_value_type.js](./core/utils/block_value_type.js))
* Support for "block limits" ([block_limits.js](./core/ui/block_space/block_limits.js)), toolbox blocks which allow only a certain number of instances in the block space
* Support for new block properties ([block.js](./core/ui/block.js)): invisible, un-deletable, immovable, specify-able via a context menu when `Blockly.editBlocks` is set
* Structure: add folders in [core/](./core) to further categorize classes
* New field types:
* Image Dropdown ([field_image_dropdown.js](./core/ui/fields/field_image_dropdown.js))
* BlockSpace (Workspace) Refactoring:
* moved many static properties and methods from `blockly.js` into a prototype class `BlockSpaceEditor` which can be instantiated multiple times on the same page
* renamed `Workspace` to `BlockSpace` to disambiguate from higher-level `BlockSpaceEditor`
* improved support for multiple blockspaces on a single page
* Playground: add dependency cache and generation script ([tests/update_test_dependencies.sh](./tests/update_test_dependencies.sh)), to allow for testing changes without re-building
* support for [goog.ui.tweak](https://google.github.io/closure-library/source/closure/goog/demos/tweakui.html)s to configure playground page behavior
* debug drawing helpers for block bumping
* Support for a special UI for unattached blocks
* Improvements to block arrangement on initialization
* Testing: add phantomjs-based test runner [test.sh](./test.sh). Tested in CI at root level of this repository.

## Installation

1. Download and install JDK version 8 from [here](https://www.oracle.com/technetwork/es/java/javase/downloads/jdk8-downloads-2133151.html)
2. run the following commands:

```
cd blockly
npm install
npm run build
```

## Usage

### Playground manual testing page

There is a playground manual testing page at [tests/playground.html](./tests/playground.html), which requires no build step or server running.

`open tests/playground.html`

### Building with apps

This is the most typical use case for code-dot-org fork development.

[Apps (aka Code Studio)](https://github.com/code-dot-org/code-dot-org/tree/staging/apps) is a set of blockly apps built on top of blockly, which installs and references this package via NPM. The easiest pathway for local development is to use [npm-link](https://docs.npmjs.com/cli/link):

```
cd {blockly repo directory}
npm link
cd {code-dot-org repo directory}/apps
npm link @code-dot-org/blockly
```

Apps will now reference your local blockly repository rather than the npm package. If you then make local changes to your repo, you can simply rebuild blockly (via `npm run build` in this repo) and then apps (via `npm run build` in code-dot-org/apps) to communicate those changes to apps.

### Publishing changes

To publish a new version to npm switch to the main branch, use `npm login` to sign in as an account with access to the `@code-dot-org` scope, then `npm version [major|minor|patch|premajor|preminor|prepatch]` for the appropriate version bump. This will do the following:

* Run linting and tests to verify your local repo.
* Rebuild the release package.
* Bump the version, adding a corresponding commit and version tag.
* Push the commit and tag to github.
* Publish the new release package to npm.

#### Testing changes

There are a set of utility and integration tests included in `tests/blockly_test.html`, and a playground manual testing page at `tests/playground.html`.

After adding any new files, you will need to run `./update_test_dependencies.sh` to update the test dependency map, which caches file dependencies so edits can be tested and played with without any re-build time.

There are three ways the test suites can be run:

1. `./test.sh` will run the tests in phantomjs
1. To debug failures, you can open the test page in your browser, e.g. `open tests/blockly_test.html`
1. `./deploy.sh` will also run `./test.sh` at the end of its full rebuild.

##### Other tests covering this package

[Blockly apps](https://github.com/code-dot-org/code-dot-org/tree/staging/apps) contains many tests that target features of blockly in the context of the code.org curriculum apps.

Additionally, [Dashboard's UI tests](https://github.com/code-dot-org/code-dot-org/tree/staging/dashboard/test/ui) cover certain features of blockly through Cucumber / Selenium scenarios.
# Blockly (Code Studio fork) - Archived

This repository historically contained Code.org’s fork of [Blockly](https://blockly.com/), the open-source visual programming environment. The fork existed to support custom features for
Code.org-specific curriculum that were not yet available with mainline Blockly or its plugins.

## Archival note

Code.org has fully migrated to mainline Blockly, and this fork is no longer used or published. This repository is archived to preserve historical reference only. It is not maintained, tested, or supported.

## Major additions and changes in this fork

- Modal editor for function blocks ([function_editor.js](./core/ui/function_editor.js))
- Scrolling improvements:
- auto-scroll on block drag ([scroll_on_block_drag_handler.js](./core/ui/block_space/scroll_on_block_drag_handler.js))
- scroll on mouse wheel ([scroll_on_wheel_handler.js](./core/ui/block_space/scroll_on_wheel_handler.js))
- New in-toolbox trashcan
- Addition of "Functional blocks" and "Contract/Variable Editor" ([contract_editor/](./core/ui/contract_editor/)) for use in the CS in Algebra curriculum
- Blocks have "Block Value Types" ([block_value_type.js](./core/utils/block_value_type.js))
- Support for "block limits" ([block_limits.js](./core/ui/block_space/block_limits.js)), toolbox blocks which allow only a certain number of instances in the block space
- Support for new block properties ([block.js](./core/ui/block.js)): invisible, un-deletable, immovable, specify-able via a context menu when `Blockly.editBlocks` is set
- Structure: add folders in [core/](./core) to further categorize classes
- New field types:
- Image Dropdown ([field_image_dropdown.js](./core/ui/fields/field_image_dropdown.js))
- BlockSpace (Workspace) Refactoring:
- moved many static properties and methods from `blockly.js` into a prototype class `BlockSpaceEditor` which can be instantiated multiple times on the same page
- renamed `Workspace` to `BlockSpace` to disambiguate from higher-level `BlockSpaceEditor`
- improved support for multiple blockspaces on a single page
- Playground: add dependency cache and generation script ([tests/update_test_dependencies.sh](./tests/update_test_dependencies.sh)), to allow for testing changes without re-building
- support for [goog.ui.tweak](https://google.github.io/closure-library/source/closure/goog/demos/tweakui.html)s to configure playground page behavior
- debug drawing helpers for block bumping
- Support for a special UI for unattached blocks
- Improvements to block arrangement on initialization
- Testing: add phantomjs-based test runner [test.sh](./test.sh). Tested in CI at root level of this repository.

## Current Blockly usage at Code.org

Code.org no longer uses this repository. Any active development related to Blockly at Code.org should happen against upstream Blockly or within the Code.org repository itself.

## npm package status

The `@code-dot-org/blockly` npm package is no longer published or updated.
Do not depend on it for new projects.