Bad Blocks How to create virtually unusable Blocks
Every application which uses Blockly defines a language. Sometimes the language is small.
Sometimes the language is large enough to use categories.
But what happens when the API one wants Blockly to control is exceptionally large? The Google Apps
Script API is a good example. We've got hundreds of functions. That means hundreds of blocks.
Creating each block manually would be a huge waste of time.
A smarter approach would be to write a script to convert the existing API documentation into
JSON block definitions. In a few seconds one has generated hundreds of blocks, and the job's done.
Don't do this. Automated block construction is a disaster for five reasons.
1. Too many blocks
First, having too many blocks makes it hard for users to find the blocks they need.
Categories aren't enough, and the toolbox starts spouting sub-categories.
When a developer asks the Blockly team for better toolbox search capabilities,
that's usually a sign that their blocks are out of control.
Now, for some projects having a large number of blocks is in and of itself not a problem. I think
Blockly@rduino is a good example of this since they are supporting a bunch of isolated libraries.
2. Inflexible blocks
Second, take a look at this example. Here's a bunch of blocks that access list elements.
With a bit of thought, all these blocks (and more) could be combined using a couple of dropdowns.
The two dropdowns on this block offer fifteen different functions --
and thus it replaces what could have been fifteen separate blocks. In this case the
dropdowns have dynamic actions, reshaping the block to add or remove inputs as needed.
3. Low-level blocks
In App Script this is the chaining sequence to get the values in a spreadsheet.
SpreadsheetApp.getActiveSheet().getDataRange().getValues()
A straight conversion of the API to blocks would mean the user needs to chain together
four blocks. Blockly generally works better as a higher-level language. In this case
one should just have a single block that gets the values.
4. Poor input UI
APIs often don't provide enough information to create good user inputs.
For example, every input in this category
is a text input. There's just isn't the detail in the API to generate anything else.
Wouldn't it be better if "anchor units" had a dropdown input with pixel, point, percent, and so
on? Wouldn't it be better if "anchor offset" had a numeric input? Wouldn't it be better if "bold"
had a checkmark input? Wouldn't it be better if "font color" had a colour picker input?
Taking a step further back, wouldn't it be better if all the font-related blocks
were replaced with a single block that had a comprehensive font-picker input?
5. Obsolescence
One of the great things about auto-generating blocks from an API is that as the API changes,
so do the blocks. All you have to do is re-run the script. This results in lower maintenance costs.
However it also breaks existing user code.
If a block disappears, or changes in a way that's not backwards compatible, users won't
be able to load their saved programs. In a conventional text-based language a changed API
just means the user needs to edit their code. But in the case of Blockly, the whole program is lost.
This is one reason why one should not auto-generate blocks,
then plan to update them later. Once a block is published it must remain forever
available to the application (although it can be omitted from the toolbox).
Conclusion
If your application has too many blocks to curate manually,
then it has too many blocks for your users to use.
Spend time thinking carefully about your blocks. Don't transfer your pain onto your users.