@@ -14,6 +14,7 @@ import CompareBlock from '@site/src/components/CompareBlock';
1414 />
1515</Head >
1616
17+
1718# Publish block libraries
1819
1920Plugins that provide libraries of block definitions are a great way to share
@@ -22,27 +23,28 @@ versatile and useful as possible, we've developed these guidelines.
2223
2324## Guidelines
2425
25- - Make it ** easy** for users to install all of your blocks, and make it
26- ** possible** for users to install only certain blocks or pieces of blocks
27- they choose.
28- - Make it easy to install everything: You can do this by providing a
29- function that installs every piece a single block definition requires
30- (such as mutators, extensions, mixins, fields, etc.). You can also
31- provide a function that will install all of the blocks offered by your
32- plugin at once.
33- - Make it possible to choose specific parts: You should export all of the
34- pieces of a block definition separately, so that it is possible for a
35- user to import only the pieces they need in order to create their own
36- similar custom block.
37- - Avoid using side effects in your plugin.
38- - Blocks, fields, extensions, and other pieces shouldn't be installed as a
39- side effect of loading your plugin. Users should maintain control over
40- which things are installed and when. This allows users to import the
41- pieces they need without worrying that pieces they don't will be
42- installed.
43- - Use the JSON field registry instead of instantiating new fields directly.
44- - <CompareBlock variant = " worse" >
45- Not Recommended - Instantiating a new field directly:
26+ - Make it ** easy** for users to install all of your blocks, and make it
27+ ** possible** for users to install only certain blocks or pieces of blocks
28+ they choose.
29+ - Make it easy to install everything: You can do this by providing a
30+ function that installs every piece a single block definition requires
31+ (such as mutators, extensions, mixins, fields, etc.). You can also
32+ provide a function that will install all of the blocks offered by your
33+ plugin at once.
34+ - Make it possible to choose specific parts: You should export all of the
35+ pieces of a block definition separately, so that it is possible for a
36+ user to import only the pieces they need in order to create their own
37+ similar custom block.
38+ - Avoid using side effects in your plugin.
39+ - Blocks, fields, extensions, and other pieces shouldn't be installed as a
40+ side effect of loading your plugin. Users should maintain control over
41+ which things are installed and when. This allows users to import the
42+ pieces they need without worrying that pieces they don't will be
43+ installed.
44+ - Use the JSON field registry instead of instantiating new fields directly.
45+
46+ - <CompareBlock variant = " worse" >
47+ Not Recommended - Instantiating a new field directly:
4648
4749 ``` js
4850 const myCustomBlock = {
@@ -52,11 +54,10 @@ Not Recommended - Instantiating a new field directly:
5254 }
5355 }
5456 ```
57+ </CompareBlock >
5558
56- </CompareBlock >
57-
58- - <CompareBlock variant = " better" >
59- Recommended - JSON field registry:
59+ - <CompareBlock variant = " better" >
60+ Recommended - JSON field registry:
6061
6162 ``` js
6263 export const myCustomBlock = {
@@ -69,36 +70,34 @@ Recommended - JSON field registry:
6970 }
7071 }
7172 ```
73+ </CompareBlock >
7274
73- </CompareBlock >
74-
75- - Using the field registry makes it easier for a user to replace the
76- implementation of the field used in your block without having to change
75+ - Using the field registry makes it easier for a user to replace the
76+ implementation of the field used in your block without having to change
7777 the block definition.
78-
79- - Don't make assumptions about what the user has already installed.
80- - If your plugin requires a custom field or another plugin, register those
78+ - Don't make assumptions about what the user has already installed.
79+ - If your plugin requires a custom field or another plugin, register those
8180 fields yourself in your provided ` install ` function.
82- - Soon, Blockly will provide tools that let you register
83- already-registered items without error. Until then, you may want to
84- check what has already been registered before registering an extension,
81+ - Soon, Blockly will provide tools that let you register
82+ already-registered items without error. Until then, you may want to
83+ check what has already been registered before registering an extension,
8584 mutator, mixin, or field yourself.
86- - Be clear about any prerequisites or dependencies that are required by
87- your plugin or block definitions.
88- - Consider providing generator functions for each of the blocks you provide.
89- - Providing generator functions that work out of the box makes it easier
90- for users to use your blocks without having to understand their
91- structure and design. If they have to write their own generator
92- functions, this may lead to redundant work being done by each user.
93- - JavaScript is the most commonly used language in Blockly, so if you only
85+ - Be clear about any prerequisites or dependencies that are required by
86+ your plugin or block definitions.
87+ - Consider providing generator functions for each of the blocks you provide.
88+ - Providing generator functions that work out of the box makes it easier
89+ for users to use your blocks without having to understand their
90+ structure and design. If they have to write their own generator
91+ functions, this may lead to redundant work being done by each user.
92+ - JavaScript is the most commonly used language in Blockly, so if you only
9493 pick one language to provide, we recommend JavaScript, unless your blocks
95- are built for a specific language such as implementing a Python library.
96- - Consider posting 'help wanted' issues for languages for which you are
97- unable to implement generator functions, and accept pull requests for
98- these if a user contributes them.
99- - If you provide an install function for your block, you can accept an
100- optional ` generators ` parameter. If a user passes a generator instance
101- that you support, you can automatically install the block-code generator
94+ are built for a specific language such as implementing a Python library.
95+ - Consider posting 'help wanted' issues for languages for which you are
96+ unable to implement generator functions, and accept pull requests for
97+ these if a user contributes them.
98+ - If you provide an install function for your block, you can accept an
99+ optional ` generators ` parameter. If a user passes a generator instance
100+ that you support, you can automatically install the block-code generator
102101 function and do related work such as adding reserved words:
103102
104103 ``` js
0 commit comments