Skip to content

Commit

Permalink
Docs: Update Interactivity API package readme (#59763)
Browse files Browse the repository at this point in the history 
* Change callout to an alert.
* Update intro, remove TOC, and change headings
* Update Installation and Quick Start Guide sections.

Co-authored-by: ndiego <[email protected]>
Co-authored-by: justintadlock <[email protected]>
  • Loading branch information
@ndiego @justintadlock
3 people authored Mar 11, 2024
1 parent 86e1422 commit 605cce2
Show file tree
Hide file tree
Showing 2 changed files with 46 additions and 63 deletions.
107 changes: 45 additions & 62 deletions packages/interactivity/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,107 +1,96 @@
# Interactivity API

> **Note**
> This package enables the API shared at [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/). As part of an [Open Source project](https://developer.wordpress.org/block-editor/getting-started/faq/#the-gutenberg-project), participation is encouraged in testing this API providing feedback at the [discussions in GitHub](https://github.com/WordPress/gutenberg/discussions/categories/interactivity-api).
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.

The Interactivity API is available at WordPress Core from version 6.5: [Merge announcement](https://make.wordpress.org/core/2024/02/19/merge-announcement-interactivity-api/)
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.

These Core blocks are already powered by the API:
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.

- Search
- Query
- Navigation
- File
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).

## Installation

> **Note**
> This step is only required if you are using this API outside of WordPress.
>
> Within WordPress, the package is already bundled in Core, so all you need to do to ensure it is loaded, by adding `@wordpress/interactivity` to the dependency array of the script module.
>
>This happens automatically when you use the dependency extraction Webpack plugin that is used in tools like wp-scripts.
Install the module:
Install the Interactivity API using the command:

```bash
npm install @wordpress/interactivity --save
```

_This package assumes that your code will run in an **ES2015+** environment. If you're using an environment that has limited or no support for such language features and APIs, you should include [the polyfill shipped in `@wordpress/babel-preset-default`](https://github.com/WordPress/gutenberg/tree/HEAD/packages/babel-preset-default#polyfill) in your code._
This step is only required if you use the Interactivity API outside WordPress.

Within WordPress, the package is already bundled in Core. To ensure it's loaded, add `@wordpress/interactivity` to the dependency array of the script module. This process is often done automatically with tools like [`wp-scripts`](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-wp-scripts/).

Furthermore, this package assumes your code will run in an **ES2015+** environment. If you're using an environment with limited or no support for such language features and APIs, you should include the polyfill shipped in [`@wordpress/babel-preset-default`](https://github.com/WordPress/gutenberg/tree/HEAD/packages/babel-preset-default#polyfill) in your code.

## Quick start guide

## Quick Start Guide
This guide will help you build a basic block that demonstrates the Interactivity API in WordPress.

### Table of Contents
### Scaffold an interactive block

- [Quick Start Guide](#quick-start-guide)
- [1. Scaffold an interactive block](#1-scaffold-an-interactive-block)
- [2. Generate the build](#2-generate-the-build)
- [3. Use it in your WordPress installation ](#3-use-it-in-your-wordpress-installation)
- [Requirements of the Interactivity API](#requirements-of-the-interactivity-aPI)
- [A local WordPress installation](#a-local-wordpress-installation)
- [Latest vesion of Gutenberg](#latest-vesion-of-gutenberg)
- [Node.js](#nodejs)
- [Code requirements](#code-requirements)
- [Add `interactivity` support to `block.json`](#add-interactivity-support-to-blockjson)
- [Add `wp-interactive` directive to a DOM element](#add-wp-interactive-directive-to-a-dom-element)
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.

#### 1. Scaffold an interactive block
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.

A WordPress plugin that registers an interactive block (using the Interactivity API) by using a [template](https://www.npmjs.com/package/@wordpress/create-block-interactive-template) can be scaffolded with the `@wordpress/create-block` command.
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
```

#### 2. Generate the build
The slug provided (`my-first-interactive-block`) defines the folder name for the scaffolded plugin and the internal block name.

When the plugin folder is generated, the build process needs to be launched to get a working version of the interactive block that can be used in WordPress.
### 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
```

#### 3. Use it in your WordPress installation
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.

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 from the generated folder (and from a different terminal window or tab) the following command
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.

```
npx @wp-now/wp-now start
```
When you are finished making changes, run the `npm run build` command. This optimizes the block code and makes it production-ready.

At this point you should be able to insert the "My First Interactive Block" block into any post, and see how it behaves in the frontend when published.
### View the block in action

### Requirements of the Interactivity API
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`).

To start working with the Interactivity API you'll need to have a [proper WordPress development environment for blocks](https://developer.wordpress.org/block-editor/getting-started/devenv/) and some specific code in your block, which should include:
```
npx @wp-now/wp-now start
```

#### A local 6.5 WordPress installation
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.

You can use [the tools to set your local WordPress environment](https://developer.wordpress.org/block-editor/getting-started/devenv/#wordpress-development-site) you feel more comfortable with.
## Requirements of the Interactivity API

To get quickly started, [`wp-now`](https://www.npmjs.com/package/@wp-now/wp-now) is the easiest way to get a WordPress site up and running locally.
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.

Interactivity API is included in Core in WordPress 6.5, for versions below, you'll need to have Gutenberg 17.5 or higher version 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:

#### Node.js
- [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)

Block development requires [Node](https://nodejs.org/en), so you'll need to have Node installed and running on your machine. Any version modern should work, but please check the minimum version requirements if you run into any issues with any of the Node.js tools used in WordPress development.
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
### Code requirements

##### Add `interactivity` support to `block.json`
#### 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`
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
#### Add `wp-interactive` directive to a DOM element

To "activate" the Interactivity API in a DOM element (and its children), add the [`wp-interactive` directive](./docs/api-reference.md#wp-interactive) to it from `render.php` or `save.js`
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
Expand All @@ -112,28 +101,22 @@ To "activate" the Interactivity API in a DOM element (and its children), add the

## API Reference

To take a deep dive in how the API works internally, the list of Directives, and how Store works, click [here](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-interactivity/packages-interactivity-api-reference/).
To take a deep dive into how the API works internally, the list of Directives, and how Store works, visit the [API reference](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-interactivity/packages-interactivity-api-reference/).

## Docs & Examples

Here you have some more resources to learn/read more about the Interactivity API:

- **[Interactivity API Discussions](https://github.com/WordPress/gutenberg/discussions/52882)**
- [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

There's a Tracking Issue opened to ease the coordination of the work related to the Interactivity API Docs: **[Documentation for the Interactivity API - Tracking Issue #53296](https://github.com/WordPress/gutenberg/issues/53296)**


## Get Involved

As part of an [Open Source project](https://developer.wordpress.org/block-editor/getting-started/faq/#the-gutenberg-project) participation is encouraged in helping shape this API and its Docs. The [discussions](https://github.com/WordPress/gutenberg/discussions/categories/interactivity-api) and [issues](https://github.com/WordPress/gutenberg/labels/%5BFeature%5D%20Interactivity%20API) in GitHub are the best place to engage.

If you are willing to help with the documentation, please add a comment to [#51928](https://github.com/WordPress/gutenberg/discussions/51928) to coordinate everyone's efforts.


## License

Interactivity API proposal, as part of Gutenberg and the WordPress project is free software, and is released under the terms of the GNU General Public License version 2 or (at your option) any later version. See [LICENSE.md](https://github.com/WordPress/gutenberg/blob/trunk/LICENSE.md) for complete license.
Expand Down
2 changes: 1 addition & 1 deletion packages/interactivity/docs/api-reference.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# API Reference

<div class="callout callout-warning">
<div class="callout callout-alert">
Interactivity API is only available for WordPress 6.5 and above.
</div>

Expand Down

0 comments on commit 605cce2

Please sign in to comment.