-
Notifications
You must be signed in to change notification settings - Fork 662
Using Blockly APIs in Plugins
This page describes best practices for calling functions and accessing properties in core Blockly.
We use Closure compiler annotations to mark visibility in the core library as public, package, protected, private, or deprecated.
All public, package, and protected members are documented in the References section of the Blockly website. You can also check visibility by reading the comments in the code.
⭐ While JavaScript does not enforce these visibility annotations, you should avoid accessing anything that is not public. The Blockly team does not guarantee stability of non-public properties and functions between releases.
Blockly has multiple paradigms for adding functionality, including:
- Subclasses (e.g. creating a new renderer)
- Mixins (e.g. adding a block extension or mutator)
- Block definitions (e.g. procedure block definitions)
For the purposes of this document, all three cases are equivalent to subclassing.
Anything marked public is part of our public API.
We try to not change our public API frequently or without good reason and warning. The exception: we may make an API public in the Q1 release and modify it in the Q2 release in response to early feedback. After that you may consider a public function or property stable.
Public functions may be called from anywhere, and overridden in subclasses as long as the signature does not change.
Package functions and properties are intended to be used within the core library, but not externally. We do not guarantee stability of anything marked @package. This means that the type, meaning, name, or function signature of anything marked @package may change without warning.
Package functions may be called from anywhere, and overridden in subclasses as long as the signature does not change.
Protected functions and properties may only be accessed by the defining class or a subclass.
Subclasses are allowed to override protected functions and properties, without changing type signatures.
For instance, a custom renderer that extends the base renderer class may access its protected properties.
In each case you should make sure you understand how the function or property is used in the rest of the code.
These can only be accessed by code in the same file as the definition. Directly accessing these properties may result in undefined behaviour.
Subclasses are not allowed to override private functions and properties.
Blockly uses an underscore_ at the end of private properties and functions.
⭐ In rare cases private functions were used so widely that they became public, but without name changes. For example, Blockly.bindEventWithChecks_ is public.
Anything marked @deprecated should not be used. Most deprecations include directions on the preferred code, either in a console warning or JSDoc.
File a feature request on core Blockly. Include a description of your use case and a statement of what you would like us to make public.
We will use the feature to request to discuss whether to make it public, or whether there are other ways for you to get the same information.
If we decide to make it public, either you or the Blockly team will make the appropriate change, and it will go live in the next quarterly Blockly release.
If you choose to use a non-public member in your plugin, consider marking your plugin as a beta and include the information in your README.
➡️ Read up on monkeypatching.
Monkeypatching in a published plugin is unsafe, because your code may interact poorly with any other plugin that monkeypatches the same code. For this reason we strongly recommend against monkeypatching in third party plugins, and will not accept it in first party plugins.
When subclassing: yes. Otherwise: no, that's monkeypatching.
When subclassing: yes. Otherwise: no, that's monkeypatching.
If we publish a getter or a setter, please use that instead of directly accessing the property. If the property is not public, definitely use getters and setters.
⭐ Consistent usage of getters and setters in plugins gives us flexibility to make changes in core Blockly without breaking published code.
By default it's public, but please drop us a line in case we want to put a getter/setter pair in place for you.
It's public by default.
Ask a question on the forum and we'll get back to you, generally within a business day.