Docs: Interactivity API: Add wp_interactivity_state() clarification (#…

…64356)

* Add wp_interactivity_state() clarification

* Update code example for wp_interactivity_state

* Update docs/reference-guides/interactivity-api/api-reference.md

Co-authored-by: Luis Herranz <[email protected]>

* Update docs/reference-guides/interactivity-api/api-reference.md

Co-authored-by: Luis Herranz <[email protected]>

* Update docs/reference-guides/interactivity-api/api-reference.md

Co-authored-by: Luis Herranz <[email protected]>

---------

Co-authored-by: Luis Herranz <[email protected]>

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

@@ -1152,7 +1152,7 @@ store('mySliderPlugin', {
 
 ## Server functions
 
-The Interactivity API comes with handy functions on the PHP part. Apart from [setting the store via server](#on-the-server-side), there is also a function to get and set Interactivity related config variables.
+The Interactivity API comes with handy functions that allow you to initialize and reference configuration options on the server. This is necessary to feed the initial data that the Server Directive Processing will use to modify the HTML markup before it's send to the browser. It is also a great way to leverage many of WordPress's APIs, like nonces, AJAX, and translations.
 
 ### wp_interactivity_config
 
@@ -1181,6 +1181,53 @@ This config can be retrieved on the client:
 const { showLikeButton } = getConfig();
 ```
 
+### wp_interactivity_state
+
+`wp_interactivity_state` allows the initialization of the global state on the server, which will be used to process the directives on the server and then will be merged with any global state defined in the client.
+
+Initializing the global state on the server also allows you to use many critical WordPress APIs, including [AJAX](https://developer.wordpress.org/plugins/javascript/ajax/), or [nonces](https://developer.wordpress.org/plugins/javascript/enqueuing/#nonce).
+
+The `wp_interactivity_state` function receives two arguments, a string with the namespace that will be used as a reference and an associative array containing the values.
+
+Here is an example of passing the WP Admin AJAX endpoint with a nonce.
+
+```php
+// render.php
+
+wp_interactivity_state(
+	'myPlugin',
+	array(
+		'ajaxUrl' => admin_url( 'admin-ajax.php' ),
+		'nonce'   => wp_create_nonce( 'myPlugin_nonce' ),
+	),
+);
+```
+
+```js
+// view.js
+
+const { state } = store( 'myPlugin', {
+	actions: {
+		*doSomething() {
+			try {
+				const formData = new FormData();
+				formData.append( 'action', 'do_something' );
+				formData.append( '_ajax_nonce', state.nonce );
+
+				const data = yield fetch( state.ajaxUrl, {
+					method: 'POST',
+					body: formData,
+				} ).then( ( response ) => response.json() );
+					console.log( 'Server data!', data );
+				} catch ( e ) {
+					// Something went wrong!
+				}
+			},
+		},
+	}
+);
+```
+
 ### wp_interactivity_process_directives
 
 `wp_interactivity_process_directives` returns the updated HTML after the directives have been processed.