Dynamic categories
Stay organized with collections
Save and categorize content based on your preferences.
Dynamic categories are categories that are dynamically repopulated based on a
function each time they are opened.
Blockly supports this by allowing you to associate a category with a function
via a registered string key. The function should return a definition of a
category's contents (including blocks, buttons, labels, etc). The contents can
be specified as JSON or XML, although JSON is recommended.
Also note that the function is provided the target workspace as a parameter, so
the blocks in your dynamic category can be based on the state of the workspace.
JSON
// Returns an array of objects.
var coloursFlyoutCallback = function(workspace) {
// Returns an array of hex colours, e.g. ['#4286f4', '#ef0447']
var colourList = getPalette();
var blockList = [];
for (var i = 0; i < colourList.length; i++) {
blockList.push({
'kind': 'block',
'type': 'colour_picker',
'fields': {
'COLOUR': colourList[i]
}
});
}
return blockList;
};
// Associates the function with the string 'COLOUR_PALETTE'
myWorkspace.registerToolboxCategoryCallback(
'COLOUR_PALETTE', coloursFlyoutCallback);
XML
// Returns an arry of XML nodes.
var coloursFlyoutCallback = function(workspace) {
// Returns an array of hex colours, e.g. ['#4286f4', '#ef0447']
var colourList = getPalette();
var blockList = [];
for (var i = 0; i < colourList.length; i++) {
var block = document.createElement('block');
block.setAttribute('type', 'colour_picker');
var field = document.createElement('field');
field.setAttribute('name', 'COLOUR');
field.innerText = colourList[i];
block.appendChild(field);
blockList.push(block);
}
return blockList;
};
// Associates the function with the string 'COLOUR_PALETTE'
myWorkspace.registerToolboxCategoryCallback(
'COLOUR_PALETTE', coloursFlyoutCallback);
After the dynamic category functions are associated with a string key (aka
registered) you can assign this string key to the custom
property of
your category definition to make the category dynamic.
JSON
{
"kind": "category",
"name": "Colours",
"custom": "COLOUR_PALETTE"
}
XML
<category name="Colours" custom="COLOUR_PALETTE"></category>
Built-in dynamic categories
Blockly provides three built-in dynamic categories.
JSON
{
"kind": "category",
"name": "Variables",
"custom": "VARIABLE"
},
{
"kind": "category",
"name": "Variables",
"custom": "VARIABLE_DYNAMIC"
},
{
"kind": "category",
"name": "Functions",
"custom": "PROCEDURE"
}
XML
<category name="Variables" custom="VARIABLE"></category>
<category name="Variables" custom="VARIABLE_DYNAMIC"></category>
<category name="Functions" custom="PROCEDURE"></category>
Note: The word 'procedure' is used throughout the Blockly codebase, but the
word 'function' has found to be more understandable by students.
Sorry for the mismatch.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-03-20 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-03-20 UTC."],[],[],null,["# Dynamic categories are categories that are dynamically repopulated based on a\nfunction each time they are opened.\n\nBlockly supports this by allowing you to associate a category with a function\nvia a registered string key. The function should return a definition of a\ncategory's contents (including blocks, buttons, labels, etc). The contents can\nbe specified as JSON or XML, although JSON is recommended.\n\nAlso note that the function is provided the target workspace as a parameter, so\nthe blocks in your dynamic category can be based on the state of the workspace. \n\n### JSON\n\n // Returns an array of objects.\n var coloursFlyoutCallback = function(workspace) {\n // Returns an array of hex colours, e.g. ['#4286f4', '#ef0447']\n var colourList = getPalette();\n var blockList = [];\n for (var i = 0; i \u003c colourList.length; i++) {\n blockList.push({\n 'kind': 'block',\n 'type': 'colour_picker',\n 'fields': {\n 'COLOUR': colourList[i]\n }\n });\n }\n return blockList;\n };\n\n // Associates the function with the string 'COLOUR_PALETTE'\n myWorkspace.registerToolboxCategoryCallback(\n 'COLOUR_PALETTE', coloursFlyoutCallback);\n\n### XML\n\n // Returns an arry of XML nodes.\n var coloursFlyoutCallback = function(workspace) {\n // Returns an array of hex colours, e.g. ['#4286f4', '#ef0447']\n var colourList = getPalette();\n var blockList = [];\n for (var i = 0; i \u003c colourList.length; i++) {\n var block = document.createElement('block');\n block.setAttribute('type', 'colour_picker');\n var field = document.createElement('field');\n field.setAttribute('name', 'COLOUR');\n field.innerText = colourList[i];\n block.appendChild(field);\n blockList.push(block);\n }\n return blockList;\n };\n\n // Associates the function with the string 'COLOUR_PALETTE'\n myWorkspace.registerToolboxCategoryCallback(\n 'COLOUR_PALETTE', coloursFlyoutCallback);\n\nAfter the dynamic category functions are associated with a string key (aka\nregistered) you can assign this string key to the `custom` property of\nyour category definition to make the category dynamic. \n\n### JSON\n\n {\n \"kind\": \"category\",\n \"name\": \"Colours\",\n \"custom\": \"COLOUR_PALETTE\"\n }\n\n### XML\n\n \u003ccategory name=\"Colours\" custom=\"COLOUR_PALETTE\"\u003e\u003c/category\u003e\n\nBuilt-in dynamic categories\n---------------------------\n\nBlockly provides three built-in dynamic categories.\n\n- `'VARIABLE'` creates a category for [*untyped* variables](/blockly/guides/create-custom-blocks/variables#untyped_variable_blocks).\n- `'VARIABLE_DYNAMIC'` creates a category for [*typed* variables](/blockly/guides/create-custom-blocks/variables#typed_variable_blocks). It has buttons to create strings, numbers, and colours.\n- `'PROCEDURE'` creates a category for function blocks.\n\n### JSON\n\n {\n \"kind\": \"category\",\n \"name\": \"Variables\",\n \"custom\": \"VARIABLE\"\n },\n {\n \"kind\": \"category\",\n \"name\": \"Variables\",\n \"custom\": \"VARIABLE_DYNAMIC\"\n },\n {\n \"kind\": \"category\",\n \"name\": \"Functions\",\n \"custom\": \"PROCEDURE\"\n }\n\n### XML\n\n \u003ccategory name=\"Variables\" custom=\"VARIABLE\"\u003e\u003c/category\u003e\n \u003ccategory name=\"Variables\" custom=\"VARIABLE_DYNAMIC\"\u003e\u003c/category\u003e\n \u003ccategory name=\"Functions\" custom=\"PROCEDURE\"\u003e\u003c/category\u003e\n\n*Note: The word 'procedure' is used throughout the Blockly codebase, but the\nword 'function' has found to be more understandable by students.\nSorry for the mismatch.*"]]