Using Blockly APIs in Plugins

⁉️ Needs Review ⁉️

• 🐙 review requested for both content and writing.

• ❕ Looks really good! It felt nice seeing all of these guidelines put into writing. Also, that monkey patching section? Great!

• ❕ Here are some questions I had while reading this. I'm not sure which ones need to be addressed, and which ones can be left, so I'm just going to give you all of 'em :P

  • ❕ Can I override public functions?
  • ❕ Can I override package functions? (I think the conclusion was no, but it might be good to note)
  • ❕ What is an example of a function w/ an underscore that became public?

• ❔ If you can override public functions (not sure on that one) would it be worth it to give each annotation a separate "calling" and "overriding" section? I'm too tired to determine whether that would be overkill or not hehe

• ❔ How do you guys feel about protected properties that have public getters/setters? For example field validator. Should plugin devs prioritize using the getters/setters? Or does it not really matter?

• ❕ It might also be nice to include a note about functions that don't have annotations (default public) in case people run into them.

• ❕ Oh and on that note! Maybe a link to core blockly as well? https://github.com/google/blockly/tree/master/core Although that might overwhelm people haha

• ❕ Again, I really like this, the FAQ was a great idea. This wiki is starting to look sweet!

• 🐬 lgtm, not sure if it is worth it to mention/link to where people can find information on preferred usage for deprecated code.

---

Introduction

This page describes best practices for calling functions and accessing properties in core Blockly.

Visibility

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.

The annotations

public

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

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

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.

private

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.

deprecated

Anything marked @deprecated should not be used. Most deprecations include directions on the preferred code.

FAQs

What if the function I want to use isn't public?

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.

What about monkeypatching?

➡️ 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.

Can I override protected properties?

Yes, although you should make sure you understand how they are used in the rest of the code.

What if I'm still not sure?

Ask a question on the forum and we'll get back to you, generally within a business day.