diff --git a/packages/interactivity/docs/api-reference.md b/packages/interactivity/docs/api-reference.md index b755b12464667..d10d56390b917 100644 --- a/packages/interactivity/docs/api-reference.md +++ b/packages/interactivity/docs/api-reference.md @@ -39,6 +39,7 @@ DOM elements are connected to data stored in the state and context through direc - [Setting the store](#setting-the-store) - [On the client side](#on-the-client-side) - [On the server side](#on-the-server-side) + - [Store client methods](#store-client-methods) ## The directives @@ -974,3 +975,76 @@ 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); } +} +```