From 605cce2b0da0819eb26cc89bbb5be676e0e06aa9 Mon Sep 17 00:00:00 2001 From: Nick Diego Date: Mon, 11 Mar 2024 16:11:06 -0500 Subject: [PATCH] Docs: Update Interactivity API package readme (#59763) * Change callout to an alert. * Update intro, remove TOC, and change headings * Update Installation and Quick Start Guide sections. Co-authored-by: ndiego Co-authored-by: justintadlock --- packages/interactivity/README.md | 107 ++++++++----------- packages/interactivity/docs/api-reference.md | 2 +- 2 files changed, 46 insertions(+), 63 deletions(-) diff --git a/packages/interactivity/README.md b/packages/interactivity/README.md index a6b2a7fb6f3dc..adc96738213fc 100644 --- a/packages/interactivity/README.md +++ b/packages/interactivity/README.md @@ -1,97 +1,86 @@ # 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": { @@ -99,9 +88,9 @@ To indicate that the block [supports](https://developer.wordpress.org/block-edit }, ``` -##### 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 @@ -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. diff --git a/packages/interactivity/docs/api-reference.md b/packages/interactivity/docs/api-reference.md index 103c535613fa7..78aefe7823d0f 100644 --- a/packages/interactivity/docs/api-reference.md +++ b/packages/interactivity/docs/api-reference.md @@ -1,6 +1,6 @@ # API Reference -
+
Interactivity API is only available for WordPress 6.5 and above.