From 0cf064f4a68082d6fb97c1ab41168d9180f3cc5f Mon Sep 17 00:00:00 2001 From: Carlos Bravo Date: Mon, 26 Feb 2024 15:42:56 +0100 Subject: [PATCH 1/3] Add a couple of functions to the docs --- packages/interactivity/docs/api-reference.md | 33 +++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/packages/interactivity/docs/api-reference.md b/packages/interactivity/docs/api-reference.md index d10d56390b9177..aeaea11d12fea1 100644 --- a/packages/interactivity/docs/api-reference.md +++ b/packages/interactivity/docs/api-reference.md @@ -1014,7 +1014,7 @@ store( "myPlugin", { Retrieves a representation of the element that the action is bound to or called from. Such representation is read-only, and contains a reference to the DOM element, its props and a local reactive state. It returns an object with two keys: -##### ref +#### ref `ref` is the reference to the DOM element as an (HTMLElement)[https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement] @@ -1047,4 +1047,35 @@ The code will log: "children": ['Log'], "onclick": event => { evaluate(entry, event); } } +## 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. + +### wp_interactivity_config + +`wp_interactivity_config` allows to set or get a configuration array, referenced to a store namespace. +The configuration is also available at the client, but it is static information. + +Consider it a global setting for interactions of a site, that won't be updated on user interactions. + +An example: + +```php + wp_interactivity_config( 'myPlugin', array( 'showLikeButton' => is_user_logged_in() ) ); +``` + +### wp_interactivity_process_directives + +`wp_interactivity_process_directives` returns the updated HTML after the directives have been processed. + +It is the Core function of the Interactivity API, and is public so any HTML can be processed, regarding whether is a block or not. + +```php +$html_content = '
'; + +// Process directives in HTML content. +wp_interactivity_state( 'myPlugin', array( 'message' => 'hello world!' ) ); +$processed_html = wp_interactivity_process_directives( $html_content ); + +// output:
hello world!
``` From 4470c5da1a30f6f2afc0ff7a653b0b23e4e95fc7 Mon Sep 17 00:00:00 2001 From: Carlos Bravo Date: Mon, 26 Feb 2024 16:20:58 +0100 Subject: [PATCH 2/3] Add index, rephrasing --- packages/interactivity/docs/api-reference.md | 41 +++++++++++++++----- 1 file changed, 32 insertions(+), 9 deletions(-) diff --git a/packages/interactivity/docs/api-reference.md b/packages/interactivity/docs/api-reference.md index aeaea11d12fea1..abb015593777c5 100644 --- a/packages/interactivity/docs/api-reference.md +++ b/packages/interactivity/docs/api-reference.md @@ -40,6 +40,11 @@ DOM elements are connected to data stored in the state and context through direc - [On the client side](#on-the-client-side) - [On the server side](#on-the-server-side) - [Store client methods](#store-client-methods) + - [getContext()](#getcontext) + - [getElement()](#getelement) +- [Server Functions](#server-functions) + - [wp_interactivity_config](#wp_interactivity_config) + - [wp_interactivity_process_directives](#wp_interactivity_process_directives) ## The directives @@ -1014,11 +1019,11 @@ store( "myPlugin", { Retrieves a representation of the element that the action is bound to or called from. Such representation is read-only, and contains a reference to the DOM element, its props and a local reactive state. It returns an object with two keys: -#### ref +##### ref `ref` is the reference to the DOM element as an (HTMLElement)[https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement] -#### attributes +##### attributes `attributes` contains a (Proxy)[https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy], which adds a getter that allows to reference other store namespaces. Feel free to check the getter in the code. [Link](https://github.com/WordPress/gutenberg/blob/8cb23964d58f3ce5cf6ae1b6f967a4b8d4939a8e/packages/interactivity/src/store.ts#L70) @@ -1058,24 +1063,42 @@ The configuration is also available at the client, but it is static information. Consider it a global setting for interactions of a site, that won't be updated on user interactions. -An example: +An example of setting: ```php wp_interactivity_config( 'myPlugin', array( 'showLikeButton' => is_user_logged_in() ) ); ``` +An example of getting: + +```php + wp_interactivity_config( 'myPlugin' ); +``` + +This config can be retrieved in the client: + +```js +// view.js + +const { showLikeButton } = getConfig(); +``` + ### wp_interactivity_process_directives `wp_interactivity_process_directives` returns the updated HTML after the directives have been processed. -It is the Core function of the Interactivity API, and is public so any HTML can be processed, regarding whether is a block or not. +It is the Core function of the Interactivity API server side rendering part, and is public so any HTML can be processed, whether is a block or not. -```php -$html_content = '
'; +This code -// Process directives in HTML content. -wp_interactivity_state( 'myPlugin', array( 'message' => 'hello world!' ) ); +```php +wp_interactivity_state( 'myPlugin', array( 'greeting' => 'Hello, World!' ) ); +$html = '
'; $processed_html = wp_interactivity_process_directives( $html_content ); +echo $processed_html; +``` -// output:
hello world!
+will output: +```html +
Hello, World!
``` From 2c8b59ca9345afb918c240e7558df05b3d68a0e0 Mon Sep 17 00:00:00 2001 From: Carlos Bravo Date: Mon, 26 Feb 2024 16:26:38 +0100 Subject: [PATCH 3/3] Fix grammar --- packages/interactivity/docs/api-reference.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/interactivity/docs/api-reference.md b/packages/interactivity/docs/api-reference.md index abb015593777c5..f6f432c5a01ad1 100644 --- a/packages/interactivity/docs/api-reference.md +++ b/packages/interactivity/docs/api-reference.md @@ -1059,7 +1059,7 @@ The Interactivity API comes with handy functions on the PHP part. Apart from [se ### wp_interactivity_config `wp_interactivity_config` allows to set or get a configuration array, referenced to a store namespace. -The configuration is also available at the client, but it is static information. +The configuration is also available on the client, but it is static information. Consider it a global setting for interactions of a site, that won't be updated on user interactions. @@ -1075,7 +1075,7 @@ An example of getting: wp_interactivity_config( 'myPlugin' ); ``` -This config can be retrieved in the client: +This config can be retrieved on the client: ```js // view.js