Block Attributes
Block attributes provide information about the data stored by a block. For example, rich content, a list of image URLs, a background color, or a button title.
A block can contain any number of attributes, and these are specified by the attributes field – an object where each key is the name of the attribute, and the value is the attribute definition.
The attribute definition will contain, at a minimum, either a type or an enum. There may be additional fields.
Type or Enum
An Attribute must have either a type or enum as outlined in the documentation here: https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#type-validation
A type would indicate the type of data stored in the attribute such as string, integer, boolean, array, and object.
An enum contains an array of allowed values such as:
[ 'large', 'small', 'tiny' ]Attribute Source
Attributes can store and source their data from a number of different places. If no source is set, the data is stored in the block’s HTML comment delimiter.
Most blocks we build will be Dynamic and use a PHP template to render on the frontend. For Dynamic blocks you must store the attribute in the HTML comment so don’t set a source.
For static blocks the source of the attribute can be the markup of the block. However this causes serious issues later if you need to convert that block from static to dynamic so it’s best to store your attribute in the HTML comment of the block. Don’t set an attribute source unless you have a very good and particular reason.
To store attributes in the markup, set the source and a selector value so that the parser can find the data in the markup. These selectors are essentially CSS selectors so you can use something as simple as img or more complex such as img.someclass, or .wp-block-some-example h2.
Attributes stored in Post Meta
Prior to WordPress 5.4 Attribute sources could be stored in postmeta. This was deprecated in favor of a new method using EntityProvider and hooks. The existing blocks that use the old method should still work for some time, but we should convert them to the new method. See: https://make.wordpress.org/core/2020/03/02/general-block-editor-api-updates/
Note: In WordPress 6.5 or so a new Block Bindings API is being added which appears to be taking this further and making more changes to how block attributes and custom fields / post meta are connected together.
Attributes vs State
It is important to note that attributes should be used for data that needs to be saved with the block. There are times when there is a need for saving the state of something in the block when it is being edited. For instance if a UI element is open in a component or if some piece of the block should be shown/hidden in the editor. These types of state changes should generally not be stored as an attribute but instead can be managed and “saved” in the editor using the useState() hook.
@todo embed https://github.com/bu-ist/labs-theme-blocks/blob/sandbox/src/blocks/theme/index.js lines 29-36
When a block is parsed this definition will be used to extract data from the block content. Anything that matches will be available to your block through the attributes prop. Example:
@todo embedhttps://github.com/bu-ist/labs-theme-blocks/blob/sandbox/src/blocks/theme/render.php line 18