-
Notifications
You must be signed in to change notification settings - Fork 622
Using Blockly APIs in Plugins
- 🐙 review requested for both content and writing.
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.
Anything marked public is part of our public API. We try to not change our public API frequently or without good reason and warning.
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.
Protected functions and properties may be used or overridden by subclasses of the class on which the property is defined.
For instance, a custom renderer that extends the base renderer class may access its protected properties.
These can only be accessed by code in the same file as the definition. Directly accessing these properties may result in undefined behaviour.
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.
Anything marked @deprecated should not be used. Most deprecations include directions on the preferred code.
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.
Yes, although you should make sure you understand how they are used in the rest of the code.
Ask a question on the forum and we'll get back to you, generally within a business day.