Docs: Interactivity API : New pages - About and FAQ #61323
Conversation
juanmaguitar
requested review from
ajitbohra,
ryanwelcher,
fabiankaegy and
ndiego
as code owners
|
The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
juanmaguitar
added
[Type] Developer Documentation
| - 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). |
There was a problem hiding this comment.
I'm not sure what this means, maybe this could link to context or be removed.
There was a problem hiding this comment.
I agree on removing these ones.
- We don't support components yet.
- We should not talk about performance without metrics.
- It's battle tested is not so important, as being in Core means already that.
There was a problem hiding this comment.
Thanks for the feedback.
I have removed these points 👍
| 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. |
There was a problem hiding this comment.
The Interactivity API is not limited to blocks. That may be where it's most often used, but I'd like to avoid assumptions that it's only for blocks. I think it's good to mention blocks, but can we also mention more general "interactive behaviors" or something general like that?
There was a problem hiding this comment.
I agree with expanding the Interactivity API's use case beyond blocks, but I would still prioritize the focus on blocks as the best way to get people started with the Interactivity API.
That may be where it's most often used, but I'd like to avoid assumptions that it's only for blocks.
I would keep the mentions of blocks to ease the transition, but I would also introduce the idea of the Interactivity API's capacity to work beyond blocks. This could be another good FAQ 😊
Right now, there are no major use cases for the Interactivity API outside a block, and focusing on blocks helps developers better understand and start using it.
There was a problem hiding this comment.
@sirreal I have added the question, "Can the Interactivity API be used beyond a block?" to the FAQ.
Please let me know your thoughts.
| 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. |
There was a problem hiding this comment.
I'm not sure, but I don't think this is accurate. @DAreRodz maybe you can confirm?
At any rate, directives are trivially small. The kind of benefit you'd get from skipping a single directive probably isn't worth it.
Maybe we just remove this bullet point.
There was a problem hiding this comment.
I could not find directives being loaded conditionally too.
There was a problem hiding this comment.
I think it was included in the original proposal post as an idea to improve performance if necessary. Additionally, it could become an "issue" if creating custom directives was allowed.
I agree that, as custom directives aren't enabled yet, and this improvement hasn't been implemented, we can remove the bullet point.
| ## 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") | ||
| ), | ||
| ) ); | ||
| ``` |
There was a problem hiding this comment.
This section seems misleading. Static strings in the interactive HTML can be rendered in PHP via the Translation API, but JavaScript translations aren't really supported yet in Script Modules. https://core.trac.wordpress.org/ticket/60234
There was a problem hiding this comment.
We showcased the translation support in a WCEU. So I would keep it, but also explain how to set translatable JS strings and mention that would be improved.
There was a problem hiding this comment.
If I understand this properly, at this stage, translations within the Interactivity API are available on the server functions (PHP) but still not on the client methods (Javascript).
I have adjusted the explanation and added the following at the end of the response:
A translation API compatible with script modules (needed for the Interactivity API) is
currently being worked on. Check https://core.trac.wordpress.org/ticket/60234 to follow the progress on this work.
There was a problem hiding this comment.
For non-interactive translated texts, you can just add them in PHP.
<span><?php _e('hello'); ?></span>For interactive translated texts, you can add the strings of translated text to the state in PHP and then use them on the client side:
wp_interactivity_state('...', array(
'hello' => __('hello'),
'bye' => __('bye'),
'welcomeText' => __('hello') // initial value of derived state for SSR
));<span data-wp-text="state.welcomeText"></span>store("...", {
state: {
get welcomeText() {
return state.isUserLeaving ? state.bye : state.hello;
},
},
});What is harder to do is things like plurals, numbers and such...
| _Dynamic block example_ | ||
| ```html | ||
| <div | ||
| data-wp-interactive='{ "namespace": "wpmovies" }' |
There was a problem hiding this comment.
We can use the string form here:
| data-wp-interactive='{ "namespace": "wpmovies" }' | |
| data-wp-interactive="wpmovies" |
| data-wp-interactive='{ "namespace": "wpmovies" }' | ||
| data-wp-context="{ 'isOpen': true }" |
There was a problem hiding this comment.
Same - string-only namespace and use the wp_interactivity_data_wp_context function.
| 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. |
There was a problem hiding this comment.
This is repeated from the other page and I don't think it's accurate.
|
|
||
| - **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 was a problem hiding this comment.
It might be good to always use "script modules"
| 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). |
There was a problem hiding this comment.
It is compatible with any existing JS libraries, but it won't work out the box.
If your block uses jQuery, it won't be compatible with client side navigation. Also, if you add any event with any external library, to any element that its visibility is handled by the Interactivity API, you need to control its behaviour by your self.
There was a problem hiding this comment.
Compatibility with other blocks is mentioned in the next line. Maybe we can just remove that part from here.
Apart from that, I believe that client side navigation probably deserves a separate explanation at some point. It is a complex topic with some nuances.
There was a problem hiding this comment.
This section discusses the requirements/goals that were defined for the Interactivity API, so I think no further explanations are needed (as this is more of a wishlist). We could add links to other parts of the docs for more details and further explanations in other sections (more about specific implementations of these ideas).
I think the idea of the Interactivity API's capacity to coexist with other libraries (such as jQuery) is a powerful one that should be highlighted as it would help with its "Optional and gradual adoption" as remarked in the following point.
, I believe that client side navigation probably deserves a separate explanation at some point. It is a complex topic with some nuances.
I completely agree with this. This is already reflected in these plans for the documentation
, and a dedicated section in the Docs will be added once client-side navigation can be fully implemented with the iAPI. In the meantime I'll provide a link to #60951 to point to the progress on this work.
|
|
||
| ### 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. |
There was a problem hiding this comment.
I don't fully understand this sentence 😅
There was a problem hiding this comment.
Any suggestions for a better rephrasing?
cc: @SantosGuillamot @sirreal
There was a problem hiding this comment.
I'm not really sure, maybe "designed to integrate seamlessly with blocks"? What's the part that's problematic, @cbravobernal? I do agree, it's hard to rephrase this because I'm not sure what exactly we're trying to express here. Should we draw a parallel where blocks are HTML markups + HTML comments, and directives are just HTML attributes?
I'm not sure what PHP-friendly means, is this about server-side rendering?
|
|
||
| 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. |
There was a problem hiding this comment.
Except full client side navigation. We can add the link to the "supports.interactivity" section.
There was a problem hiding this comment.
I have added a few callouts to warn about this. Let me know what you think.
|
|
||
| ## 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: |
There was a problem hiding this comment.
Again, beware of client side navigation.
There was a problem hiding this comment.
See #61323 (comment)
|
|
||
| ## 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. |
There was a problem hiding this comment.
However, it’ll be investigated whether some directives (and also your custom directives) could be reused across the frontend and the editor.
Other folks could confirm but this doesn't look like a priority right now. Maybe it is explored at some point, but I am a bit afraid that mentioning it could cause expectations.
There was a problem hiding this comment.
I have removed this question (and answer) to avoid false expectations. If we see this is a recurrent question from the community, we can think of a better response (hopefully providing specific plans) and include it here.
Co-authored-by: Jon Surrell <[email protected]>
Co-authored-by: Carlos Bravo <[email protected]>
…Press/gutenberg into docs/interactivity-api-what-and-faq
Co-authored-by: Carlos Bravo <[email protected]>
Co-authored-by: Carlos Bravo <[email protected]>
…I be used beyond a block
…Press/gutenberg into docs/interactivity-api-what-and-faq
Co-authored-by: Jon Surrell <[email protected]>
|
@sirreal @cbravobernal @SantosGuillamot I think I have addressed all your comments and feedback in the new commits for this PR. Let me know your thoughts on this last version. |
Co-authored-by: Jon Surrell <[email protected]>
Co-authored-by: Jon Surrell <[email protected]>
…Press/gutenberg into docs/interactivity-api-what-and-faq
What?
Creates two new pages to get a deeper understanding of what the Interactivity API is or find answers to questions about this standard:
Why?
To surface some explanations "hidden" on the proposal that are really useful for new users of the Interactivity API to help them understand the reasoning behind this standard.
This PR solves #60783 among other questions
cc: @luisherranz @cbravobernal @SantosGuillamot