Skip to content

Commit 27eb456

Browse files
fabiankaegyfabiankaegy
committed
add new interactivity api getting started guide
1 parent a22dc1f commit 27eb456

File tree

1 file changed

+204
-0
lines changed

1 file changed

+204
-0
lines changed

‎guides/interactivity-api-getting-started.md‎

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
---
2+
sidebar_label: Interactivity API Basics
3+
---
4+
5+
# Getting started with the Interactivity API
6+
7+
The Interactivity API was released in WordPress 6.5. It is a new way to write frontend JavaScript specifically designed for the needs of blocks.
8+
9+
This guide will walk you through the basics of the Interactivity API and how to get started with it.
10+
11+
## Pre-requisites
12+
13+
The Interactivity API only works in ESM (ECMAScript Modules) environments. This means that you cannot simply use it in a regular `viewScript` or JS file that you enqueue in your theme. Instead your build step needs to support this and the file needs to be loaded properly.
14+
15+
Luckily, both 10up-toolkit and @wordpress/scripts handle all of this for you. Just make sure that you use at least version 6.1+ of toolkit or @wordpress/scripts 27.2.0+.
16+
17+
### Configuring 10up-toolkit for script modules
18+
19+
In order for toolkit to properly output these script modules you need to enable a new feature flag in your `package.json` file. Under the `10up-toolkit` key you need to se the `useScriptModules` flag to `true`.
20+
21+
```json
22+
{
23+
"10up-toolkit": {
24+
"useScriptModules": true
25+
}
26+
}
27+
```
28+
29+
With that set you can now start to use the `scriptModule` & `viewScriptModule` keys in `block.json` to define your module scripts. `scriptModule` is similar to `script` and will load both in the editor and on the frontend. `viewScriptModule` is similar to `viewScript` and will only load on the frontend. In 90% of cases you will want `viewScriptModule`.
30+
31+
If you want to load a module script that is not connected to a block you can also use the `moduleEntry` key in `package.json` to add your own custom module entrypoints:
32+
33+
```json
34+
{
35+
"10up-toolkit": {
36+
"moduleEntry": {
37+
"my-script": "./src/my-script.js"
38+
}
39+
}
40+
}
41+
```
42+
43+
These scripts then need to get manually enqueued using the [`wp_enqueue_script_module`](https://developer.wordpress.org/reference/functions/wp_enqueue_script_module/) function.
44+
45+
## Writing your first Interactivity API code
46+
47+
Now that we are all set up we can get started writing out first Interactivity API powered code.
48+
49+
In this example we are going to write a simple block that renders a toggle that expands and collapses a div when a button is clicked.
50+
51+
First we need to tell WordPress that our block is making use of the Interactivity API by setting `supports.interactivity` to `true` in the block.json file.
52+
53+
```json
54+
{
55+
"supports": {
56+
"interactivity": true
57+
}
58+
}
59+
```
60+
61+
This lets WordPress know that there are special html data attributes that need to get processed before the HTML is printed on the page.
62+
63+
Next we can setup the namespace of our interactive region. This is done by adding a `data-wp-interactivity` attribute to the root element of our block.
64+
65+
```php
66+
$additional_attributes = [
67+
'data-wp-interactivity' => 'namespace/block-name',
68+
];
69+
70+
?>
71+
72+
<div <?php echo get_block_wrapper_attributes( $additional_attributes ); ?>>
73+
...
74+
</div>
75+
```
76+
77+
This namespace needs to match the namespace we use in a minute when we add out JS code.
78+
79+
This happens by creating a new file we can for example call `view-module.js`. (The name doesn't matter here). This file now needs to get referenced in the `viewScriptModule` key in the `block.json` file.
80+
81+
```json
82+
{
83+
"viewScriptModule": "file:./view-module.js"
84+
}
85+
```
86+
87+
In this file we can now import the `store` function from the `@wordpress/interactivity` package and define out first custom store.
88+
89+
```js
90+
import { store } from '@wordpress/interactivity';
91+
92+
store( 'namespace/block-name', {
93+
...
94+
} );
95+
```
96+
97+
This store is now ready and connected to our block. From here we can start defining all the logic we need.
98+
99+
### Adding a toggle
100+
101+
The Interactivity API is built to be declarative. This means that you define the state of your block and the API takes care of updating the DOM for you. So the HTML you write in the `render.php` file really is the source of truth for all the markup that gets displayed. Including it's various interactive states.
102+
103+
This is accomplished by using special html data attributes (directives). WordPress comes with a bunch of different directives. All of then are prefixed with `data-wp-`. For example `data-wp-class--is-active` can be used to control whether or not the class `is-active` is added to an element.
104+
105+
```html
106+
<div data-wp-class--is-active="context.isActive">
107+
...
108+
</div>
109+
```
110+
111+
In this example the `is-active` class would never get added to the div because we don't yet have our context defined. And what the `data-wp-class--` directive does is check if the value we reference is truthy and if so it adds the class we define after the `--` to the element.
112+
113+
To define out context we can again start in out markup. The `data-wp-context` attribute is used to define the initial state of our block. This initial state gets fully server rendered and can then get updated interactively.
114+
115+
```php
116+
$additional_attributes = [
117+
'data-wp-interactivity' => 'namespace/block-name',
118+
'data-wp-context' => wp_json_encode(
119+
[
120+
'isActive' => false,
121+
],
122+
JSON_HEX_TAG | JSON_HEX_APOS | JSON_HEX_QUOT | JSON_HEX_AMP
123+
)
124+
];
125+
```
126+
127+
If you change the value of `isActive` in the context the `is-active` class will get added or removed from the div.
128+
129+
### Lets make it interactive
130+
131+
Now that we have our context defined we can start to add some interactivity to our block. This is done by defining actions that can be triggered by the user.
132+
133+
```js
134+
import { store, getContext } from '@wordpress/interactivity';
135+
136+
store( 'namespace/block-name', {
137+
actions: {
138+
toggle() {
139+
const context = getContext();
140+
context.isActive = ! context.isActive;
141+
},
142+
},
143+
} );
144+
```
145+
146+
In this example we define a new action called `toggle`. This action is now available to be triggered by the user. We can trigger it by adding a `data-wp-on--click` attribute to an element in our block.
147+
148+
```php
149+
<?php
150+
$additional_attributes = [
151+
'data-wp-interactivity' => 'namespace/block-name',
152+
'data-wp-context' => wp_json_encode(
153+
[
154+
'isActive' => false,
155+
],
156+
JSON_HEX_TAG | JSON_HEX_APOS | JSON_HEX_QUOT | JSON_HEX_AMP
157+
)
158+
];
159+
160+
?>
161+
162+
<div <?php echo get_block_wrapper_attributes( $additional_attributes ); ?>>
163+
<button data-wp-on--click="actions.toggle">
164+
Toggle
165+
</button>
166+
<div data-wp-class--is-active="context.isActive">
167+
...
168+
</div>
169+
</div>
170+
```
171+
172+
This will now toggle the `isActive` state in our context and the `is-active` class will get added or removed from the div.
173+
174+
To make this more accessible we can also add a `data-wp-bind--` directive and bind the `aria-expanded` attribute to this same context.
175+
176+
```php
177+
<?php
178+
$additional_attributes = [
179+
'data-wp-interactivity' => 'namespace/block-name',
180+
'data-wp-context' => wp_json_encode(
181+
[
182+
'isActive' => false,
183+
],
184+
JSON_HEX_TAG | JSON_HEX_APOS | JSON_HEX_QUOT | JSON_HEX_AMP
185+
)
186+
];
187+
188+
?>
189+
190+
<div <?php echo get_block_wrapper_attributes( $additional_attributes ); ?>>
191+
<button data-wp-on--click="actions.toggle">
192+
Toggle
193+
</button>
194+
<div data-wp-class--is-active="context.isActive" data-wp-bind--aria-expanded="context.isActive">
195+
...
196+
</div>
197+
</div>
198+
```
199+
200+
## Conclusion
201+
202+
The Interactivity API is a powerful new way to write frontend JavaScript for blocks. It is designed to be declarative and easy to use. This guide has shown you the basics of how to get started with the Interactivity API and how to write your first interactive block.
203+
204+
For more information on the Interactivity API check out the [official documentation](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/).

0 commit comments

Comments
 (0)