Docs: Interactivity API : New pages - About and FAQ #61323

juanmaguitar · 2024-05-02T12:31:57Z

What?

Creates two new pages to get a deeper understanding of what the Interactivity API is or find answers to questions about this standard:

About the Interactivity API To learn more about the API Goals and the reasoning behind the use of a standard to add interactivity to blocks.
Frequently Asked Questions To find responses to some frequently asked questions about the technology behind and alternatives.

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

github-actions · 2024-05-02T12:32:14Z

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 props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: juanmaguitar <juanmaguitar@git.wordpress.org>
Co-authored-by: sirreal <jonsurrell@git.wordpress.org>
Co-authored-by: cbravobernal <cbravobernal@git.wordpress.org>
Co-authored-by: SantosGuillamot <santosguillamot@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

sirreal

I've left a bunch of feedback, but I'll leave final reviews for the other folks you mentioned who are better informed than I am.

sirreal · 2024-05-03T12:35:55Z

docs/reference-guides/interactivity-api/iapi-faq.md

+- 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).


I'm not sure what this means, maybe this could link to context or be removed.

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.

Thanks for the feedback.
I have removed these points 👍

sirreal · 2024-05-03T12:41:22Z

docs/reference-guides/interactivity-api/iapi-faq.md

+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 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?

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.

@sirreal I have added the question, "Can the Interactivity API be used beyond a block?" to the FAQ.
Please let me know your thoughts.

sirreal · 2024-05-03T12:43:22Z

docs/reference-guides/interactivity-api/iapi-faq.md

+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.


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.

I could not find directives being loaded conditionally too.

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.

Removed! 👍

sirreal · 2024-05-03T12:46:27Z

docs/reference-guides/interactivity-api/iapi-faq.md

+## 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")
+      ),
+) );
+```


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

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.

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.

sirreal · 2024-05-03T12:50:57Z

docs/reference-guides/interactivity-api/iapi-about.md

+_Dynamic block example_
+```html
+<div
+  data-wp-interactive='{ "namespace": "wpmovies" }'


We can use the string form here:

Suggested change

data-wp-interactive='{ "namespace": "wpmovies" }'

data-wp-interactive="wpmovies"

docs/reference-guides/interactivity-api/iapi-about.md

sirreal · 2024-05-03T12:53:14Z

docs/reference-guides/interactivity-api/iapi-about.md

+  data-wp-interactive='{ "namespace": "wpmovies" }'
+  data-wp-context="{ 'isOpen': true }"


Same - string-only namespace and use the wp_interactivity_data_wp_context function.

docs/reference-guides/interactivity-api/iapi-about.md

sirreal · 2024-05-03T12:54:55Z

docs/reference-guides/interactivity-api/iapi-about.md

+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.


This is repeated from the other page and I don't think it's accurate.

sirreal · 2024-05-03T12:55:45Z

docs/reference-guides/interactivity-api/iapi-about.md

+
+- **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**.


It might be good to always use "script modules"

cbravobernal · 2024-05-05T21:02:08Z

docs/reference-guides/interactivity-api/iapi-about.md

+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).


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.

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.

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.

cbravobernal · 2024-05-05T21:03:26Z

docs/reference-guides/interactivity-api/iapi-about.md

+
+### 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.


I don't fully understand this sentence 😅

Any suggestions for a better rephrasing?
cc: @SantosGuillamot @sirreal

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?

docs/reference-guides/interactivity-api/iapi-about.md

cbravobernal · 2024-05-05T21:06:46Z

docs/reference-guides/interactivity-api/iapi-about.md

+
+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.


Except full client side navigation. We can add the link to the "supports.interactivity" section.

I have added a few callouts to warn about this. Let me know what you think.

cbravobernal · 2024-05-05T21:08:22Z

docs/reference-guides/interactivity-api/iapi-about.md

+
+## 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:


Again, beware of client side navigation.

See #61323 (comment)

docs/reference-guides/interactivity-api/iapi-about.md

SantosGuillamot · 2024-05-06T07:20:46Z

docs/reference-guides/interactivity-api/iapi-faq.md

+
+## 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.


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.

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 <sirreal@users.noreply.github.com>

Co-authored-by: Carlos Bravo <37012961+cbravobernal@users.noreply.github.com>

…Press/gutenberg into docs/interactivity-api-what-and-faq

docs/reference-guides/interactivity-api/iapi-faq.md

Co-authored-by: Jon Surrell <sirreal@users.noreply.github.com>

Co-authored-by: Carlos Bravo <37012961+cbravobernal@users.noreply.github.com>

…I be used beyond a block

…Press/gutenberg into docs/interactivity-api-what-and-faq

docs/reference-guides/interactivity-api/iapi-about.md

docs/reference-guides/interactivity-api/iapi-faq.md

Co-authored-by: Jon Surrell <sirreal@users.noreply.github.com>

juanmaguitar · 2024-05-06T09:29:50Z

@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 <sirreal@users.noreply.github.com>

sirreal

This seems good to me when you're satisfied. Thanks!

…Press/gutenberg into docs/interactivity-api-what-and-faq

new pages - about and faq

f86cd76

juanmaguitar requested review from ajitbohra, ryanwelcher, fabiankaegy and ndiego as code owners May 2, 2024 12:31

juanmaguitar added [Type] Developer Documentation Documentation for developers [Feature] Interactivity API API to add frontend interactivity to blocks. labels May 2, 2024

sirreal reviewed May 3, 2024

View reviewed changes

