From f86cd76f2d07eeb4c67e3814ff44900db76925f9 Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Thu, 2 May 2024 13:26:56 +0100 Subject: [PATCH 01/18] new pages - about and faq --- docs/manifest.json | 12 ++ .../interactivity-api/README.md | 5 + .../interactivity-api/iapi-about.md | 191 ++++++++++++++++++ .../interactivity-api/iapi-faq.md | 129 ++++++++++++ docs/toc.json | 6 + 5 files changed, 343 insertions(+) create mode 100644 docs/reference-guides/interactivity-api/iapi-about.md create mode 100644 docs/reference-guides/interactivity-api/iapi-faq.md diff --git a/docs/manifest.json b/docs/manifest.json index 05f1f36ce7ca63..a2577530463555 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -509,6 +509,18 @@ "markdown_source": "../docs/reference-guides/interactivity-api/api-reference.md", "parent": "interactivity-api" }, + { + "title": "About the Interactivity API", + "slug": "iapi-about", + "markdown_source": "../docs/reference-guides/interactivity-api/iapi-about.md", + "parent": "interactivity-api" + }, + { + "title": "Frequently Asked Questions", + "slug": "iapi-faq", + "markdown_source": "../docs/reference-guides/interactivity-api/iapi-faq.md", + "parent": "interactivity-api" + }, { "title": "SlotFills Reference", "slug": "slotfills", diff --git a/docs/reference-guides/interactivity-api/README.md b/docs/reference-guides/interactivity-api/README.md index de6b0c5b1c4558..3cc9534bc68cbf 100644 --- a/docs/reference-guides/interactivity-api/README.md +++ b/docs/reference-guides/interactivity-api/README.md @@ -22,6 +22,11 @@ Use the following links to locate the topic you're interested in. If you have ne - **[API Reference](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/api-reference/):** To take a deep dive into how the API works internally, the list of Directives, and how Store works. - **[Docs and Examples](#docs--examples):** Additional resources to learn/read more about the Interactivity API. +To get a deeper understanding of what the Interactivity API is or find answers to questions you may have about this standard, check the following resources: +- **[About the Interactivity API](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/iapi-about/):** To learn more about the API Goals and the reasoning behind the use of a standard to add interactivity to blocks. +- **[Frequently Asked Questions](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/iapi-faq/):** To find responses to some frequently asked questions about the technology behind and alternatives. + + ## Requirements of the Interactivity API Interactivity API is included in Core in WordPress 6.5. For versions below, you'll need Gutenberg 17.5 or higher installed and activated in your WordPress installation. diff --git a/docs/reference-guides/interactivity-api/iapi-about.md b/docs/reference-guides/interactivity-api/iapi-about.md new file mode 100644 index 00000000000000..10a51f86816628 --- /dev/null +++ b/docs/reference-guides/interactivity-api/iapi-about.md @@ -0,0 +1,191 @@ +# About the Interactivity API + +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](https://alpinejs.dev/), it’s a similar approach but explicitly designed to work seamlessly with WordPress. + +## API Goals + +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 the following requirements/goals for the Interactivity 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 HTML 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 hooks, 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. +- **Extensible**: 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. + +## Why directives? + +Directives are the result of deep [research into different possibilities and approaches](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/iapi-faq/#what-approaches-have-been-considered-instead-of-using-directives). We’ve found that this design covers the requirements most effectively. + +### Block-first and PHP-friendly + +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_ +```html +
+ + +

+ This element is now visible! +

+
+``` + +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. +- **Core Translation 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 enhancement** 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 UI 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_ + +```html + +

This element is now visible!

+ +``` + +_Declarative code_ + +This is the same use case shared above but serves as an example of declarative code using this new system. The JavaScript logic is defined in the `view.js` file of the block, and add the directives to the markup in the `render.php`. + +```js +// view.js file + +import { store, getContext } from "@wordpress/interactivity"; + +store( 'wpmovies', { + actions: { + toggle: () => { + const context = getContext(); + context.isOpen = !context.isOpen; + }, + }, +}); +``` + +```php + + +
+ + +

+ This element is now visible! +

+
+``` + +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](https://developer.wordpress.org/reference/hooks/render_block/) 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`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-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](https://developer.chrome.com/docs/web-platform/view-transitions/) 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 front end. 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_ + +Two columns table comparing some aspects with and without a standard. Without a standard, block developers have to take care of everything, while having a standard. Totally handled by the standard: Tooling, hydration, integrating it with WordPress, SSR of the interactive parts, inter-block communication, and frontend performance. Partially handled: Security, accessibility, and best practices. Developer responsibility: Block logic. In the without a standard column, everything is under the developer responsability. + + +With this absorption, less knowledge is required to create interactive blocks, and developers have fewer decisions to worry about. + +By adopting a standard, learning from other interactive blocks is simpler, and fosters collaboration and code reusability. As a result, the development process is leanier and friendlier to less experienced developers. + diff --git a/docs/reference-guides/interactivity-api/iapi-faq.md b/docs/reference-guides/interactivity-api/iapi-faq.md new file mode 100644 index 00000000000000..3d477d01adcf5f --- /dev/null +++ b/docs/reference-guides/interactivity-api/iapi-faq.md @@ -0,0 +1,129 @@ +# Frequently Asked Questions + +## How does the Interactivity API work under the hood? + +Its three main components are: + +- [Preact](https://preactjs.com/) combined with [Preact Signals](https://preactjs.com/guide/v10/signals/) for hydration, client logic, and client-side navigation. +- HTML Directives that can be understood by both the client and server. +- Server-side logic, handled by the [HTML_Tag_Processor](https://make.wordpress.org/core/2023/03/07/introducing-the-html-api-in-wordpress-6-2/). + +## Why 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 small: 8kB, including [hooks](https://preactjs.com/guide/v10/hooks/) and [signals](https://preactjs.com/blog/introducing-signals/). +- It’s battle-tested. +- 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`](https://preactjs.com/guide/v10/switching-to-preact/) 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. + +### 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](https://github.com/alpinejs/alpine/tree/d7f9d641f7a763c56c598d118bd189a406a22383/packages/docs/src/en/directives), and having a similar system tailored for WordPress blocks has many benefits. + +### Plain JavaScript + +See the answer below. + +### Template DSL + +The possibility of creating a [DSL](https://en.wikipedia.org/wiki/Domain-specific_language) 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. + +Using JS in PHP extensions (like v8js) is also possible, but unfortunately PHP extensions are not backward compatible and can only be used when there's a PHP fallback. + +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 (filter) that modifies the server-rendered HTML. Let’s say this filter adds a single CSS 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 i18n. + +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. +- All the benefits of [using a standard](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/what-is-interactivity-api#why-a-standard). + + +## 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. + +This API only adds a new standard way to easily add frontend interactivity to blocks. This means that you still need to use React to handle the editor part of your blocks. + +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 [`__()`](https://developer.wordpress.org/reference/functions/__/) and [`_e()`](https://developer.wordpress.org/reference/functions/_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: + +```php +// render.php +wp_interactivity_state( 'favoriteMovies', array( + "1" => array( + "id" => "123-abc", + "movieName" => __("someMovieName", "textdomain") + ), +) ); +``` + + +## I’m concerned about XSS; can JavaScript be injected into directives? + +No. The Interactivity API only allows for [References](https://make.wordpress.org/core/2023/03/30/proposal-the-interactivity-api-a-better-developer-experience-in-building-interactive-blocks/#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 Custom Security Policies? + +Yes. The Interactivity API does not use [`eval()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval) or the [`Function()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/Function) constructor, so it doesn’t violate the [`unsafe-eval`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#unsafe_keyword_values) content security policy. It is also designed to work with any [custom content security policy](https://developer.wordpress.org/apis/security/). + +## 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. + diff --git a/docs/toc.json b/docs/toc.json index c0ec94fd049a0d..fa80ee6c4f4404 100644 --- a/docs/toc.json +++ b/docs/toc.json @@ -209,6 +209,12 @@ }, { "docs/reference-guides/interactivity-api/api-reference.md": [] + }, + { + "docs/reference-guides/interactivity-api/iapi-about.md": [] + }, + { + "docs/reference-guides/interactivity-api/iapi-faq.md": [] } ] }, From 641c7f514e3e9f2c77c3fb2fd27b04630bf74c3f Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Mon, 6 May 2024 08:17:43 +0100 Subject: [PATCH 02/18] Can the Interactivity API be used beyond a block --- docs/reference-guides/interactivity-api/iapi-faq.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/reference-guides/interactivity-api/iapi-faq.md b/docs/reference-guides/interactivity-api/iapi-faq.md index 3d477d01adcf5f..6021f8e3031481 100644 --- a/docs/reference-guides/interactivity-api/iapi-faq.md +++ b/docs/reference-guides/interactivity-api/iapi-faq.md @@ -13,10 +13,6 @@ Its three main components are: 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 small: 8kB, including [hooks](https://preactjs.com/guide/v10/hooks/) and [signals](https://preactjs.com/blog/introducing-signals/). -- It’s battle-tested. -- 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. @@ -70,14 +66,18 @@ The main difference is that the Interactivity API is **declarative and reactive* 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? +## Do I need to know React, PHP, and this 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. -This API only adds a new standard way to easily add frontend interactivity to blocks. This means that you still need to use React to handle the editor part of your blocks. +The Interactivity API introduces a new standard method to facilitate the integration of interactive behaviors into the frontend part of WordPress. This means that you still need to use React to handle the editor part of your blocks. 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. +## Can the Interactivity API be used beyond a block? + +Absolutely, yes, it is not limited to blocks. You'll see a lot of mentions of how the Interactivity API provides a standard for creating interactive blocks, but that's only because that's the most common use case. More generally speaking, the Interactivity API standard can be used to add "interactive behaviors" to the front end of any part of WordPress. + ## 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: From dacea867ea1d9efd9a4869e6441e1bf55b8d5f2d Mon Sep 17 00:00:00 2001 From: JuanMa Date: Mon, 6 May 2024 09:22:30 +0200 Subject: [PATCH 03/18] Update docs/reference-guides/interactivity-api/iapi-about.md Co-authored-by: Jon Surrell --- docs/reference-guides/interactivity-api/iapi-about.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference-guides/interactivity-api/iapi-about.md b/docs/reference-guides/interactivity-api/iapi-about.md index 10a51f86816628..e324524156caa7 100644 --- a/docs/reference-guides/interactivity-api/iapi-about.md +++ b/docs/reference-guides/interactivity-api/iapi-about.md @@ -39,7 +39,7 @@ _Dynamic block example_ ```html
false ) ); ?> data-wp-watch="callbacks.logIsOpen" >
``` -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. +Using imperative code may be easier when creating simple user experiences, but it becomes much more difficult as applications 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 From fec3369d0a12cfbbf609e35cd749623def1ab2f3 Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Mon, 6 May 2024 09:03:40 +0100 Subject: [PATCH 09/18] replaced scripts by script modules --- docs/reference-guides/interactivity-api/iapi-faq.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference-guides/interactivity-api/iapi-faq.md b/docs/reference-guides/interactivity-api/iapi-faq.md index 4e08bc60ee0102..8a6e51740383fb 100644 --- a/docs/reference-guides/interactivity-api/iapi-faq.md +++ b/docs/reference-guides/interactivity-api/iapi-faq.md @@ -92,8 +92,8 @@ No. Blocks outside the Interactivity API can coexist with blocks using it. Howev 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. -- **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. +- **All the script modules 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 script modules loading once the block is in the viewport**. This way, the initial load would be optimized without affecting the user experience. ## Does it work with the Core Translation API? From 879758e2b4cb5b786ad5c2a0b1e2e71842d9c952 Mon Sep 17 00:00:00 2001 From: JuanMa Date: Mon, 6 May 2024 10:07:04 +0200 Subject: [PATCH 10/18] Update docs/reference-guides/interactivity-api/iapi-about.md Co-authored-by: Carlos Bravo <37012961+cbravobernal@users.noreply.github.com> --- docs/reference-guides/interactivity-api/iapi-about.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference-guides/interactivity-api/iapi-about.md b/docs/reference-guides/interactivity-api/iapi-about.md index bd7834c93ff687..bafbfd2f093d8b 100644 --- a/docs/reference-guides/interactivity-api/iapi-about.md +++ b/docs/reference-guides/interactivity-api/iapi-about.md @@ -33,7 +33,7 @@ Directives are the result of deep [research into different possibilities and app 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. +As directives are HTML attributes, they are perfect for dynamic blocks and PHP. _Dynamic block example_ ```html From 9f7ef43bd3dac155a329a63f155a39c0e1129cc2 Mon Sep 17 00:00:00 2001 From: JuanMa Date: Mon, 6 May 2024 10:07:15 +0200 Subject: [PATCH 11/18] Update docs/reference-guides/interactivity-api/iapi-about.md Co-authored-by: Carlos Bravo <37012961+cbravobernal@users.noreply.github.com> --- docs/reference-guides/interactivity-api/iapi-about.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference-guides/interactivity-api/iapi-about.md b/docs/reference-guides/interactivity-api/iapi-about.md index bafbfd2f093d8b..b0619c5b7f710f 100644 --- a/docs/reference-guides/interactivity-api/iapi-about.md +++ b/docs/reference-guides/interactivity-api/iapi-about.md @@ -67,7 +67,7 @@ As the Interactivity API works perfectly with server-side rendering, you can use ### Optional and gradual adoption -The Interactivity API pipeline promotes **progressive enhancement** 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. +The Interactivity API pipeline promotes **progressive enhancement** by building on top of WordPress’s solid foundation and patterns. 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. From c2e82f3311c303578d201cf8d3dedfe851fe9a0c Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Mon, 6 May 2024 09:14:37 +0100 Subject: [PATCH 12/18] Added wp_interactivity_process_directives to Can the Interactivity API be used beyond a block --- docs/reference-guides/interactivity-api/iapi-faq.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/reference-guides/interactivity-api/iapi-faq.md b/docs/reference-guides/interactivity-api/iapi-faq.md index 8a6e51740383fb..793dbc2b5bd090 100644 --- a/docs/reference-guides/interactivity-api/iapi-faq.md +++ b/docs/reference-guides/interactivity-api/iapi-faq.md @@ -78,6 +78,8 @@ On the other hand, if you want to create an interactive block, with the Interact Absolutely, yes, it is not limited to blocks. You'll see a lot of mentions of how the Interactivity API provides a standard for creating interactive blocks, but that's only because that's the most common use case. More generally speaking, the Interactivity API standard can be used to add "interactive behaviors" to the front end of any part of WordPress. +See the [`wp_interactivity_process_directives`](https://developer.wordpress.org/reference/functions/wp_interactivity_process_directives/) for details on using the Interactivity API outside of blocks with arbitrary HTML. + ## 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: From 37a2ef5b2aac380db3ce9510389b8f84bdc2194e Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Mon, 6 May 2024 10:27:50 +0100 Subject: [PATCH 13/18] Callouts about full site editing --- docs/reference-guides/interactivity-api/iapi-about.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/reference-guides/interactivity-api/iapi-about.md b/docs/reference-guides/interactivity-api/iapi-about.md index b0619c5b7f710f..f9e23e86ce6eaa 100644 --- a/docs/reference-guides/interactivity-api/iapi-about.md +++ b/docs/reference-guides/interactivity-api/iapi-about.md @@ -71,6 +71,10 @@ The Interactivity API pipeline promotes **progressive enhancement** by building 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. +
+ Full-page client-side navigation will be an exception to this compatibility with other libraries rule. See [Client-side navigation](#client-side-navigation) for more details. +
+ ### 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? @@ -145,9 +149,7 @@ Using imperative code may be easier when creating simple user experiences, but i 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 @@ -167,6 +169,10 @@ Using built-in directives does not require a build step and only requires a smal 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. +
+ Full-page client-side navigation with the Interactivity API is still a work in progress (see https://github.com/WordPress/gutenberg/issues/60951), but it's expected that to enable this behaviour all the interactivity required for blocks is provided with the Interactivity API Standard. Only in this case, the Interactivity API won't be fully compatible with other libraries (such as jQuery). +
+ It also pairs very well with the [View Transitions API](https://developer.chrome.com/docs/web-platform/view-transitions/) allowing developers to animate page transitions easily. ## Why a standard? From fb09fd38fa6eea7e418dd0332eb627d135b40cac Mon Sep 17 00:00:00 2001 From: JuanMa Date: Mon, 6 May 2024 11:28:33 +0200 Subject: [PATCH 14/18] Update docs/reference-guides/interactivity-api/iapi-faq.md Co-authored-by: Jon Surrell --- docs/reference-guides/interactivity-api/iapi-faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference-guides/interactivity-api/iapi-faq.md b/docs/reference-guides/interactivity-api/iapi-faq.md index 793dbc2b5bd090..e7924936d0e06b 100644 --- a/docs/reference-guides/interactivity-api/iapi-faq.md +++ b/docs/reference-guides/interactivity-api/iapi-faq.md @@ -78,7 +78,7 @@ On the other hand, if you want to create an interactive block, with the Interact Absolutely, yes, it is not limited to blocks. You'll see a lot of mentions of how the Interactivity API provides a standard for creating interactive blocks, but that's only because that's the most common use case. More generally speaking, the Interactivity API standard can be used to add "interactive behaviors" to the front end of any part of WordPress. -See the [`wp_interactivity_process_directives`](https://developer.wordpress.org/reference/functions/wp_interactivity_process_directives/) for details on using the Interactivity API outside of blocks with arbitrary HTML. +See the [`wp_interactivity_process_directives` function](https://developer.wordpress.org/reference/functions/wp_interactivity_process_directives/) for details on using the Interactivity API outside of blocks with arbitrary HTML. ## Does this mean I must migrate all my interactive blocks to use this API? From e7956f35bde41ef33f7e2d0e2b95556e6fa37a50 Mon Sep 17 00:00:00 2001 From: JuanMa Date: Mon, 6 May 2024 11:30:04 +0200 Subject: [PATCH 15/18] Update docs/reference-guides/interactivity-api/iapi-about.md Co-authored-by: Jon Surrell --- docs/reference-guides/interactivity-api/iapi-about.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference-guides/interactivity-api/iapi-about.md b/docs/reference-guides/interactivity-api/iapi-about.md index f9e23e86ce6eaa..da91ea34b14a60 100644 --- a/docs/reference-guides/interactivity-api/iapi-about.md +++ b/docs/reference-guides/interactivity-api/iapi-about.md @@ -126,7 +126,7 @@ store( 'wpmovies', {
true ) ); ?> >