Skip to content

Latest commit

 

History

History
114 lines (77 loc) · 6.66 KB

README.md

File metadata and controls

114 lines (77 loc) · 6.66 KB
Raw

react-blockly

Built on Blockly

A React component that embeds a Blockly visual programming editor.

This is a continuation of PatientsLikeMe's react-blockly-component project. This new version utilizes Google's official Blockly npm packages in addition to other modernizations.

Features:

  • Supports an xmlDidChange prop so other components can easily consume the XML generated by the editor
  • Generates the toolbox XML from a toolboxCategories or toolboxBlocks prop, and automatically notifies Blockly when it's been updated

Example usage

FernandoVazZ has made an example React app that shows how to set up react-blockly as well as how to create custom blocks for use in it: https://github.com/FernandoVazZ/reactblockly-customblocks/

Thanks so much Fernando!

Help wanted!

I wrote react-blockly for an internal tool when I worked at PatientsLikeMe, Inc. I no longer maintain this tool, and I don't even have access to it anymore. I also don't have any actual project that uses react-blockly anymore.

I'd love to find maintainers for this package who actually use it. In particular, some things I would love to have help with are:

  • A test suite
  • Switching over to the newer JSON-based toolbox format that Blockly now supports
  • Seeing if we can remove immutable.js as a dependency
  • Modernizing the components, potentially moving away from class components and towards publicly-exposed hooks and function components
  • TypeScript typings

If you are interested in working on any of those things, please let me know! Additionally, if you're interested in taking over maintainership of this package entirely, I'd be happy to talk to you about that.

Installation

To add react-blockly to a React app that uses npm, run:

npm install --save react-blockly

To add react-blockly to a React app that uses yarn, run:

yarn add react-blockly

How to use

write import ReactBlockly from 'react-blockly'; in your code and use ReactBlockly as a component.

You could also import one of these component:

BlocklyEditor,
BlocklyToolbox,
BlocklyToolboxBlock,
BlocklyToolboxCategory,
BlocklyWorkspace

using import { BlocklyToolbox } from 'react-blockly'(or another component name)

Developer setup for working on this package

Clone this repository, and then inside it, do:

yarn install
yarn run start

webpack-dev-server will start and will be serving a demo of react-blockly, which should automatically refresh if you change the code locally.

Properties

All properties are optional except where otherwise specified.

  • initialXml: The XML of the program to initially load in the editor.
  • workspaceConfiguration: Any configuration options to be passed into Blockly.inject (except for toolbox, which is handled automatically).
  • wrapperDivClassName: The value for the class attribute to be used on the <div> elements generated by this component. Typically you'll need to use this to set the height of the Blockly editor, using either an explicit height style, flexboxes, or some other means.
  • toolboxCategories: An array of categories for the toolbox. Each category is an object including the following properties:
    • name: The display name of this category.
    • custom: The value for the custom attribute of this category (can be either "VARIABLE" or "PROCEDURE").
    • categories: An array of subcategories, each of which follows the same format as this object.
    • blocks: An array of blocks to appear in the category. Each block is an object including the following properties:
      • type (required): The Blockly type name for the block (such as "controls_if" or "logic_compare").
      • colour: If present, gives a custom colour value for the block.
      • shadow: True if this is a shadow block; false or undefined otherwise.
      • fields: An object mapping from field names to pre-set values for those fields.
      • values: An object mapping from value input names to pre-set connected blocks for those value inputs. Each block is an object following the same format as this one.
      • statements: An object mapping from statement input names to pre-set connected blocks for those statement inputs. Each block is an object following the same format as this one.
      • next: The next block connected to this one, which is an object following the same format as this one.
      • mutation: An object specifying the content of the <mutation> tag for this block, with the following properties:
        • attributes: An object mapping from attribute names to values for those attributes.
        • innerContent: The XML content of the <mutation> tag in string format.
  • toolboxBlocks: An array of top-level blocks for the toolbox. Each block is an object following the format of the objects in the toolboxCategories blocks array (specified above). If this property is defined, toolboxCategories should not be defined, since Blockly's toolbox can either contain blocks or categories, but not both.
  • workspaceDidChange: A callback function that will be fired for every workspace event. Take a look at https://developers.google.com/blockly/guides/configure/web/events for a full list of events. For example you can handle your clientside code generation in this function. The new workspace object will be passed as an argument to the function.
  • processToolboxCategory: A callback function that can be used to pre-process the content of a toolbox category. This function is passed a single object (an Immutable.js Map) from the toolboxCategories array and is expected to return an object of the same format. This is useful if another React component is embedding BlocklyEditor and wants to add dynamic content to the toolbox.

Example usage

See public/index.html and src/dev-index.jsx for a fairly full-fledged demo that shows off most of the features of this component.

Contributing

We accept pull requests and issues! You can file an issue on this project, or fork, modify, and file a pull request.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Licensing

react-blockly is Copyright © 2019 Nat Budin. Distributed under the terms and conditions of the MIT License.

react-blockly is based on react-blockly-component, which is Copyright © 2015 PatientsLikeMe, Inc. Distributed under the terms and conditions of the MIT License.