The WordPress coreCoreCore is the set of software required to run WordPress. The Core Development Team builds WordPress. development team builds WordPress! Follow this site for general updates, status reports, and the occasional code debate. There’s lots of ways to contribute:
Found a bugbugA bug is an error or unexpected result. Performance improvements, code optimization, and are considered enhancements, not defects. After feature freeze, only bugs are dealt with, with regressions (adverse changes from the previous version) being the highest priority.?Create a ticket in the bug tracker.
Over the last year, a group of contributors has been working to improve the blockBlockBlock is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. development onboarding experience within the Block Editor Handbook. In this post, I wanted to take a moment and highlight the updates made, pinpoint areas for further refinement, and outline our focus for the next few months and ways you can help.
Project overview
The initiative to enhance the Block Editor Handbook began in 2020, largely sparked by the Next Steps for Block Creation Documentation discussion on GitHubGitHubGitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/. Since that time, the community has been consistently updating the content, with the most recent effort led by @juanmaguitar, @welcher, @mburridge, and myself.
In talking with prospective block developers, documentation was consistently one of the most recurrent pain points, especially for those who want to learn how to build custom blocks or extend the Editor using official resources. Improving the Getting Started section, as well as other extensibility docs, was a natural starting point in addressing this feedback.
Here are some highlights from the work completed in the last eight months:
Landing page makeover: We’ve revamped the Handbook’s main page to make it more inviting and informative for those new to block development.
Updated Getting Started chapter: This section now offers a clearer path for beginners, including:
Block Development Environment: A selection of detailed guides on setting up everything you need for block development.
Quick Start Guide: A new, straightforward guide for quickly setting up a block development environment with a helpful walkthrough video.
Fundamentals of Block Development: A deep dive into the most important concepts in block development, taking into account the feedback received on commonly confused topics.
Expanded Curating the Editor Experience: Previously a single page, this topic was given its own dedicated section, with more updates coming in Q1 2024.
Block Development Examples: We launched a GitHub repository filled with practical examples of custom blocks and Editor extensions, complete with Playground previews and downloadable versions of each example. Contributions to the repository are welcomed.
More visuals: We’ve added diagrams and images throughout the Handbook to clarify key ideas.
At this point, improvement to the Reference Guides chapter is ongoing, but no fundamental restructuring is planned in the near future. If you have ideas on how this section can be improved (much of it is autogenerated from in-code documentation), please share your suggestions. The current setup is not ideal, and it’s also not complete. Some code documentation is only accessible in the Gutenberg GitHub repository.
Get involved
The Block Editor Handbook contains over 400 published pages, and the effort taken in 2023 just scratches the surface. While that might seem daunting, improving the documentation is one of the easiest ways to contribute to the WordPress project, especially for quick fixes like typos or formatting. Feedback on existing content, such as the new block tutorial, is also invaluable.
All documentation is hosted on the GutenbergGutenbergThe Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ GitHub repository. If you find an issue or wish to give feedback, please open a new issue there. If you would like to fix issues yourself, follow the Documentation Contributions guide to learn how to submit a pull request. You can see the list of all outstanding documentation issues using the[Type] Developer Documentation label.
If you experience any problems or have questions, reach out in the #core-editor or #docsSlackSlackSlack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/. channels. You can also leave comments here or pingPingThe act of sending a very small amount of data to an end point. Ping is used in computer science to illicit a response from a target server to test it’s connection. Ping is also a term used by Slack users to @ someone or send them a direct message (DM). Users might say something along the lines of “Ping me when the meeting starts.” me (@ndiego) directly.
The Interactivity API proposal was published a few months ago. This APIAPIAn API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. aims to create a new standard for WordPress that simplifies and empowers building rich interactive web applications with WordPress using declarative and reactive programming principles.
Since the proposal was published, a dedicated group of contributors has been focused on incorporating the Interactivity API into the GutenbergGutenbergThe Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ project, albeit in an experimental capacity. Fresh documentation resources have also been prepared to guide you through this API’s exciting possibilities.
While the Interactivity API is experimental, you can already start exploring its potential, testing its features, and exploring what’s to come.
This update shares the current state of the Interactivity API, the avenues to track its progress, the learning resources available, and how you can contribute.
Wondering about the current state of affairs and how to stay in the loopLoopThe Loop is PHP code used by WordPress to display posts. Using The Loop, WordPress processes each post to be displayed on the current page, and formats it according to how it matches specified criteria within The Loop tags. Any HTML or PHP code in the Loop will be processed on each post. https://codex.wordpress.org/The_Loop.? Let’s dive right in.
Some coreCoreCore is the set of software required to run WordPress. The Core Development Team builds WordPress. blocks are already embracing the Interactivity API’s potential, but its integration is still very limited.
The list of tasks planned for the Interactivity API is available in the Roadmap – Current list of tasks discussion. This roadmap evolves and adapts as contributors learn more about the needs of this initiative.
A good way to keep track of the development of the Interactivity API is to subscribe to Roadmap – Current list of tasks, as this discussion will be updated whenever new Tracking Issues are introduced or fresh plans emerge for this proposal’s future.
Given its experimental state, rapid iterations and occasional disruptions are expected. The Changelog – Tracking Breaking Changes in the Interactivity API discussion ensures you’re properly informed about any breaking change on new Gutenberg releases.
Learning Resources
Ready to expand your knowledge about the Interactivity API? Here’s where to start.
Where can I find technical documentation?
Technical documentation for the Interactivity API can be located within the docs folder of the interactivity package. This documentation currently hosts the following resources:
Bear in mind that this documentation is still a work in progress, so don’t hesitate to open a new discussion to ask any questions. If you want to contribute to documentation efforts, join the Coordinating our documentation efforts discussion.
To get started with the Interactivity API, you can follow this Quick Start Guide taking into account the current requirements of the Interactivity API. This guide will show you how to create your first interactive blockBlockBlock is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. with the Interactivity API that you can test in your WordPress projects.
Once your interactive block is up and running, you can learn more from the Interactivity API Reference to continue adding interactivity to your blocks with this API.
As WordPress advances toward more powerful interactive experiences, seize the opportunity to engage. Your insights and contributions will help shape this proposal.
What if effortlessly creating performant, fluid, and idiomatic frontend interactivity on blockBlockBlock is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience.-based WordPress sites was possible? Imagine plugins providing interactions like “heart this post” or “add to cart” without page reloads. Picture instant search, commenting, and native full-page transitions as best-in-class built-ins without complex scaffolding or external tools. Envision achieving this in any block theme by default without sacrificing PHPPHPThe web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher server rendering and the pluginPluginA plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party ecosystem for a JSJSJavaScript, a web scripting language typically executed in the browser. Often used for advanced user interfaces and behaviors. runtime. Visualize block developers easily declaring and extending such behaviors in a way that is immediately familiar and compatible with the block ecosystem.
That’s what we, the contributors involved in this project, aim to explore and unlock with the Interactivity APIAPIAn API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways.. The demo below shows some of this power and flexibility in action.
GutenbergGutenbergThe Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ has evolved a lot over the past few years, though most of the improvements have focused on the block developer experience within the block editor. Today, we’d like to update you on the Interactivity API, which aims to be a standard way to allow developers to add interactivity to the frontend of their blocks.
The Interactivity API is for the frontend of blocks, not for the block editor. This means the API is not expected to be used inside the edit function. It’s a way to create interactive user interfaces for your site visitors. Having said that, we’d like to explore whether some directives could be reused across the frontend and the editor to unify the whole block developer experience.
This is still experimental. Functionalities are missing, documentation is scarce, and the final API may look different. The API’s design is open to debate, and any feedback is key to ensuring the Interactivity API accounts for the entirety of WordPress’ diverse needs and requirements.
The main goal of the Interactivity API is to provide a standard and simple way to handle the frontend interactivity of Gutenberg blocks.
A standard makes it easier for developers to create rich, interactive user experiences, from simple cases like counters or popups to more complex features like instant page navigation, instant search, or carts and checkouts.
All these user experiences are technically possible right now without the Interactivity API. However, the more complex the user experience and the more blocks interact with each other, the harder it becomes for developers to build and maintain sites. There are a lot of challenges they have to figure out themselves. The API aims to provide out-of-the-box means for supporting these kinds of interactions.
To address this challenge, before researching different approaches, some requirements/goals for the API were defined:
Block-first and PHP-first: The API must work well with PHP and the current block system, including dynamic blocks, widely extended in WordPress. It must support server-side rendering. Server-rendered HTMLHTMLHyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers. and client-hydrated HTML must be exactly the same. This is important for SEO and the user experience.
Backward compatible: The API must be compatible with WordPress hooksHooksIn WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same., which could, for example, modify server-rendered HTML. It must also be compatible with internationalization and existing JS libraries on the site (such as jQuery).
Optional and gradual adoption: Related to the previous point, the API must remain optional. It should be possible to adopt it gradually, meaning that interactive blocks not using this API can coexist with those using it.
Declarative and reactive: The API must use declarative code, listen to changes in the data, and update only the parts of the DOM that depend on that data.
Performant: The runtime must be fast and lightweight to ensure the best user experience.
ExtensibleExtensibleThis is the ability to add additional functionality to the code. Plugins extend the WordPress core software.: In the same way WordPress focuses on extensibility, this new system must provide extensibility patterns to cover most use cases.
Atomic and composable: Having small reusable parts that can be combined to create more complex systems is required to create flexible and scalable solutions.
Compatible with the existing block development tooling: The API must be integrated with the existing block-building tools without requiring additional tooling or configuration by the developer.
Apart from all these requirements, integrating client-side navigation on top of any solution should be easy and performant. Client-side navigation is the process of navigating between site pages without reloading the entire page, which is one of the most impressive user experiences demanded by web developers. For that reason, this functionality should be compatible with this new system.
What’s being proposed?
The Interactivity API is a standard system of directives, based on declarative code, for adding frontend interactivity to blocks.
Directives extend HTML with special attributes that tell the Interactivity API to attach a specified behavior to a DOM element or even to transform it. For those familiar with Alpine.js, it’s a similar approach but explicitly designed to work seamlessly with WordPress.
The API is designed for the world of blocks and takes WordPress history of being closely attached to web standards to heart.
As directives are added to the HTML, they work great with dynamic blocks and PHP.
Dynamic block example
<div
data-wp-interactive='{ "namespace": "wpmovies" }'
data-wp-context='{ "isOpen": false }'
data-wp-watch="callbacks.logIsOpen"
>
<button
data-wp-on--click="actions.toggle"
data-wp-bind--aria-expanded="context.isOpen"
aria-controls="p-1"
>
Toggle
</button>
<p id="p-1" data-wp-show="context.isOpen">
This element is now visible!
</p>
</div>
As you can see, directives like data-wp-on--click or data-wp-show are added as custom HTML attributes. WordPress can process this HTML on the server, handling the directives’ logic and creating the appropriate markup.
Backward compatible
As the Interactivity API works perfectly with server-side rendering, you can use all the WordPress APIs, including:
WordPress filters and actions: You can keep using WordPress hooks to modify the HTML or even to modify directives. Additionally, existing hooks will keep working as expected.
CoreCoreCore is the set of software required to run WordPress. The Core Development Team builds WordPress.TranslationtranslationThe process (or result) of changing text, words, and display formatting to support another language. Also see localization, internationalization. API: e.g. __() and _e(). You can use it to translate the text in the HTML (as you normally would) and even use those APIs on the server side of your directives.
Optional and gradual adoption
The Interactivity API pipeline promotes progressive enhancementenhancementEnhancements are simple improvements to WordPress, such as the addition of a hook, a new feature, or an improvement to an existing feature. by building on top of WordPress’s solid foundation and patterns. It was carefully designed not to force any use cases to pay for the costs of other use cases.
For example, blocks with directives can coexist with other (interactive or non-interactive) blocks. This means that if there are other blocks on the page using other frameworks like jQuery, everything will work as expected.
Declarative and reactive
The Interactivity API follows an approach similar to other popular JS frameworks by separating state, actions, and callbacks and defining them declaratively. Why declaratively?
Declarative code describes what a program should do, while imperative code describes how the program should do it. Using a declarative approach, the UIUIUser interface automatically updates in response to changes in the underlying data. With an imperative approach, you must manually update the UI whenever the data changes. Compare the two code examples:
Imperative code
<button id="toggle-button">Toggle Element</button>
<p>This element is now visible!</p>
<script>
const button = document.getElementById("toggle-button");
button.addEventListener("click", () => {
const element = document.getElementById("element");
if(element) {
element.remove();
} else {
const newElement = document.createElement("p");
newElement.textContent = "This element is visible";
document.body.appendChild(newElement);
}
});
</script>
Declarative code
This is the same use case shared above but serves as an example of declarative code using this new system. The JavaScriptJavaScriptJavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. logic is defined in the view.js file of the block, and add the directives to the markup in the render.php .
<!-- Render.php file -->
<div
data-wp-interactive='{ "namespace": "wpmovies" }'
data-wp-context="{ 'isOpen': true }"
>
<button
data-wp-on--click="actions.toggle"
data-wp-bind--aria-expanded="context.ispen"
aria-controls="p-1"
>
Toggle
</button>
<p id="p-1" data-wp-show="context.isOpen">
This element is now visible!
</p>
</div>
Don’t worry if you don’t fully understand this example yet. It will be explained in detail later in the post.
Using imperative code may be easier when creating simple user experiences, but it becomes much more difficult as blocks become more complex. The Interactivity API must cover all use cases, from the simplest to the most challenging. That’s why a declarative approach using directives better fits the Interactivity API.
Performant
The API has been designed to be as performant as possible:
The runtime code needed for the directives is just ~10 KB, and it only needs to be loaded once for all the blocks.
It only loads the directives needed by the blocks present on the page. For example, if no blocks are using data-wp-show, the code for this directive won’t be loaded.
The scripts will load without blocking the page rendering.
There are ongoing explorations about the possibility of delaying the scripts loading once the block is in the viewport. This way, the initial load would be optimized without affecting the user experience.
Extensible
Directives can be added, removed, or modified directly from the HTML. For example, users could use the render_block filter to modify the HTML and its behavior.
In addition to using built-in directives, users can create custom directives to add any custom behaviors to their HTML.
Atomic and composable
Each directive controls a small part of the DOM, and you can combine multiple directives to create rich, interactive user experiences.
Compatible with the existing block development tooling
Using built-in directives does not require a build step and only requires a small runtime. A build step is necessary only when creating custom directives that return JSX. For such use cases, the API works out of the box with common block-building tools like wp-scripts.
Client-side navigation
The Interactivity API comes with built-in primitives for adding client-side navigation to your site. This functionality is completely optional, but it opens the possibility to create these user experiences without having to opt out of the WordPress rendering system.
It also pairs very well with the View Transitions API allowing developers to animate page transitions easily.
Why a standard?
Blocks using the Interactivity API and interactive blocks using other approaches like jQuery can coexist, and everything will work as expected. However, the Interactivity API comes with some benefits for your interactive blocks:
Blocks can communicate with each other easily. With a standard, this communication is handled by default. When different blocks use different approaches to frontend interactivity, inter-block communication becomes more complex and almost impossible when separate developers create blocks.
Composability and compatibility: You can combine interactive blocks, and nest them in structures with defined behaviors. Thanks to following the same standard, they are fully cross-compatible. If each block used a different approach to interactivity, they would likely break.
Fewer KBs will be sent to the browser. If each plugin author uses a different JS framework, more code will be loaded in the frontend. If all the blocks use the same one, the code is reused.
If all the blocks on a page use this standard, site-wide features like client-side navigation can be enabled.
Additionally, with a standard, WordPress can absorb the maximum amount of complexity from the developer because it will handle most of what’s needed to create an interactive block.
Complexities absorbed by the standard
With this absorption, less knowledge is required to create interactive blocks, and developers have fewer decisions to worry about.
Additionally, if the community adopts a standard, learning from other interactive blocks would be simpler, which fosters collaboration and code reusability. This should simplify the development process and make it friendlier to less experienced developers.
How to create interactive blocks using the API
It’s important to highlight that the block creation workflow doesn’t change.
Until now, WordPress has been intentionally unopinionated about the different solutions used on the frontend of blocks. The Interactivity API changes that. It adds a new standard way to easily add frontend interactivity to blocks while the APIs handling the Block Editor remain the same.
To add interactivity to blocks using the Interactivity API, developers would need to:
Add directives to the markup to add specific behavior to the block.
If needed, create a store with the logic (state, actions, or callbacks) needed for interactivity. Blocks using only directives with self-sufficient logic like data-wp-link, don’t need this step.
Before explaining each step in more detail, let’s return to our example: a button that shows and hides some text. We’ll also add logic to send a message in the console whenever the button is hidden/revealed.
Add directives
Directives are added to the markup of your block. In the render.php file (for dynamic blocks) or the save.js file (for static blocks).
<div
data-wp-interactive='{ "namespace": "wpmovies" }'
data-wp-context='{ "isOpen": false }'
data-wp-watch="callbacks.logIsOpen"
>
<button
data-wp-on--click="actions.toggle"
data-wp-bind--aria-expanded="context.isOpen"
aria-controls="p-1"
>
Toggle
</button>
<p id="p-1" data-wp-show="context.isOpen">
This element is now visible!
</p>
</div>
In this example, the directive data-wp-context is used to define some local state ("isOpen": false) that will be available to that HTML node and all its children. All the actions and callbacks used in those nodes can access that data. Knowing that, other directives like data-wp-on--click can trigger actions and callbacks reading that context.
Create the store
In this part, the logic (actions and callbacks) called by the directives is defined.
The store is created in the view.js file of each block. Although it works at a block level right now, the possibility of sharing code that multiple blocks need will be investigated as well.
// view.js
import { store, getContext } from "@wordpress/interactivity";
store( 'wpmovies', {
actions: {
toggle: () => {
const context = getContext();
context.isOpen = !context.isOpen;
},
},
callbacks: {
logIsOpen: () => {
const context = getContext();
// Log the value of `isOpen` each time it changes.
console.log(`Is open: ${context.isOpen}`);
},
},
});
For those familiar with ReactReactReact is a JavaScript library that makes it easy to reason about, construct, and maintain stateless and stateful user interfaces. https://reactjs.org/., this would be an equivalent React component:
const Comp = () => {
const [isOpen, setIsOpen] = useState(false);
useEffect(() => {
// Log the value of `isOpen` each time it changes.
console.log(`Is Open: ${isOpen}`);
}, [isOpen]);
const toggle = () => {
setIsOpen(!isOpen);
};
return (
<div>
<button
onClick={toggle}
aria-expanded={isOpen}
aria-controls="p-1"
>
Toggle
</button>
{isOpen && <p id="p-1">This element is visible!</p>}
</div>
);
};
Let’s take a look at each step in detail:
1. Add the directives
Directives are custom HTML attributes whose value can contain options or references to the store.
Let’s return to our previous example:
Dynamic block example
// render.php
<div
<?php echo get_block_wrapper_attributes(); ?>
data-wp-interactive='{ "namespace": "wpmovies" }'
data-wp-context='{ "isOpen": false }'
data-wp-watch="callbacks.logIsOpen"
>
<button
data-wp-on--click="actions.toggle"
data-wp-bind--aria-expanded="context.isOpen"
aria-controls="p-1"
>
Toggle
</button>
<p id="p-1" data-wp-show="context.isOpen">
This element is now visible!
</p>
</div>
This is how it would work in a static block:
Static block example
// save.js
const save = () => {
return `
<div
{...useBlockProps()}
data-wp-interactive='{ "namespace": "wpmovies" }'
data-wp-context='{ "isOpen": true }'
data-wp-watch="callbacks.logIsOpen"
>
<button
data-wp-on--click="actions.toggle"
data-wp-bind--aria-expanded="context.isOpen"
aria-controls="p-1"
>
Toggle
</button>
<p id="p-1" data-wp-show="context.isOpen">
This element is now visible!
</p>
</div>
`;
};
The example above uses directives like wp-show and wp-on to add interactivity to the HTML. Below is the initial list of core directives planned, which aims to cover the most common use cases for adding interactivity. It has been inspired by other frameworks like Alpine, VueVueVue (pronounced /vjuː/, like view) is a progressive framework for building user interfaces. https://vuejs.org/., or Svelte:
wp-context provides local state available to a specific HTML node and its children.
wp-on runs code on dispatched DOM events like click or keyup. The format of this directive is data-wp-on--[event], like data-wp-on--click or data-wp-on--keyup.
wp-show shows and hides elements depending on the state or context.
wp-each creates DOM elements by iterating through a list.
wp-bind allows setting HTML attributes on elements.
wp-class adds or removes a class to an HTML element, depending on its value.
wp-style adds or removes inline style to an HTML element, depending on its value.
wp-text sets the inner content of an HTML element.
wp-html sets the innerHTML property of an HTML element.
wp-slot / wp-fill moves snippets of HTML from one place (fills) to another (slots).
wp-watch runs an expression when the node is created and runs it again when the state or context changes.
wp-init runs an expression only when the node is created.
wp-error captures errors in other interactive blocks.
Please bear in mind that this list may vary, and not all these core directives have been implemented yet. Additionally, the API is extensible: anyone can create their own directives if needed.
An important feature is that, when needed, directives support server-side rendering in PHP. This results in a better user experience and better SEO. This is usually taken for granted with WordPress but, when using modern frameworks like React to add interactivity to blocks, it is common to show empty content until client-side JavaScript updates the HTML.
2. Create the store
The store contains the reactive state and the actions and callbacks that modify it.
State: Defines data available to the HTML nodes of the page. It is important to differentiate between two ways to define the data:
Global state: It is defined using the store() function, and the data is available to all the HTML nodes of the page.
Context/Local State: It is defined using the data-wp-context directive in an HTML node, and the data is available to that HTML node and its children.
Actions: Usually triggered by the data-wp-on directive (using event listeners) or other actions.
Callbacks: Automatically react to state changes. Usually triggered by data-wp-callback or data-wp-init directives.
Returning to our example, this could be a simple store in one block:
// view.js
import { store, getContext } from "@wordpress/interactivity";
store( 'wpmovies', {
actions: {
toggle: () => {
const context = getContext();
context.isOpen = !context.isOpen;
},
},
callbacks: {
logIsOpen: () => {
const context = getContext();
// Log the value of `isOpen` each time it changes.
console.log(`Is open: ${context.isOpen}`);
},
},
});
In this specific case, only actions and callbacks are defined, but some state could also be included. For example, you could define the state in another block to create a list with your “Favorite movies”. It might look something like this:
// view.js - A favorite movies block
import { store, getContext } from '@wordpress/interactivity';
const { state } = store( 'wpmovies', {
state: {
favoriteMovies: [],
},
actions: {
addMovie: () => {
const context = getContext();
// We assume that there is a `wp-context` directive
// on the block which provides the item ID.
state.favoriteMovies.push(context.item.id);
},
clearFavoriteMovies: () => {
state.favoriteMovies = [];
},
},
});
Note: The store function will automatically merge the store definitions from all the blocks using store into a single reactive object. This way, you can use the global state defined in other blocks.
Initializing the store on the server with wp_initial_state()
The state can also be initialized on the server using the wp_initial_state() function. You would typically do this in the render.php file of your block (the render.php templates were introduced in WordPress 6.1). Initializing your state on the server allows you to populate it with some data from the server without worrying about serializing that data or making additional API requests.
The store defined on the server with wp_initial_state() gets merged with the stores defined in the view.js files. For example, the “Favorite movies” block from above could initialize its store on the server like this:
And then its `view.js` file would be simplified to:
// view.js - A favorite movies block
import { store, getContext } from '@wordpress/interactivity';
const { state } = store( 'wpmovies', {
actions: {
addMovie: () => {
const context = getContext();
// We assume that there is a `wp-context` directive
// on the block which provides the item ID.
state.favoriteMovies.push(context.item.id);
},
clearFavoriteMovies: () => {
state.favoriteMovies = [];
},
},
});
Initializing the store in the server also allows you to use any WordPress API. For example, you could use the Core Translation API to translate part of your state:
When creating a directive, you might notice that its value is a string pointing to a specific state, an action, or a callback. For instance, in the example that we’ve been using in this post, the value of the data-wp-on--click directive was actions.toggle, and the value of data-wp-watch was callbacks.logIsOpen.
Those values are references to a particular property in the store. They are wired to the directives automatically so that each directive “knows” what actions.toggle refers to without any additional configuration.
When a directive is evaluated, the reference callback receives an object with:
The store containing the state, actions and callbacks.
The context (an object containing the context defined in all the wp-context ancestors).
The reference to the DOM element on which the directive was defined (a ref).
Other properties relevant to the directive. For example, the data-wp-on--click directive also receives the instance of the MouseEvent triggered by the user.
import { store, getContext, getElement } from "@wordpress/interactivity"
const { state } = store( 'wpmovies', {
state: {
theme: false,
},
actions: {
toggle: ( event ) => {
console.log(state);
// `{ "theme": false }`
const context = getContext();
console.log(context);
// `{ "isOpen": true }`
const { ref } = getElement();
console.log(ref);
// The DOM element
console.log(event);
// The Event object if using the `data-wp-on`
}
}
})
This approach enables some functionalities that make directives flexible and powerful:
Actions and callbacks can read and modify the state and the context.
Actions and callbacks can do anything a regular JavaScript function can do, like access the DOM or make API requests.
Callbacks automatically react to state changes.
How can users learn more and keep track of the API?
If you are interested in this proposal, let us know in the comments or the Interactivity API GitHub repo. Your feedback is highly appreciated. If you want to learn more about the Interactivity API, here is a list of relevant links with more information:
GitHub repo: This is where most aspects are discussed and a way to follow the development process. Feel free to open any issue, discussion, or pull request.
Movies demo repo: An example with some interactive blocks and user experiences. If you are interested in the code or even reproducing it locally, the information is gathered here.
There will be more resources in the future, including technical documentation, to explain everything in more detail.
Next steps
There will be two sessions on April 17th, 2023 (one at 08:00UTC and another at 17:00UTC) featuring a live product demo followed by a Q&A. The specifics for each session will be announced on the Make Core blogblog(versus network, site). If you’re interested in the Interactivity API, have any related questions, or want to provide feedback, feel free to join us. For those who cannot attend or prefer to share feedback in writing, comment on this post. Additionally, the session will be recorded and posted it here.
EDIT: These are the links to both sessions, where the Interactivity API is explained in more detail and answered some questions:
First session: Hosted by Michael Burridge and led by Mario Santos and Luis Herranz.
Second session: Hosted by Ryan Welcher and led by Michal Czaplinski
With this in mind, these are the next steps for the Interactivity API:
Gather and address the feedback received in the live session and this post.
Keep developing the API, incorporating the feedback.
Work on more technical documentation to explain in detail how the Interactivity API works.
Once there is enough feedback and the API feels confident enough, the intent is to add the API as an experimental feature to Gutenberg so block authors can start building with it (with the eventual goal of including it in Core).
FAQ
How does the Interactivity API work under the hood?
Its three main components are:
Preact combined with Preact Signals for hydration, client logic, and client-side navigation.
HTML Directives that can be understood by both the client and server.
There will be more technical documentation to explain the API in more detail in the future. In the meantime, please share any questions in the comments or on the GitHub repo.
Why did you choose Preact to build the directives system? Why not React or another JavaScript framework?
Preact has a number of advantages over React and other JavaScript frameworks like Vue, Svelte, or Solid in the context of the frontend (which is the focus of the Interactivity API):
It’s performant (even more when used with signals).
It’s compatible with React (through preact/compat, useful to share the same Editor components for some use cases where SSR is not important, and the components are very complex, like an e-commerce cart and checkout, for example).
It’s HTML-friendly (unlike React).
It gives us DOM diffing out of the box.
It’s extremely extensible through their Option Hooks. They use that extensibility for the hooks (preact/hooks), compatibility with React (preact/compat) and their signals (@preact/signals). Basically, everything but the DOM diffing algorithm.
Its core team has been great and very helpful. They are also interested in enhancing this “island-based” usage of Preact.
Is Gutenberg going to move from React to Preact since the Interactivity API uses it?
No. At the moment, there are no plans to make that transition. The requirements and advantages of the editor, as a fully interactive application, are quite different. Preact does have a @preact/compat package that enables full compatibility with the React ecosystem, and many large web applications use it. However, using Preact in the block editor would not offer advantages like it does on the frontend in the Interactivity API.
What approaches have been considered instead of using directives?
Many alternative approaches were considered. Here’s a brief summary of some of them:
React and other JavaScript frameworks
React was considered first because Gutenberg developers are familiar with it. Other popular JS frameworks like Svelte, Vue.js, or Angular were also considered, but none of them (including React) are PHP-friendly or compatible with WordPress hooks or internationalization. See above for a longer explanation.
Alpine.js
Alpine.js is a great framework, and it inspired a lot of functionality in the Interactivity API. However, it doesn’t support server-side rendering of its directives, and having a similar system tailored for WordPress blocks has many benefits.
The possibility of creating a DSL for writing interactive templates was also researched. The code written in that Template DSL would then be compiled into both JavaScript and PHP. However, creating a production-grade Template compiler is complex and would be a large and risky investment of effort. This approach is still being considered for the future, with the directives serving as a compilation target.
Why should I, as a block developer, use the Interactivity API rather than React?
Using React on the frontend doesn’t work smoothly with server rendering in PHP. Every approach that uses React to render blocks has to load content using client-side JavaScript. If you only render your blocks on the client, it typically results in a poor user experience because the user stares at empty placeholders and spinners while waiting for content to load.
Now, it’s possible to server-render a block in PHP and use React to render the same block on the frontend. However, this results in a poor developer experience because the logic has to be duplicated across the PHP and React parts. Not only that, but you have now exposed yourself to subtle bugs caused by WordPress hooks!
Imagine installing a third-party plugin with a hook (filterFilterFilters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output.) that modifies the server-rendered HTML. Let’s say this filter adds a single CSSCSSCascading Style Sheets. class to your block’s HTML. That CSS class will be present in the server-rendered markup. On the frontend, your block will render again in React, but now the content will not include that CSS class because there is no way to apply WordPress hooks to React-rendered content!
On the other hand, the Interactivity API is designed to work perfectly with WordPress hooks because directives enhance the server-rendered HTML with behaviors. This also means it works out of the box with WordPress backend APIs like i18ni18nInternationalization, or the act of writing and preparing code to be fully translatable into other languages. Also see localization. Often written with a lowercase i so it is not confused with a lowercase L or the numeral 1. Often an acquired skill..
To summarize, using the Interactivity API rather than just using React comes with these benefits:
If you use React, your interactive blocks must generate the same markup on the client as they do on the server in PHP. Using the Interactivity API, there is no such requirement as directives are added to server-rendered HTML.
The Interactivity API is PHP-friendlier. It works out of the box with WordPress hooks or other server functionalities such as internationalization. For example, with React, you can’t know which hooks are applied on the server, and their modifications would be overwritten after hydration.
What are the benefits of Interactivity API over just using jQuery or vanilla JavaScript?
The main difference is that the Interactivity API is declarative and reactive, so writing and maintaining complex interactive experiences should become way easier. Additionally, it has been specially designed to work with blocks, providing a standard that comes with the benefits mentioned above, like inter-block communication, compatibility, or site-wide features such as client-side navigation.
Finally, comparing it with jQuery, the Interactivity API runtime is ~10kb, which is much more lightweight. Actually, there is an ongoing effort to remove heavy frameworks like jQuery across the WordPress ecosystem, and this would help in this regard.
Do I need to know React, PHP, and this new Interactivity API?
If you want to add frontend interactivity to your blocks using this API, the short answer is yes. If your block is not interactive, the block creation workflow will remain exactly the same.
As mentioned in the post, this API only adds a new standard way to easily add frontend interactivity to blocks, which didn’t exist until now. This means that you will still need to use React to handle the editor part of your blocks.
In the future, we’d like to explore the possibility of expanding the usage of directives to unify the developer experience among the Editor as well.
On the other hand, if you want to create an interactive block, with the Interactivity API you don’t have to deal with complex topics like tooling, integration with WordPress, inter-block communication, or the server-side rendering of the interactive parts.
Does this mean I must migrate all my interactive blocks to use this API?
No. Blocks outside the Interactivity API can coexist with blocks using it. However, as explained above, keep in mind that there are some benefits for blocks that use the API:
Blocks can communicate with each other easily. With a standard, this communication is handled by default. When different blocks use different approaches to frontend interactivity, inter-block communication becomes more complex and gets almost impossible when separate developers create blocks.
Composability and compatibility: You can combine interactive blocks, nest them in structures with defined behaviors, and, thanks to following the same standard, they are fully cross-compatible. If each block were to use a different approach to interactivity, they would likely break.
Fewer KBs will be sent to the browser. If each plugin author uses a different JS framework, more code will be loaded in the frontend. If all the blocks use the same one, the code is reused.
If all the blocks on a page use this standard, site-wide features like client-side navigation can be enabled.
What are the performance implications of using this API? Is it worth loading the Interactivity API for very simple use cases?
The API has been designed with performance in mind, so it shouldn’t be a problem:
The runtime code needed for the directives is just ~10 KB, and it only needs to be loaded once for all the blocks.
It only loads the directives needed by the blocks present on the page. For example, if no blocks use data-wp-show, that directive won’t be loaded.
All the scripts that belong to the Interactivity API (including the `view.js` files) will load without blocking the page rendering.
There are ongoing explorations about the possibility of delaying the scripts loading once the block is in the viewport. This way, the initial load would be optimized without affecting the user experience.
Can I use directives in the block editor?
No. Right now, directives only work in the frontend of blocks. However, it’ll be investigated whether some directives (and also your custom directives) could be reused across the frontend and the editor. It’s worth emphasizing that the realities of the editor application and the frontend of a website are very different, particularly around the interactivity they afford. It needs to be ensured that the right tools are built for the right context. An interesting area to explore further would be to expose directives in the editor so users and builders can use them to attach behaviors to their sites on demand.
Does it work with the Core Translation API?
It does! As the Interactivity API works perfectly with server-side rendering, you can use all the WordPress APIs including __() and _e(). You can use it to translate the text in the HTML (as you normally would) and even use it inside the store when using wp_initial_state() on the server side. It might look something like this:
Before testing, bear in mind that the Interactivity API is still experimental and very likely to change before an official release. There are still missing functionalities that may break your site, and the API hasn’t been documented yet properly. If you plan to use it, do so at your own risk.
If you want to test the Interactivity API, you can install the latest version of the plugin on your site. Note that it requires the latest version of Gutenberg to work. Once installed, you can start creating interactive blocks using the API.
If you prefer to test the Interactivity API in a demo site with some interactive blocks already in place, you can look at the WP Movies demo.
How can interactive blocks update/save the state on the server?
It is still an active area of research, but is on the roadmap for the Interactivity API. For example, there’s an ongoing experiment to create an interactive version of the Comments Form block that can persist comments on the site and refresh itself without a full page reload.
Is it going to be a plugin? Or will it be part of Gutenberg/Core?
Although it is now distributed as a plugin, it aims to be added as an experimental feature to Gutenberg. The goal is to include it in Core once enough feedback has been gathered, and it’s clear that it’s the right direction.
I’m concerned about XSS; can JavaScript be injected into directives?
No. The Interactivity API only allows for References to be passed as values to the directives. This way, there is no need to eval() full JavaScript expressions, so it’s not possible to perform XSS attacks.
Does this work with CSP?
Yes. The Interactivity API does not use eval() or the Function() constructor, so it doesn’t violate the unsafe-eval content security policy. It is also designed to work with any custom content security policy.
Can you use directives to make AJAX/REST-API requests?
Sure. Actions and callbacks called by directives can do anything a JavaScript function can, including making API requests.
As mentioned during the post, it’d be great to hear your thoughts and new ideas in the GitHub repo.
Special props to @czapla , who coauthored this blog post with me from the start, and to @kristastevens for her invaluable help in shaping the document and ensuring everything was cohesive.
Over the last ten months, a group of contributorshas been working on a way to make it easier to build interactive blocks. These plans were first made public in the Exploration to enable better Developer and Visitor Experiences with blocks post, and the work they’ve been doing since then has been shared publicly in this GitHub repository. Additionally, @poliuk, who has been involved in this exploratory work, presented a talk sharing the group’s vision of the future of WordPress frontend at WordCampWordCampWordCamps are casual, locally-organized conferences covering everything related to WordPress. They're one of the places where the WordPress community comes together to teach one another what they’ve learned throughout the year and share the joy. Learn more. Europe, held in June 2022 in Porto.
As stated in this post from April, these are some of the questions that have been explored:
How to enable a much more powerful interactive and dynamic Visitor Experience with blocks? How to have a much more delightful Developer Experience when building blocks? How to offer a standard way to create interactive blocks so blockBlockBlock is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. developers don’t have to reinvent the wheel? How to ensure the block editor takes care of performance optimizations for visitors? How to enable nice and faster page transitions with blocks?
This new update is to share with the community that there has been progress on these areas and to announce that an initial proposal that could positively impact WordPress’ DX & UXUXUser experience will be shared soon. The goal of this proposal is to create a new standard that simplifies building rich interactive web applications with WordPress using declarative and reactive programming principles.
If you can’t wait until the initial proposal gets published and are curious about the work done so far, please visit this GitHub repo.
Here’s a list of the main areas where these contributors have been working on:
WordPress Directives PluginPluginA plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party (tracking issue) by @cbravobernal, @santosguillamot, @darerodz, @luisherranz & @czapla: An installable plugin that adds a set of basic directives and client-side transitions.
Directives Hydration (tracking issue) by the same contributors: This issue tracks the work done to implement this mechanism to hydrate the DOM.
Stress testing (tracking issue) by the same contributors: This issue tracks the work done to test the performance and resilience of the Directives Hydration mechanism.
Client-side navigation of the Query LoopLoopThe Loop is PHP code used by WordPress to display posts. Using The Loop, WordPress processes each post to be displayed on the current page, and formats it according to how it matches specified criteria within The Loop tags. Any HTML or PHP code in the Loop will be processed on each post. https://codex.wordpress.org/The_Loop. block using directives (PR) by @luisherranz: An experiment to implement client-side transitions in the Query Loop block.
Replicate Navigation block using directives (PR) by @luisherranz, @santosguillamot, & @darerodz: An experiment to switch from micromodal + imperative code to declarative directives.
Stay tuned for the next update, in which they’ll explain these areas of exploration in more detail, demonstrate how they fit together, and outline the alternatives that were considered.
Meanwhile, anyone who wants to contribute will be warmly welcomed, so if you want to join in with this work and get involved, please raise your hand in the comments section below or open a conversation in this Discussion board.
– Visitor Experience: to refer to the UXUXUser experience of a final user visiting a WordPress site. – Editor Experience: to refer to the UX of a user in the blockBlockBlock is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. editor. – Block Developer Experience: to refer to the experience developers have when working to create blocks.
Blocks have been a huge improvement for the Editor Experience. Now, editors can create complex content and customize their site designs with the same technique: by using blocks. But from a development perspective, there’s still room for improvement with regard to the level of interactivity that can be enabled with blocks for the visitors of a WordPress site (Visitor Experience) and the Development Experience of creating blocks.
The general acceptance of blocks as the new WordPress data abstraction is the perfect moment to provide a standard solution to create interactive blocks.
Enable a much more powerful interactive and dynamic Visitor Experience with blocks?
Have a much more delightful Developer Experience when building blocks?
Offer a standard way to create interactive blocks so block developers don’t have to reinvent the wheel?
Ensure the block editortakes care of performance optimizations for visitors?
Enable nice and faster page transitions with blocks?
This post aims to start a conversation about these challenges and highlight them as some of the problems that need to be solved in order to achieve one of the big-picture goals for 2022: To improve the Block Developer Experience.
A better interactive and dynamic Visitor Experience with blocks
What does it mean, to have better interactive and dynamic Visitor Experiences with blocks? Let’s take some use cases as examples of things that would be great if they could be done just with blocks. Imagine (🎶) :
A form block that doesn’t trigger a page reload to display responses from the server.
A pagination block that doesn’t reload the whole page when going to “next page” and loads only the portion needed.
A learning management system (LMS) where users can interact with the content in a more dynamic way enabling a better learning experience
Create with blocks a great e-commerce experience with carts, checkouts, and product galleries that dynamically respond to the visitor interaction
The ability to create just with blocks things such as Infinite Scroll, Swipe Navigation or any other experience in the frontend you can imagine.
Let’s work together to enable these kinds of delightful Visitor Experiences by using blocks!
By working together we can create a standard way to develop blocks that enable complex and performant visitor experiences (perhaps by taking advantage of techniques such as frontend block hydration).
A better Block Developer Experience
Blocks are amazing. They are a great mechanism for writing content. And now, with Full Site Editing, the power of Blocks has reached the world of Themes, so you don’t need to know how to code to create and customize your WordPress site.
There are still challenges to solve though regarding the Block Developer Experience (“better block deprecation management” or “avoid duplication of code across JavascriptJavaScriptJavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. and PHPPHPThe web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher in order to properly render a block” are some examples of things that could be improved). It would be great if blocks could enable great Visitor experiences whilst also taking care of the complexity of modern tooling and strategies.
Let’s work together to define a standard way to create blocks that makes the development of blocks a pleasant experience.
Do you have some exploration you’d like to share with the community?
How do you think blocks could enable more powerful Visitor Experiences?
Is there any specific Visitor Experience (transitions between pages, partial hydration,…) that cannot be (easily) done with blocks that you think is missing?
How do you think the Block Development Experience could be improved?
What are the most important aspects of Block Development Experience you would like to improve?
You must be logged in to post a comment.