From c3d8a4b8937bc53239bacc7a23aba853e8d912bc Mon Sep 17 00:00:00 2001 From: Carlos Bravo <37012961+c4rl0sbr4v0@users.noreply.github.com> Date: Thu, 29 Feb 2024 14:03:46 +0100 Subject: [PATCH] Rename data_wp_context_function (#59465) Co-authored-by: c4rl0sbr4v0 Co-authored-by: DAreRodz Co-authored-by: swissspidy --- .../interactivity-api/interactivity-api.php | 6 +- .../block-library/src/navigation/index.php | 2 +- packages/block-library/src/search/index.php | 2 +- .../interactivity/docs/2-api-reference.md | 147 ++++++++++++++++++ 4 files changed, 152 insertions(+), 5 deletions(-) diff --git a/lib/compat/wordpress-6.5/interactivity-api/interactivity-api.php b/lib/compat/wordpress-6.5/interactivity-api/interactivity-api.php index 395aece766cb65..adbfb0e1800a03 100644 --- a/lib/compat/wordpress-6.5/interactivity-api/interactivity-api.php +++ b/lib/compat/wordpress-6.5/interactivity-api/interactivity-api.php @@ -151,7 +151,7 @@ function wp_interactivity_config( string $store_namespace, array $config = array } } -if ( ! function_exists( 'data_wp_context' ) ) { +if ( ! function_exists( 'wp_interactivity_data_wp_context' ) ) { /** * Generates a `data-wp-context` directive attribute by encoding a context * array. @@ -162,7 +162,7 @@ function wp_interactivity_config( string $store_namespace, array $config = array * * Example: * - *
true, 'count' => 0 ) ); ?>> + *
true, 'count' => 0 ) ); ?>> * * @since 6.5.0 * @@ -171,7 +171,7 @@ function wp_interactivity_config( string $store_namespace, array $config = array * @return string A complete `data-wp-context` directive with a JSON encoded value representing the context array and * the store namespace if specified. */ - function data_wp_context( array $context, string $store_namespace = '' ): string { + function wp_interactivity_data_wp_context( array $context, string $store_namespace = '' ): string { return 'data-wp-context=\'' . ( $store_namespace ? $store_namespace . '::' : '' ) . ( empty( $context ) ? '{}' : wp_json_encode( $context, JSON_HEX_TAG | JSON_HEX_APOS | JSON_HEX_QUOT | JSON_HEX_AMP ) ) . diff --git a/packages/block-library/src/navigation/index.php b/packages/block-library/src/navigation/index.php index 3a3a654aee6126..1d73d09bbd1fbb 100644 --- a/packages/block-library/src/navigation/index.php +++ b/packages/block-library/src/navigation/index.php @@ -552,7 +552,7 @@ private static function get_nav_element_directives( $is_interactive ) { return ''; } // When adding to this array be mindful of security concerns. - $nav_element_context = data_wp_context( + $nav_element_context = wp_interactivity_data_wp_context( array( 'overlayOpenedBy' => array( 'click' => false, diff --git a/packages/block-library/src/search/index.php b/packages/block-library/src/search/index.php index c368c2ab03dbf8..ca8c70edfa907d 100644 --- a/packages/block-library/src/search/index.php +++ b/packages/block-library/src/search/index.php @@ -179,7 +179,7 @@ function render_block_core_search( $attributes ) { if ( $is_expandable_searchfield ) { $aria_label_expanded = __( 'Submit Search' ); $aria_label_collapsed = __( 'Expand search field' ); - $form_context = data_wp_context( + $form_context = wp_interactivity_data_wp_context( array( 'isSearchInputVisible' => $open_by_default, 'inputId' => $input_id, diff --git a/packages/interactivity/docs/2-api-reference.md b/packages/interactivity/docs/2-api-reference.md index bae15e9a7fcf2f..64033107a8a552 100644 --- a/packages/interactivity/docs/2-api-reference.md +++ b/packages/interactivity/docs/2-api-reference.md @@ -969,3 +969,150 @@ const { state } = store( // The following call works as expected. store( "myPlugin/private", { /* store part */ }, { lock: PRIVATE_LOCK } ); ``` + +### Store client methods + +Apart from the store function, there are also some methods that allows the developer to access data on their store functions. + + - getContext() + - getElement() + +#### getContext() + +Retrieves the context inherited by the element evaluating a function from the store. The returned value depends on the element and the namespace where the function calling `getContext()` exists. + +```php +// render.php +
+ +
+``` + +```js +// store +import { store, getContext } from '@wordpress/interactivity'; + +store( "myPlugin", { + actions: { + log: () => { + const context = getContext(); + // Logs "false" + console.log('context => ', context.isOpen) + }, + }, +}); +``` + +#### getElement() + +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` is the reference to the DOM element as an (HTMLElement)[https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement] + +##### 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) + +Those attributes will contain the directives of that element. In the button example: + +```js +// store +import { store, getContext } from '@wordpress/interactivity'; + +store( "myPlugin", { + actions: { + log: () => { + const element = getElement(); + // Logs "false" + console.log('element attributes => ', element.attributes) + }, + }, +}); +``` + +The code will log: + +```json +{ + "data-wp-on--click": 'actions.increaseCounter', + "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 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. + +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 on 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 server side rendering part, and is public so any HTML can be processed, whether is a block or not. + +This code + +```php +wp_interactivity_state( 'myPlugin', array( 'greeting' => 'Hello, World!' ) ); +$html = '
'; +$processed_html = wp_interactivity_process_directives( $html_content ); +echo $processed_html; +``` + +will output: +```html +
Hello, World!
+``` + +### wp_interactivity_data_wp_context + +`wp_interactivity_data_wp_context` returns a stringified JSON of a context directive. +This function is the recommended way to print the `data-wp-context` attribute in the server side rendedered markup. + +```php + +$my_context = array( + 'counter' => 0, + 'isOpen' => true, +); +
+
+``` + +will output: + +```html +
+```