Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Move Interactivity API docs from package to reference guides (#61143)
Co-authored-by: juanmaguitar <juanmaguitar@git.wordpress.org> Co-authored-by: fabiankaegy <fabiankaegy@git.wordpress.org>
- Loading branch information
3 people
committed
Apr 29, 2024
1 parent
cbdf540
commit 4abdb39
Showing
7 changed files
with
148 additions
and
114 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,74 @@ | ||
| # Interactivity API Reference | ||
|
|
||
| The Interactivity API, [introduced in WordPress 6.5](https://make.wordpress.org/core/2024/02/19/merge-announcement-interactivity-api/), provides a standard way for developers to add interactions to the front end of their blocks. The API is also used in many Core WordPress blocks, including Search, Query, Navigation, and File. | ||
|
|
||
| This standard makes it easier for developers to create rich, interactive user experiences, from simple counters or pop-ups to more complex features like instant page navigation, instant search, shopping carts, or checkouts. | ||
|
|
||
| Blocks can share data, actions, and callbacks between them. This makes communication between blocks simpler and less error-prone. For example, clicking on an “add to cart” block can seamlessly update a separate “cart” block. | ||
|
|
||
| For more information about the genesis of the Interactivity API, check out the [original proposal](https://make.wordpress.org/core/2023/03/30/proposal-the-interactivity-api-a-better-developer-experience-in-building-interactive-blocks/). You can also review the [merge announcement](https://make.wordpress.org/core/2024/02/19/merge-announcement-interactivity-api/), the [status update post](https://make.wordpress.org/core/2023/08/15/status-update-on-the-interactivity-api/), and the official [Trac ticket](https://core.trac.wordpress.org/ticket/60356). | ||
|
|
||
| <div class="callout callout-info"> | ||
| The Interactivity API is supported by the package <code>@wordpress/interactivity</code> which is bundled in WordPress Core from v6.5 | ||
| </div> | ||
|
|
||
| ## Navigating the Interactivity API docs | ||
|
|
||
| Use the following links to locate the topic you're interested in. If you have never worked with the Interactivity API before, consider reading through the following resources in the order listed. | ||
|
|
||
| - **[Requirements](#requirements-of-the-interactivity-api):** Check this section before you start creating your interactive blocks with the Interactivity API. | ||
| - **[Quick Start Guide](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/quick-start-guide/):** Get a custom block using the Interactivity API up and running in less than one minute. | ||
| - **[Tutorial: A first look at the Interactivity API](https://developer.wordpress.org/news/2024/04/11/a-first-look-at-the-interactivity-api/)** This article from the [WordPress Developer Blog](https://developer.wordpress.org/news/) is a great way to get introduced to the Interactivity API. | ||
| - **[API Reference](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/api-reference/):** To take a deep dive into how the API works internally, the list of Directives, and how Store works. | ||
| - **[Docs and Examples](#docs--examples):** Additional resources to learn/read more about the Interactivity API. | ||
|
|
||
| ## Requirements of the Interactivity API | ||
|
|
||
| Interactivity API is included in Core in WordPress 6.5. For versions below, you'll need Gutenberg 17.5 or higher installed and activated in your WordPress installation. | ||
|
|
||
| It’s also important to highlight that the block creation workflow doesn’t change, and all the [prerequisites](https://developer.wordpress.org/block-editor/getting-started/devenv/) remain the same. These include: | ||
|
|
||
| - [Code editor](https://developer.wordpress.org/block-editor/getting-started/devenv/#code-editor) | ||
| - [Node.js development tools](https://developer.wordpress.org/block-editor/getting-started/devenv/#node-js-development-tools) | ||
| - [Local WordPress environment (site)](https://developer.wordpress.org/block-editor/getting-started/devenv/#local-wordpress-environment) | ||
|
|
||
| You can start creating interactions once you set up a block development environment and are running WordPress 6.5+ (or Gutenberg 17.5+). | ||
|
|
||
| ### Code requirements | ||
|
|
||
| #### Add `interactivity` support to `block.json` | ||
|
|
||
| To indicate that the block [supports](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/) the Interactivity API features, add `"interactivity": true` to the `supports` attribute of the block's `block.json` file. | ||
|
|
||
| ``` | ||
| "supports": { | ||
| "interactivity": true | ||
| }, | ||
| ``` | ||
|
|
||
| #### Add `wp-interactive` directive to a DOM element | ||
|
|
||
| To "activate" the Interactivity API in a DOM element (and its children), add the [`wp-interactive`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-interactivity/packages-interactivity-api-reference/#wp-interactive) directive to the element in the block's `render.php` or `save.js` files. | ||
|
|
||
|
|
||
| ```html | ||
| <div data-wp-interactive="myPlugin"> | ||
| <!-- Interactivity API zone --> | ||
| </div> | ||
| ``` | ||
|
|
||
| ## Docs & Examples | ||
|
|
||
| Here you have some more resources to learn/read more about the Interactivity API: | ||
|
|
||
| - [WordPress 6.5 Dev Note](https://make.wordpress.org/core/2024/03/04/interactivity-api-dev-note/) | ||
| - [Merge announcement](https://make.wordpress.org/core/2024/02/19/merge-announcement-interactivity-api/) | ||
| - [Proposal: The Interactivity API – A better developer experience in building interactive blocks](https://make.wordpress.org/core/2023/03/30/proposal-the-interactivity-api-a-better-developer-experience-in-building-interactive-blocks/) | ||
| - [Interactivity API Discussions](https://github.com/WordPress/gutenberg/discussions/52882) | ||
| - Developer Hours sessions ([Americas](https://www.youtube.com/watch?v=RXNoyP2ZiS8&t=664s) & [APAC/EMEA](https://www.youtube.com/watch?v=6ghbrhyAcvA)) | ||
| - [wpmovies.dev](http://wpmovies.dev/) demo and its [wp-movies-demo](https://github.com/WordPress/wp-movies-demo) repo | ||
|
|
||
| <div class="callout"> | ||
| There's a Tracking Issue opened to ease the coordination of the work related to the Interactivity API Docs: <a href="https://github.com/WordPress/gutenberg/issues/53296">Documentation for the Interactivity API - Tracking Issue #53296</a> | ||
| </div> | ||
|
|
File renamed without changes.
41 changes: 41 additions & 0 deletions
41
docs/reference-guides/interactivity-api/quick-start-guide.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,41 @@ | ||
| # Quick start guide | ||
|
|
||
| This guide will help you build a basic block that demonstrates the Interactivity API in WordPress. | ||
|
|
||
| ## Scaffold an interactive block | ||
|
|
||
| Start by ensuring you have Node.js and `npm` installed on your computer. Review the [Node.js development environment](https://developer.wordpress.org/block-editor/getting-started/devenv/nodejs-development-environment/) guide if not. | ||
|
|
||
| Next, use the [`@wordpress/create-block`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/) package and the [`@wordpress/create-block-interactive-template`](https://www.npmjs.com/package/@wordpress/create-block-interactive-template) template to scaffold the complete “My First Interactive Block” plugin. | ||
|
|
||
| Choose the folder where you want to create the plugin, and then execute the following command in the terminal from within that folder: | ||
|
|
||
| ``` | ||
| npx @wordpress/create-block@latest my-first-interactive-block --template @wordpress/create-block-interactive-template | ||
| ``` | ||
|
|
||
| The slug provided (`my-first-interactive-block`) defines the folder name for the scaffolded plugin and the internal block name. | ||
|
|
||
| ## Basic usage | ||
|
|
||
| With the plugin activated, you can explore how the block works. Use the following command to move into the newly created plugin folder and start the development process. | ||
|
|
||
| ``` | ||
| cd my-first-interactive-block && npm start | ||
| ``` | ||
|
|
||
| When `create-block` scaffolds the block, it installs `wp-scripts` and adds the most common scripts to the block’s `package.json` file. Refer to the [Get started with wp-scripts](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-wp-scripts/) article for an introduction to this package. | ||
|
|
||
| The `npm start` command will start a development server and watch for changes in the block’s code, rebuilding the block whenever modifications are made. | ||
|
|
||
| When you are finished making changes, run the `npm run build` command. This optimizes the block code and makes it production-ready. | ||
|
|
||
| ## View the block in action | ||
|
|
||
| If you have a local WordPress installation already running, you can launch the commands above inside the `plugins` folder of that installation. If not, you can use [`wp-now`](https://github.com/WordPress/playground-tools/tree/trunk/packages/wp-now) to launch a WordPress site with the plugin installed by executing the following command from the plugin's folder (`my-first-interactive-block`). | ||
|
|
||
| ``` | ||
| npx @wp-now/wp-now start | ||
| ``` | ||
|
|
||
| You should be able to insert the "My First Interactive Block" block into any post and see how it behaves in the front end when published. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.