From 81d5d34ba25cad8faf2ee2ce1c4c4c2d8b6aeb8a Mon Sep 17 00:00:00 2001 From: Damon Cook Date: Fri, 9 Aug 2024 15:58:34 -0400 Subject: [PATCH] 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 * Update docs/reference-guides/interactivity-api/api-reference.md Co-authored-by: Luis Herranz * Update docs/reference-guides/interactivity-api/api-reference.md Co-authored-by: Luis Herranz --------- Co-authored-by: Luis Herranz --- .../interactivity-api/api-reference.md | 49 ++++++++++++++++++- 1 file changed, 48 insertions(+), 1 deletion(-) diff --git a/docs/reference-guides/interactivity-api/api-reference.md b/docs/reference-guides/interactivity-api/api-reference.md index a4b400b8c0276b..29ec67cc17507f 100644 --- a/docs/reference-guides/interactivity-api/api-reference.md +++ b/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.