sirreal requested review from DAreRodz and cbravobernal May 3, 2024 12:56

cbravobernal reviewed May 5, 2024

View reviewed changes

docs/reference-guides/interactivity-api/iapi-about.md Outdated Show resolved Hide resolved

cbravobernal reviewed May 5, 2024

View reviewed changes

docs/reference-guides/interactivity-api/iapi-about.md Outdated Show resolved Hide resolved

cbravobernal reviewed May 5, 2024

View reviewed changes

docs/reference-guides/interactivity-api/iapi-about.md Outdated Show resolved Hide resolved

Can the Interactivity API be used beyond a block

641c7f5

SantosGuillamot reviewed May 6, 2024

View reviewed changes

juanmaguitar and others added 6 commits May 6, 2024 09:22

Update docs/reference-guides/interactivity-api/iapi-about.md

dacea86

Co-authored-by: Jon Surrell <sirreal@users.noreply.github.com>

Adjustments based on feedback on the PR

ca7cb29

merge changes

c490333

Update docs/reference-guides/interactivity-api/iapi-about.md

489a8ee

Co-authored-by: Carlos Bravo <37012961+cbravobernal@users.noreply.github.com>

Removed use directives in the block editor

022e3b8

Merge branch 'docs/interactivity-api-what-and-faq' of github.com:Word…

cbdc530

…Press/gutenberg into docs/interactivity-api-what-and-faq

sirreal reviewed May 6, 2024

View reviewed changes

docs/reference-guides/interactivity-api/iapi-faq.md Show resolved Hide resolved

juanmaguitar and others added 3 commits May 6, 2024 08:47

Translation API with the iAPI

883785f

Update docs/reference-guides/interactivity-api/iapi-about.md

072e8b0

Co-authored-by: Jon Surrell <sirreal@users.noreply.github.com>

replaced scripts by script modules

fec3369

juanmaguitar and others added 4 commits May 6, 2024 10:07

Update docs/reference-guides/interactivity-api/iapi-about.md

879758e

Co-authored-by: Carlos Bravo <37012961+cbravobernal@users.noreply.github.com>

Update docs/reference-guides/interactivity-api/iapi-about.md

9f7ef43

Co-authored-by: Carlos Bravo <37012961+cbravobernal@users.noreply.github.com>

Added wp_interactivity_process_directives to Can the Interactivity AP…

c2e82f3

…I be used beyond a block

Merge branch 'docs/interactivity-api-what-and-faq' of github.com:Word…

9a03279

…Press/gutenberg into docs/interactivity-api-what-and-faq

sirreal reviewed May 6, 2024

View reviewed changes

docs/reference-guides/interactivity-api/iapi-about.md Outdated Show resolved Hide resolved

sirreal reviewed May 6, 2024

View reviewed changes

docs/reference-guides/interactivity-api/iapi-faq.md Outdated Show resolved Hide resolved

juanmaguitar and others added 2 commits May 6, 2024 10:27

Callouts about full site editing

37a2ef5

Update docs/reference-guides/interactivity-api/iapi-faq.md

fb09fd3

Co-authored-by: Jon Surrell <sirreal@users.noreply.github.com>

juanmaguitar and others added 2 commits May 6, 2024 11:30

Update docs/reference-guides/interactivity-api/iapi-about.md

e7956f3

Co-authored-by: Jon Surrell <sirreal@users.noreply.github.com>

Update docs/reference-guides/interactivity-api/iapi-about.md

37b1b84

Co-authored-by: Jon Surrell <sirreal@users.noreply.github.com>

juanmaguitar requested review from sirreal, cbravobernal and SantosGuillamot May 6, 2024 09:32

sirreal approved these changes May 6, 2024

View reviewed changes

juanmaguitar added 3 commits May 6, 2024 11:31

better phrasing for client-side navigation exception

9568bf8

Merge branch 'docs/interactivity-api-what-and-faq' of github.com:Word…

6e7023d

…Press/gutenberg into docs/interactivity-api-what-and-faq

added link to ongoing explorations for scripts loading delay

0b6a8f9

juanmaguitar enabled auto-merge (squash) May 6, 2024 10:39

juanmaguitar merged commit 2df24b3 into trunk May 6, 2024
60 checks passed

juanmaguitar deleted the docs/interactivity-api-what-and-faq branch May 6, 2024 11:13

github-actions bot added this to the Gutenberg 18.4 milestone May 6, 2024

This was referenced May 6, 2024

Docs: Interactivity Api - Small fixes #61403

Merged

Docs: Interactivity API - Shape a section in the docs providing a full response to the question "Why it's not possible to just use React?" #60783

Closed

Directory

Docs: Interactivity API : New pages - About and FAQ #61323

Docs: Interactivity API : New pages - About and FAQ #61323

Conversation

juanmaguitar commented May 2, 2024 • edited

What?

Why?

github-actions bot commented May 2, 2024 • edited

sirreal left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

juanmaguitar May 6, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

juanmaguitar May 6, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cbravobernal May 5, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

juanmaguitar May 6, 2024 • edited

Choose a reason for hiding this comment

juanmaguitar commented May 6, 2024

sirreal left a comment

Choose a reason for hiding this comment

juanmaguitar commented May 2, 2024 •

edited

github-actions bot commented May 2, 2024 •

edited

juanmaguitar May 6, 2024 •

edited

juanmaguitar May 6, 2024 •

edited

cbravobernal May 5, 2024 •

edited

juanmaguitar May 6, 2024 •

edited