Extensions
Extensions allow you to extend any registered block in your WordPress installation using a simple .json based API, which is similar to the block.json configuration. This includes core, third-party and blocks made with Blockstudio.
All field types can be added to any block, with the data being saved to the block’s attributes. The complete feature set of attributes like filtering, disabling, conditional logic and populating options are available for extensions.
Extension Types
Extended values can be utilized in versatile ways:
- class: Add a class using the attribute value to the block
- style: Add inline styles using the attribute value to the block
- attributes: Set any attribute value directly on the block
- data attributes: Use extension values to set specific data attributes
Setup
Imagine the following scenario: you want to add a custom class select field to every core block. All you need to do is add this .json file anywhere in your block folder, and it will be automatically registered as an extension.
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"priority": 10,
"blockstudio": {
"extend": true,
"attributes": [
{
"id": "customColor",
"type": "select",
"label": "Custom color",
"options": [
{
"value": "#f00",
"label": "Red"
},
{
"value": "#00f",
"label": "Blue"
}
],
"set": [
{
"attribute": "style",
"value": "color: {attributes.customColor}"
}
]
}
]
}
}
This will add a customColor field to every core block, allowing you to set the color of the block’s text.
File Name
Since there is no rendering template, an extension doesn’t need a matching index file and thus doesn’t need to be named block.json. This allows storing all extensions conveniently in a single folder. Several files may extend the same blocks, for example two files with "name": "core/*"; each registers its own fields.
Schema
Blockstudio provides a custom JSON schema for extension configurations:
Name
The name property of the configuration object defines which blocks should be extended. There are three options depending on your needs:
- blockName: A single block name, e.g.
core/paragraph - [blockNameA, blockNameB]: An array of block names, e.g.
["core/paragraph", "core/heading"] - core/*: A wildcard to extend all blocks of a certain type
Any name that ends in an asterisk is a prefix wildcard, not only core/*. The
following extension applies to every block whose name starts with my-plugin/,
including blocks made with Blockstudio:
{
"name": "my-plugin/*",
"blockstudio": {
"extend": true,
"attributes": []
}
}
Excluding Blocks
Use a top-level exclude array to skip blocks that would otherwise match name:
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"exclude": ["core/button", "core/image"],
"blockstudio": {
"extend": true,
"attributes": []
}
}
Exclusions use the same exact-name and trailing-* prefix matching as name.
They take precedence over single names, name lists, and wildcards. An excluded
block receives neither the extension’s editor fields nor its frontend attributes
or assets. Other matching extensions are unaffected. Omit exclude or use an
empty array to keep the existing behavior.
Blockstudio Key
Just like when using block.json for custom blocks, the blockstudio property has to be present in the configuration object with extend set to true.
Position
By default, extensions will render in its own tab in the block inspector. If you want to move the extensions to a different position, you can use the group property:
- settings: The default position
- styles: The styles tab
- advanced: The advanced tab
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"blockstudio": {
"extend": true,
"group": "styles",
"attributes": []
}
}
Priority
The priority property allows you to define the order in which extensions are rendered. Extensions with a higher priority will be rendered later. Set it at the top level of the file, as in the setup example, or inside extend:
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"blockstudio": {
"extend": { "priority": 10 },
"attributes": []
}
}
When both are set, blockstudio.extend.priority wins.
Attributes
For more information on how attributes work, please refer to the attributes section.
The only thing you need to know about attributes inside extensions is the set property. It is used to apply the value of the attribute to one of the extension types.
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"blockstudio": {
"extend": true,
"attributes": [
{
"id": "customColor",
"type": "select",
"label": "Heading color",
"options": [
{
"value": "#f00",
"label": "Red"
},
{
"value": "#00f",
"label": "Blue"
}
],
"set": [
{
"attribute": "style",
"value": "color: {attributes.customColor}"
}
]
}
]
}
}
Getting Values
Dot notation inside curly braces is used to get the value of an attribute.
It is also possible to get nested values when attributes are not returning a single value, for example, when setting the return format to both on field types with options.
{
"attributes": [
{
"id": "customColor",
"type": "select",
"label": "Heading color",
"options": [
{
"value": "#f00",
"label": "Red"
},
{
"value": "#00f",
"label": "Blue"
}
],
"returnFormat": "both",
"set": [
{
"attribute": "style",
"value": "color: {attributes.customColor.value}"
},
{
"attribute": "data-color",
"value": "{attributes.customColor.label}"
}
]
}
]
}
The example above will set the style attribute to color: #f00 or color: #00f and the data-color attribute to Red or Blue depending on the value.
For now, only values from the current attribute can be used inside set definitions. The ability to use values from other attributes might be added in the future.
Arrays
When using arrays, the set property will be applied to every item in the array.
Each item adds its own class or style declaration. Any other attribute holds a single value, so every item overwrites it and the last item wins. Set join to true to write the results of all items instead, separated by spaces and without empty or repeated values, so a selector like [data-langs~="en"] matches every chosen item. join has no effect on class and style, or on fields that return a single value.
{
"id": "langs",
"type": "checkbox",
"label": "Languages",
"options": [
{
"value": "en",
"label": "English"
},
{
"value": "de",
"label": "German"
}
],
"set": [
{
"attribute": "data-langs",
"value": "{attributes.langs}",
"join": true
}
]
}
Choosing both options renders data-langs="en de". Without join, it renders data-langs="de".
Attributes Field
When using the attributes field, there is no set property needed, as the field automatically maps the values to the attribute name and value.
Inspecting Extension Fields
bs_block_extension_fields('core/paragraph') returns the field definitions of
every extension that matches a block. See
Inspecting Blocks for the return
value and how it relates to bs_block_fields().