You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 14763bd
Browse filesBrowse the repository at this point in the historyBrowse files
* Interactivity API: Migrate Interactivity fixtures to supported directive forms
* Interactivity API: Use full event suffix in event directives
* Interactivity API: Skip suffixed lifecycle directives
* Interactivity API: Do not invoke negated functions
* Interactivity API: Remove special handling for data-wp-ignore
* Interactivity API: Update island hydration e2e coverage
* Interactivity API: Correct hydration fixture explanation
* Interactivity API: Remove expired unique-ID deprecation notices from Interactivity API reference
* Interactivity API: Announce removals in the changelog
* Interactivity API: Normalize reference emphasis formatting
* Interactivity API: Reference removal PR in the changelog
* Interactivity API: Warn about two-hyphen event names
Event directives now read the whole suffix as the event name, so a leftover two-hyphen unique ID silently listens for an event that never fires. Warn in development mode and suggest the three-hyphen form. Document that the deprecated async event directives still cut the event name at `--`.
* Interactivity API: Share the unsupported suffix warning with router-region
Align the warnSuffixNotSupported() wording with the existing router-region message and use the helper there too.
* Interactivity API: Warn about leftover data-wp-ignore attributes
* Interactivity API: Remove JSDoc from the Evaluate interface
* Interactivity API: Move and extend tests for removed deprecations
Move the tests next to the other directive tests and follow their conventions. Cover production mode, the new warnings, data-wp-ignore hydration, deprecated async event directives, and negation of values and getters.
* Interactivity API: Rename stale isolated island e2e fixtures
* Interactivity API: Document unique IDs for event directives and function negation
* Interactivity API: Split the breaking changes changelog entry
---------
Co-authored-by: David <david.arenas@automattic.com>
Co-authored-by: luisherranz <luisherranz@git.wordpress.org>
Copy file name to clipboardExpand all lines: docs/reference-guides/interactivity-api/directives-and-store.md
+19-8Lines changed: 19 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -415,6 +415,17 @@ The `wp-on` directive is executed each time the associated event is triggered.
415
415
416
416
The callback passed as the reference receives [the event](https://developer.mozilla.org/en-US/docs/Web/API/Event) (`event`), and the returned value by this callback is ignored.
417
417
418
+
You can attach several callbacks to the same event of a DOM element by using the syntax `data-wp-on--[event]---[unique-id]` (note the three hyphens before the unique ID). Everything between `data-wp-on--` and the three hyphens is used as the event name, so `data-wp-on--click--counter` listens for an event named `click--counter`, not for `click`.
419
+
420
+
```html
421
+
<button
422
+
data-wp-on--click="actions.logTime"
423
+
data-wp-on--click---counter="actions.countClick"
424
+
>
425
+
Click Me!
426
+
</button>
427
+
```
428
+
418
429
### `wp-on-window`
419
430
420
431
<divclass="callout callout-info">
@@ -448,6 +459,8 @@ store( 'myPlugin', {
448
459
449
460
The callback passed as the reference receives [the event](https://developer.mozilla.org/en-US/docs/Web/API/Event) (`event`), and the returned value by this callback is ignored. When the element is removed from the DOM, the event listener is also removed.
450
461
462
+
You can attach several callbacks to the same window event by using the syntax `data-wp-on-window--[window-event]---[unique-id]` (note the three hyphens before the unique ID), like `data-wp-on-window--resize---log-width`.
463
+
451
464
### `wp-on-document`
452
465
453
466
<divclass="callout callout-info">
@@ -481,14 +494,14 @@ store( 'myPlugin', {
481
494
482
495
The callback passed as the reference receives [the event](https://developer.mozilla.org/en-US/docs/Web/API/Event) (`event`), and the returned value by this callback is ignored. When the element is removed from the DOM, the event listener is also removed.
483
496
497
+
You can attach several callbacks to the same document event by using the syntax `data-wp-on-document--[document-event]---[unique-id]` (note the three hyphens before the unique ID), like `data-wp-on-document--keydown---log-key`.
498
+
484
499
### `wp-watch`
485
500
486
501
It runs a callback **when the node is created and runs it again when the state or context changes**.
487
502
488
503
You can attach several side effects to the same DOM element by using the syntax `data-wp-watch---[unique-id]` (note the three hyphens before the unique ID).
489
504
490
-
> **Deprecation notice:** The two-hyphen syntax `data-wp-watch--[unique-id]` is deprecated and will stop working in WordPress 7.1. Use three hyphens (`---`) for unique IDs.
491
-
492
505
The `unique-id` doesn't need to be unique globally. It just needs to be different from the other unique IDs of the `wp-watch` directives of that DOM element.
493
506
494
507
```html
@@ -547,8 +560,6 @@ This directive runs a callback **only when the node is created**.
547
560
548
561
You can attach several `wp-init` to the same DOM element by using the syntax `data-wp-init---[unique-id]` (note the three hyphens before the unique ID).
549
562
550
-
> **Deprecation notice:** The two-hyphen syntax `data-wp-init--[unique-id]` is deprecated and will stop working in WordPress 7.1. Use three hyphens (`---`) for unique IDs.
551
-
552
563
The `unique-id` doesn't need to be unique globally. It just needs to be different from the other unique IDs of the `wp-init` directives of that DOM element.
553
564
554
565
```html
@@ -597,8 +608,6 @@ You can use and compose hooks like `useState`, `useWatch`, or `useEffect` inside
597
608
598
609
You can attach several `wp-run` to the same DOM element by using the syntax `data-wp-run---[unique-id]` (note the three hyphens before the unique ID).
599
610
600
-
> **Deprecation notice:** The two-hyphen syntax `data-wp-run--[unique-id]` is deprecated and will stop working in WordPress 7.1. Use three hyphens (`---`) for unique IDs.
601
-
602
611
The `unique-id` doesn't need to be unique globally. It just needs to be different from the other unique IDs of the `wp-run` directives of that DOM element.
603
612
604
613
```html
@@ -776,6 +785,8 @@ And then, the string value `"state.isPlaying"` is used to assign the result of t
776
785
</div>
777
786
```
778
787
788
+
The `!` operator negates the referenced value. It only works with values, such as state, context, or derived state defined with a getter. If the reference points to a function, such as an action or a callback, the function is not called and the directive receives `undefined` instead (with a warning when `SCRIPT_DEBUG` is enabled). To negate the result of a computation, define it as derived state with a getter and negate that.
789
+
779
790
These values assigned to directives are **references** to a particular property in the store. They are wired to the directives automatically so that each directive “knows” what store element refers to, without any additional configuration.
780
791
781
792
Note that, by default, references point to properties in the current namespace, which is the one specified by the closest ancestor with a `data-wp-interactive` attribute. If you need to access a property from a different namespace, you can explicitly set the namespace where the property accessed is defined. The syntax is `namespace::reference`, replacing `namespace` with the appropriate value.
@@ -1025,7 +1036,7 @@ This approach enables some functionalities that make directives flexible and pow
1025
1036
1026
1037
#### On the client side
1027
1038
1028
-
_In the `view.js` file of each block_ the developer can define both the state and the elements of the store referencing functions like actions, side effects or derived state.
1039
+
*In the `view.js` file of each block* the developer can define both the state and the elements of the store referencing functions like actions, side effects or derived state.
1029
1040
1030
1041
The `store` method used to set the store in JavaScript can be imported from `@wordpress/interactivity`.
1031
1042
@@ -1058,7 +1069,7 @@ The state defined on the server with `wp_interactivity_state()` gets merged with
1058
1069
1059
1070
The `wp_interactivity_state` function receives two arguments, a `string` with the namespace that will be used as a reference and an [associative array](https://www.php.net/manual/en/language.types.array.php) containing the values.
1060
1071
1061
-
_Example of store initialized from the server with a `state` = `{ someValue: 123 }`_
1072
+
*Example of store initialized from the server with a `state` = `{ someValue: 123 }`*
0 commit comments