iAPI Docs: Understanding global state, local context and derived state

[luisherranz]

What?

Following up on The Reactive and Declarative Mindset guide, this is the second guide of the new Core Concepts section of the Interactivity API, focusing on explaining the concept of state and the different types of state (global, local, and derived) used in the Interactivity API.

Why?

The Interactivity API would benefit from some guides that explain the concepts and mental models, not just from the API references.

How?

For now, I have simply added the guide as a markdown file.

The work to generate the new Core Concepts section is in the pull request for the guide for reactive and declarative mindset. So, once that pull request is merged, we can change this one to fit that format.

[SantosGuillamot]

After a first read, the guide looks amazing! 👏 I think these are key concepts to understand while using the Interactivity API and this pull request does a great job explaining them. I might be biased because I was already familiar with the terms, but I like how it is structured. I feel the explanations including "When to use X" and the different examples are really useful.

I'll try to take a deeper look once you consider it ready.

[gziolo]

Great to see this type of guide added as it will help to onboard developers. Thank you so much for working on it 👏🏻

It sounds like a good direction with the nomenclature of global state vs local context. I did the first pass with the focus on the global state and left my feedback inline. I intend to have a look at local context next, but I might have other priorities in the next days so feel free to proceed based on feedback from other contributors 😄

One thing that isn't fully clear from this guide is what are the best practices for calling wp_interactivity_state. Where devs should locate the code call, inside the main plugin file vs inside the render_callback of the block type, and what are the implications of that. That might apply to store() calls as well, when I think about it now, too.

[gziolo]

One crucial aspect that is important to clarify is the nuances of how developers should handle multiple blocks of the same type, e.g., several Image blocks rendered on the page, in contrast to how that would look like in the case where two different block types would like to share the same global state, ex. the Gallery block and the Image block set as the child, or the Navigation block and some completely custom block type that would interact with it from a completely random place on the page.

[gziolo]

For education purposes, will this magically read the value from the myPlugin namespace if there is no wp-data-interactivy="myPlugin" set higher in the HTML tree?

[luisherranz]

No, we can add data-wp-interactive to make it clearer, thanks!

[gziolo]

Was it intentional to reuse the same namespace myPlugin as in the first example for declaring server state? Later the docs state:

Lastly, all calls to the store function with the same namespace are merged together:

In effect, I was wondering if at this moment I should assume that the store contains:

• counter, shown, example - wp_interactivity_state firs call
• isLoading - store first call
• someValue - wp_interactivity_state second call
• otherValue - store second call

[luisherranz]

Maybe it's not very clear. I'll think it over about the example in this guide. Thanks!

[gziolo]

What is the same object in this context? It would help to clarify it further.

[luisherranz]

Ok, I'll try to improve it, thanks!

[gziolo]

It's getting confusing to see the same namespace myPlugin referenced again. What would be the recommendation for plugin authors when picking the namespace name? Should they use one for their plugin, split by block types?

[luisherranz]

I want to create a specific guide that explains namespaces and scope.

[gziolo]

What alternatives are there to explain the idea of a derived state with the first example presented? I often saw something similar to the following:

Suggested change

	wp_interactivity_state( 'myPlugin', array(
	'counter' => 1, // This is global state.
	'double' => 2, // This is derived state.
	));
	$counter = 1;
	wp_interactivity_state( 'myPlugin', array(
	'counter' => $counter, // This is global state.
	'double' => 2 * $counter, // This is derived state.
	));

When placing the value, it isn't immediately clear that double is computed from other entries in the state.

[luisherranz]

Good suggestion. I will apply it to the guide. Thank you!

[jffng]

In general this helped my understanding of global state, local context, and derived state. I was able to clean up the store of something I'm working on and feel more confident in the implementation, after reading this guide.

[jffng]

Why typically? Because you often depend on values from the server (e.g. block attributes) to calculate the initial values of state?

[luisherranz]

I have created a specific guide to explain server-side rendering and how directives are processed on the server. It's part of this PR:

• iAPI Docs: The first three Core Concepts guides #63759

Hopefully, it will answer your question.

(Feedback welcomed on that guide too 😄)

[jffng]

To me, this is the key difference between derived vs global state, and could be presented much earlier in the guide. That could just be how I learn though.

[luisherranz]

Alright, I'll take a look to see if it can be mentioned earlier. Thanks, Jeff!

[luisherranz]

I am closing this pull request in favor of this one where I have merged this guide with the other two initial guides:

• iAPI Docs: The first three Core Concepts guides #63759