Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Interactivity API Docs: Add server functions documentation. #59373

Merged
merged 3 commits into from
Feb 26, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 55 additions & 1 deletion packages/interactivity/docs/api-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -1018,7 +1023,7 @@ It returns an object with two keys:

`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)

Expand Down Expand Up @@ -1047,4 +1052,53 @@ 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 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 = '<div data-wp-text="myPlugin::state.greeting"></div>';
$processed_html = wp_interactivity_process_directives( $html_content );
echo $processed_html;
```

will output:
```html
<div data-wp-text="create-block::state.greeting">Hello, World!</div>
```
Loading