Open your browser's dev tools and try running
wp.data.select('core/editor').getBlocks() in the console when editing a post or when using the Site Editor. This command will return all available blocks.
diff --git a/docs/how-to-guides/feature-flags.md b/docs/how-to-guides/feature-flags.md
index 11c5ae881337dd..04fc6c08d98249 100644
--- a/docs/how-to-guides/feature-flags.md
+++ b/docs/how-to-guides/feature-flags.md
@@ -54,7 +54,7 @@ if ( globalThis.IS_GUTENBERG_PLUGIN ) {
```js
if ( true ) {
- // Wepack has replaced `globalThis.IS_GUTENBERG_PLUGIN` with `true`
+ // Webpack has replaced `globalThis.IS_GUTENBERG_PLUGIN` with `true`
pluginOnlyFeature();
}
```
diff --git a/docs/how-to-guides/plugin-sidebar-0.md b/docs/how-to-guides/plugin-sidebar-0.md
index 76ef54bb9d3082..495aa0a1d6b8bd 100644
--- a/docs/how-to-guides/plugin-sidebar-0.md
+++ b/docs/how-to-guides/plugin-sidebar-0.md
@@ -42,7 +42,7 @@ Add the following code to a JavaScript file called `plugin-sidebar.js` and save
} )( window.wp, window.React );
```
-For this code to work, those utilities need to be available in the browser, so you must specify `wp-plugins`, `wp-edit-post`, and `react` as dependencies of your script.
+For this code to work, those utilities need to be available in the browser, so you must specify `wp-plugins`, `wp-editor`, and `react` as dependencies of your script.
Here is the PHP code to register your script and specify the dependencies:
diff --git a/docs/how-to-guides/themes/global-settings-and-styles.md b/docs/how-to-guides/themes/global-settings-and-styles.md
index 205a3ee862ce6b..e0b7653321413d 100644
--- a/docs/how-to-guides/themes/global-settings-and-styles.md
+++ b/docs/how-to-guides/themes/global-settings-and-styles.md
@@ -111,7 +111,7 @@ body {
## Specification
-This specification is the same for the three different origins that use this format: core, themes, and users. Themes can override core's defaults by creating a file called `theme.json`. Users, via the site editor, will also be able to override theme's or core's preferences via an user interface that is being worked on.
+This specification is the same for the three different origins that use this format: core, themes, and users. Themes can override core's defaults by creating a file called `theme.json`. Users, via the site editor, will also be able to override theme's or core's preferences via a user interface that is being worked on.
```json
{
@@ -1034,7 +1034,7 @@ h3 {
{% end %}
##### Element pseudo selectors
-Pseudo selectors `:hover`, `:focus`, `:visited`, `:active`, `:link`, `:any-link` are supported by Gutenberg.
+Pseudo selectors `:hover`, `:focus`, `:focus-visible`, `:visited`, `:active`, `:link`, `:any-link` are supported by Gutenberg.
```json
"elements": {
diff --git a/docs/reference-guides/block-api/block-registration.md b/docs/reference-guides/block-api/block-registration.md
index 92be19ee48c9fa..a2f9fac64f6165 100644
--- a/docs/reference-guides/block-api/block-registration.md
+++ b/docs/reference-guides/block-api/block-registration.md
@@ -312,10 +312,6 @@ The key is the name of the block (`string`) to hook into, and the value is the p
}
```
-It’s crucial to emphasize that the Block Hooks feature is only designed to work with _static_ block-based templates, template parts, and patterns. For patterns, this includes those provided by the theme, from [Block Pattern Directory](https://wordpress.org/patterns/), or from calls to [`register_block_pattern`](https://developer.wordpress.org/reference/functions/register_block_pattern/).
-
-Block Hooks will not work with post content or patterns crafted by the user, such as synced patterns, or theme templates and template parts that have been modified by the user.
-
## Block collections
## `registerBlockCollection`
diff --git a/docs/reference-guides/block-api/block-variations.md b/docs/reference-guides/block-api/block-variations.md
index 8a0c6b1dd5bd6c..8c223e54eea299 100644
--- a/docs/reference-guides/block-api/block-variations.md
+++ b/docs/reference-guides/block-api/block-variations.md
@@ -60,6 +60,44 @@ wp.blocks.registerBlockVariation( 'core/embed', {
} );
```
+## Registering block variations in PHP
+
+Block variations can also be registered from PHP using the `get_block_type_variations` filter hook. This approach is particularly useful when you need to dynamically generate variations based on registered post types, taxonomies, or other WordPress data.
+
+Here's an example of how to register a custom variation for the `core/image` block:
+
+```php
+function my_custom_image_variation( $variations, $block_type ) {
+ // Only modify variations for the image block
+ if ( 'core/image' !== $block_type->name ) {
+ return $variations;
+ }
+
+ // Add a custom variation
+ $variations[] = array(
+ 'name' => 'wide-image',
+ 'title' => __( 'Wide image', 'textdomain' ),
+ 'description' => __( 'A wide image', 'textdomain' ),
+ 'scope' => array( 'inserter' ),
+ 'isDefault' => false,
+ 'attributes' => array(
+ 'align' => 'wide', // Identifies the link type as custom
+ ),
+ );
+
+ return $variations;
+}
+add_filter( 'get_block_type_variations', 'my_custom_image_variation', 10, 2 );
+```
+
+The `get_block_type_variations` filter is called when variations are requested for a block type. It receives two parameters:
+- `$variations`: An array of currently registered variations for the block type
+- `$block_type`: The full block type object
+
+Note that variations registered through PHP will be merged with any variations registered through JavaScript using `registerBlockVariation()`.
+
+
+
## Removing a block variation
Block variations can also be easily removed. To do so, use `wp.blocks.unregisterBlockVariation()`. This function accepts the name of the block and the `name` of the variation that should be unregistered.
diff --git a/docs/reference-guides/core-blocks.md b/docs/reference-guides/core-blocks.md
index 3b251813e41c0a..a548e5df8f28a8 100644
--- a/docs/reference-guides/core-blocks.md
+++ b/docs/reference-guides/core-blocks.md
@@ -14,7 +14,7 @@ Display a date archive of your posts. ([Source](https://github.com/WordPress/gut
- **Name:** core/archives
- **Category:** widgets
-- **Supports:** align, interactivity (clientNavigation), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~
+- **Supports:** align, color (background, gradients, link, text), interactivity (clientNavigation), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~
- **Attributes:** displayAsDropdown, showLabel, showPostCounts, type
## Audio
@@ -32,7 +32,7 @@ Add a user’s avatar. ([Source](https://github.com/WordPress/gutenberg/tree/tru
- **Name:** core/avatar
- **Category:** theme
-- **Supports:** align, color (~~background~~, ~~text~~), interactivity (clientNavigation), spacing (margin, padding), ~~alignWide~~, ~~html~~
+- **Supports:** align, color (~~background~~, ~~text~~), filter (duotone), interactivity (clientNavigation), spacing (margin, padding), ~~alignWide~~, ~~html~~
- **Attributes:** isLink, linkTarget, size, userId
## Pattern
@@ -78,7 +78,7 @@ Display a list of all terms of a given taxonomy. ([Source](https://github.com/Wo
- **Name:** core/categories
- **Category:** widgets
-- **Supports:** align, interactivity (clientNavigation), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~
+- **Supports:** align, color (background, gradients, link, text), interactivity (clientNavigation), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~
- **Attributes:** displayAsDropdown, label, showEmpty, showHierarchy, showLabel, showOnlyTopLevel, showPostCounts, taxonomy
## Code
@@ -245,7 +245,7 @@ Add an image or video with a text overlay. ([Source](https://github.com/WordPres
- **Name:** core/cover
- **Category:** media
-- **Supports:** align, anchor, color (heading, text, ~~background~~, ~~enableContrastChecker~~), dimensions (aspectRatio), interactivity (clientNavigation), layout (~~allowJustification~~), shadow, spacing (blockGap, margin, padding), typography (fontSize, lineHeight), ~~html~~
+- **Supports:** align, anchor, color (heading, text, ~~background~~, ~~enableContrastChecker~~), dimensions (aspectRatio), filter (duotone), interactivity (clientNavigation), layout (~~allowJustification~~), shadow, spacing (blockGap, margin, padding), typography (fontSize, lineHeight), ~~html~~
- **Attributes:** allowedBlocks, alt, backgroundType, contentPosition, customGradient, customOverlayColor, dimRatio, focalPoint, gradient, hasParallax, id, isDark, isRepeated, isUserOverlayColor, minHeight, minHeightUnit, overlayColor, sizeSlug, tagName, templateLock, url, useFeaturedImage
## Details
@@ -255,7 +255,7 @@ Hide and show additional content. ([Source](https://github.com/WordPress/gutenbe
- **Name:** core/details
- **Category:** text
- **Supports:** align (full, wide), anchor, color (background, gradients, link, text), interactivity (clientNavigation), layout (~~allowEditing~~), spacing (blockGap, margin, padding), typography (fontSize, lineHeight), ~~html~~
-- **Attributes:** allowedBlocks, showContent, summary
+- **Attributes:** allowedBlocks, name, placeholder, showContent, summary
## Embed
@@ -418,7 +418,7 @@ An organized collection of items displayed in a specific order. ([Source](https:
- **Supports:** __unstablePasteTextInline, anchor, color (background, gradients, link, text), interactivity (clientNavigation), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~
- **Attributes:** ordered, placeholder, reversed, start, type, values
-## List item
+## List Item
An individual item within a list. ([Source](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/list-item))
@@ -534,7 +534,7 @@ Start with the basic building block of all narrative. ([Source](https://github.c
- **Supports:** __unstablePasteTextInline, anchor, color (background, gradients, link, text), interactivity (clientNavigation), spacing (margin, padding), splitting, typography (fontSize, lineHeight), ~~className~~
- **Attributes:** align, content, direction, dropCap, placeholder
-## Pattern placeholder
+## Pattern Placeholder
Show a block pattern. ([Source](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/pattern))
@@ -549,7 +549,7 @@ Display post author details such as name, avatar, and bio. ([Source](https://git
- **Name:** core/post-author
- **Category:** theme
-- **Supports:** color (background, gradients, link, text), interactivity (clientNavigation), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~
+- **Supports:** color (background, gradients, link, text), filter (duotone), interactivity (clientNavigation), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~
- **Attributes:** avatarSize, byline, isLink, linkTarget, showAvatar, showBio, textAlign
## Author Biography
@@ -616,7 +616,7 @@ Displays the contents of a post or page. ([Source](https://github.com/WordPress/
- **Name:** core/post-content
- **Category:** theme
-- **Supports:** align (full, wide), background (backgroundImage, backgroundSize), color (background, gradients, link, text), dimensions (minHeight), layout, spacing (blockGap, margin, padding), typography (fontSize, lineHeight), ~~html~~
+- **Supports:** align (full, wide), background (backgroundImage, backgroundSize), color (background, gradients, heading, link, text), dimensions (minHeight), layout, spacing (blockGap, margin, padding), typography (fontSize, lineHeight), ~~html~~
## Date
@@ -672,7 +672,7 @@ Post terms. ([Source](https://github.com/WordPress/gutenberg/tree/trunk/packages
- **Supports:** color (background, gradients, link, text), interactivity (clientNavigation), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~
- **Attributes:** prefix, separator, suffix, term, textAlign
-## Time To Read
+## Time to Read
Show minutes required to finish reading the post. ([Source](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/post-time-to-read))
@@ -718,7 +718,7 @@ An advanced block that allows displaying post types based on different query par
- **Supports:** align (full, wide), interactivity, layout, ~~html~~
- **Attributes:** enhancedPagination, namespace, query, queryId, tagName
-## No results
+## No Results
Contains the block elements used to render content when no query results are found. ([Source](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/query-no-results))
@@ -784,7 +784,7 @@ Display the total number of results in a query. ([Source](https://github.com/Wor
- **Name:** core/query-total
- **Category:** theme
- **Ancestor:** core/query
-- **Supports:** align (full, wide), color (background, gradients, text), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~
+- **Supports:** align (full, wide), color (background, gradients, text), interactivity (clientNavigation), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~
- **Attributes:** displayType
## Quote
@@ -811,8 +811,8 @@ Display entries from any RSS or Atom feed. ([Source](https://github.com/WordPres
- **Name:** core/rss
- **Category:** widgets
-- **Supports:** align, color (background, gradients, link, text), interactivity (clientNavigation), ~~html~~
-- **Attributes:** blockLayout, columns, displayAuthor, displayDate, displayExcerpt, excerptLength, feedURL, itemsToShow
+- **Supports:** align, color (background, gradients, link, text), interactivity (clientNavigation), spacing (margin, padding), ~~html~~
+- **Attributes:** blockLayout, columns, displayAuthor, displayDate, displayExcerpt, excerptLength, feedURL, itemsToShow, openInNewTab, rel
## Search
@@ -847,7 +847,7 @@ Display an image to represent this site. Update this block and the changes apply
- **Name:** core/site-logo
- **Category:** theme
-- **Supports:** align, color (~~background~~, ~~text~~), interactivity (clientNavigation), spacing (margin, padding), ~~alignWide~~, ~~html~~
+- **Supports:** align, color (~~background~~, ~~text~~), filter (duotone), interactivity (clientNavigation), spacing (margin, padding), ~~alignWide~~, ~~html~~
- **Attributes:** isLink, linkTarget, shouldSyncIcon, width
## Site Tagline
@@ -885,7 +885,7 @@ Display icons linking to your social profiles or sites. ([Source](https://github
- **Name:** core/social-links
- **Category:** widgets
- **Allowed Blocks:** core/social-link
-- **Supports:** align (center, left, right), anchor, color (background, gradients, ~~enableContrastChecker~~, ~~text~~), interactivity (clientNavigation), layout (default, ~~allowInheriting~~, ~~allowSwitching~~, ~~allowVerticalAlignment~~), spacing (blockGap, margin, padding, units)
+- **Supports:** align (center, left, right), anchor, color (background, gradients, ~~enableContrastChecker~~, ~~text~~), interactivity (clientNavigation), layout (default, ~~allowInheriting~~, ~~allowSwitching~~, ~~allowVerticalAlignment~~), spacing (blockGap, margin, padding, units), ~~html~~
- **Attributes:** customIconBackgroundColor, customIconColor, iconBackgroundColor, iconBackgroundColorValue, iconColor, iconColorValue, openInNewTab, showLabels, size
## Spacer
@@ -914,7 +914,7 @@ Summarize your post with a list of headings. Add HTML anchors to Heading blocks
- **Experimental:** true
- **Category:** design
- **Supports:** color (background, gradients, link, text), interactivity (clientNavigation), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~
-- **Attributes:** headings, onlyIncludeCurrentPage
+- **Attributes:** headings, maxLevel, onlyIncludeCurrentPage
## Tag Cloud
diff --git a/docs/reference-guides/interactivity-api/README.md b/docs/reference-guides/interactivity-api/README.md
index 3a5bbb84ff159c..5504f8fd19fafe 100644
--- a/docs/reference-guides/interactivity-api/README.md
+++ b/docs/reference-guides/interactivity-api/README.md
@@ -113,7 +113,7 @@ Here you have some more resources to learn/read more about the Interactivity API
- [Merge announcement](https://make.wordpress.org/core/2024/02/19/merge-announcement-interactivity-api/)
- [Proposal: The Interactivity API – A better developer experience in building interactive blocks](https://make.wordpress.org/core/2023/03/30/proposal-the-interactivity-api-a-better-developer-experience-in-building-interactive-blocks/)
- [Interactivity API Discussions](https://github.com/WordPress/gutenberg/discussions/52882), especially the [showcase](https://github.com/WordPress/gutenberg/discussions/55642#discussioncomment-9667164) discussions.
-- [wpmovies.dev](http://wpmovies.dev/) demo and its [wp-movies-demo](https://github.com/WordPress/wp-movies-demo) repo
+- [wpmovies.dev](https://wpmovies.dev/) demo and its [wp-movies-demo](https://github.com/WordPress/wp-movies-demo) repo
- Examples using the Interactivity API at [block-development-examples](https://github.com/WordPress/block-development-examples):
- [`interactivity-api-block-833d15`](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/interactivity-api-block-833d15)
- [`interactivity-api-countdown-3cd73e`](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/interactivity-api-countdown-3cd73e)
diff --git a/docs/reference-guides/interactivity-api/api-reference.md b/docs/reference-guides/interactivity-api/api-reference.md
index bbbb565684c578..c5ed0e84025a15 100644
--- a/docs/reference-guides/interactivity-api/api-reference.md
+++ b/docs/reference-guides/interactivity-api/api-reference.md
@@ -873,28 +873,28 @@ const { state } = store( 'myPlugin', {
} );
```
-As mentioned above with [`wp-on`](#wp-on), [`wp-on-window`](#wp-on-window), and [`wp-on-document`](#wp-on-document), an async action should be used whenever the `async` versions of the aforementioned directives cannot be used due to the action requiring synchronous access to the `event` object. Synchronous access is required whenever the action needs to call `event.preventDefault()`, `event.stopPropagation()`, or `event.stopImmediatePropagation()`. To ensure that the action code does not contribute to a long task, you may manually yield to the main thread after calling the synchronous event API. For example:
+You may want to add multiple such `yield` points in your action if it is doing a lot of work.
+
+As mentioned above with [`wp-on`](#wp-on), [`wp-on-window`](#wp-on-window), and [`wp-on-document`](#wp-on-document), an async action should be used whenever the `async` versions of the aforementioned directives cannot be used due to the action requiring synchronous access to the `event` object. Synchronous access is required whenever the action needs to call `event.preventDefault()`, `event.stopPropagation()`, or `event.stopImmediatePropagation()`.
+
+To ensure that the action code does not contribute to a long task, you may manually yield to the main thread after calling the synchronous event API. The Interactivity API provides the `splitTask()` function for that purpose, which implements yielding in a cross-browser compatible way. Here is an example:
```js
-// Note: In WordPress 6.6 this splitTask function is exported by @wordpress/interactivity.
-function splitTask() {
- return new Promise( ( resolve ) => {
- setTimeout( resolve, 0 );
- } );
-}
+import { splitTask } from '@wordpress/interactivity';
store( 'myPlugin', {
actions: {
- handleClick: function* ( event ) {
+ handleClick: withSyncEvent( function* ( event ) {
event.preventDefault();
yield splitTask();
doTheWork();
- },
+ } ),
},
} );
```
-You may want to add multiple such `yield` points in your action if it is doing a lot of work.
+You may notice the use of the [`withSyncEvent()`](#withsyncevent) utility function in this example. This is necessary due to an ongoing effort to handle store actions asynchronously by default, unless they require synchronous event access (which this example does due to the call to `event.preventDefault()`). Otherwise a deprecation warning will be triggered, and in a future release the behavior will change accordingly.
+
#### Side Effects
@@ -1253,6 +1253,43 @@ store( 'mySliderPlugin', {
} );
```
+### withSyncEvent()
+
+Actions that require synchronous access to the `event` object need to use the `withSyncEvent()` function to annotate their handler callback. This is necessary due to an ongoing effort to handle store actions asynchronously by default, unless they require synchronous event access. Therefore, as of Gutenberg 20.4 / WordPress 6.8 all actions that require synchronous event access need to use the `withSyncEvent()` function. Otherwise a deprecation warning will be triggered, and in a future release the behavior will change accordingly.
+
+Only very specific event methods and properties require synchronous access, so it is advised to only use `withSyncEvent()` when necessary. The following event methods and properties require synchronous access:
+
+* `event.currentTarget`
+* `event.preventDefault()`
+* `event.stopImmediatePropagation()`
+* `event.stopPropagation()`
+
+Here is an example, where one action requires synchronous event access while the other actions do not:
+
+```js
+// store
+import { store, withSyncEvent } from '@wordpress/interactivity';
+
+store( 'myPlugin', {
+ actions: {
+ // `event.preventDefault()` requires synchronous event access.
+ preventNavigation: withSyncEvent( ( event ) => {
+ event.preventDefault();
+ } ),
+
+ // `event.target` does not require synchronous event access.
+ logTarget: ( event ) => {
+ console.log( 'event target => ', event.target );
+ },
+
+ // Not using `event` at all does not require synchronous event access.
+ logSomething: () => {
+ console.log( 'something' );
+ },
+ },
+} );
+```
+
## Server functions
The Interactivity API comes with handy functions that allow you to initialize and reference configuration options on the server. This is necessary to feed the initial data that the Server Directive Processing will use to modify the HTML markup before it's send to the browser. It is also a great way to leverage many of WordPress's APIs, like nonces, AJAX, and translations.
diff --git a/docs/reference-guides/interactivity-api/core-concepts/the-reactive-and-declarative-mindset.md b/docs/reference-guides/interactivity-api/core-concepts/the-reactive-and-declarative-mindset.md
index 3760fdf3867802..4f167d4e37de8a 100644
--- a/docs/reference-guides/interactivity-api/core-concepts/the-reactive-and-declarative-mindset.md
+++ b/docs/reference-guides/interactivity-api/core-concepts/the-reactive-and-declarative-mindset.md
@@ -28,6 +28,15 @@ Take, for example, this interactive block with two buttons and a paragraph:
this is inactive