diff --git a/docs/manifest.json b/docs/manifest.json index 84c7da42aa8b20..638c5d2b16c83d 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -1679,6 +1679,12 @@ "markdown_source": "../packages/interactivity/README.md", "parent": "packages" }, + { + "title": "API Reference", + "slug": "packages-interactivity-api-reference", + "markdown_source": "../packages/interactivity/docs/api-reference.md", + "parent": "packages-interactivity" + }, { "title": "@wordpress/interface", "slug": "packages-interface", diff --git a/packages/interactivity/README.md b/packages/interactivity/README.md index 0ea49bdea0782f..a0fddb9a42bf28 100644 --- a/packages/interactivity/README.md +++ b/packages/interactivity/README.md @@ -1,62 +1,141 @@ # Interactivity API -> **Warning** -> **This package is only available in Gutenberg** at the moment and not in WordPress Core as it is still very experimental, and very likely to change. +> **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 is available at WordPress Core from version 6.5 [Merge announcement](https://make.wordpress.org/core/2024/02/19/merge-announcement-interactivity-api/) + +These Core blocks are already powered by thi API: +- Search +- Query +- Navigation +- File + +## Installation > **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) we encourage participation in helping shape this API and the [discussions in GitHub](https://github.com/WordPress/gutenberg/discussions/categories/interactivity-api) is the best place to engage. +> 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 `wp-interactivity` to the dependency array of the module script. +> +>This happens automatically when you use the dependency extraction Webpack plugin that is used in tools like wp-scripts. + +Install the module: + +```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._ + +## Quick Start Guide -This package can be tested, but it's still very experimental. -The Interactivity API is [being used in some core blocks](https://github.com/search?q=repo%3AWordPress%2Fgutenberg%20%40wordpress%2Finteractivity&type=code) but its use is still very limited. +### Table of Contents +- [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) -## Frequently Asked Questions +#### 1. Scaffold an interactive block -At this point, some of the questions you have about the Interactivity API may be: +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. -### What is this? +``` +npx @wordpress/create-block@latest my-first-interactive-block --template @wordpress/create-block-interactive-template +``` -This is the base of a new standard to create interactive blocks. Read [the proposal](https://make.wordpress.org/core/2023/03/30/proposal-the-interactivity-api-a-better-developer-experience-in-building-interactive-blocks/) to learn more about this. +#### 2. Generate the build -### Can I use it? +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. -You can test it, but it's still very experimental. +``` +cd my-first-interactive-block && npm start +``` -### How do I get started? +#### 3. Use it in your WordPress installation -The best place to start with the Interactivity API is this [**Getting started guide**](https://github.com/WordPress/gutenberg/blob/trunk/packages/interactivity/docs/1-getting-started.md). There you'll will find a very quick start guide and the current 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 from the generated folder (and from a different terminal window or tab) the following command -### Where can I ask questions? +``` +npx @wp-now/wp-now start +``` -The [“Interactivity API” category](https://github.com/WordPress/gutenberg/discussions/categories/interactivity-api) in Gutenberg repo discussions is the best place to ask questions about the Interactivity API. +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. -### Where can I share my feedback about the API? +### Requirements of the Interactivity API -The [“Interactivity API” category](https://github.com/WordPress/gutenberg/discussions/categories/interactivity-api) in Gutenberg repo discussions is also the best place to share your feedback about the Interactivity API. +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: -## Installation +#### A local 6.5 WordPress installation -Install the module: +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. -```bash -npm install @wordpress/interactivity --save +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 to have Gutenberg 17.5 or higher version installed and activated in your WordPress installation. + +#### Node.js + +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. + +#### 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` + +``` +"supports": { + "interactivity": true +}, ``` -_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._ +##### 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` -## Docs & Examples -**[Interactivity API Documentation](https://github.com/WordPress/gutenberg/tree/trunk/packages/interactivity/docs)** is the best place to learn about this proposal. Although it's still in progress, some key pages are already available: +```html +
+ +
+``` -- **[Getting Started Guide](https://github.com/WordPress/gutenberg/blob/trunk/packages/interactivity/docs/1-getting-started.md)**: Follow this Getting Started guide to learn how to scaffold a new project and create your first interactive blocks. -- **[API Reference](https://github.com/WordPress/gutenberg/blob/trunk/packages/interactivity/docs/2-api-reference.md)**: Check this page for technical detailed explanations and examples of the directives and the store. +## 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/). + +## 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)** +- [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/) - 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 -

Code is Poetry.

+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. + +

Code is Poetry.

diff --git a/packages/interactivity/docs/1-getting-started.md b/packages/interactivity/docs/1-getting-started.md deleted file mode 100644 index 4e8c1086da695d..00000000000000 --- a/packages/interactivity/docs/1-getting-started.md +++ /dev/null @@ -1,87 +0,0 @@ -# Getting started with the Interactivity API - -To get started with the Interactivity API, you can follow this [**Quick Start Guide**](#quick-start-guide) by taking into account the [current requirements of the Interactivity API](#requirements-of-the-interactivity-api) (especially the need for Gutenberg 16.2 or later). - -## Table of Contents - -- [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) - -## Quick Start Guide - -#### 1. Scaffold an interactive block - -We can scaffold 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) with the `@wordpress/create-block` command. - -``` -npx @wordpress/create-block@latest my-first-interactive-block --template @wordpress/create-block-interactive-template -``` - -#### 2. Generate the build - -When the plugin folder is generated, we should launch the build process to get the final version of the interactive block that can be used from WordPress. - -``` -cd my-first-interactive-block && npm start -``` - -#### 3. Use it in your WordPress installation - -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 - -``` -npx @wp-now/wp-now start -``` - -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. - -> **Note** -> We recommend you to also check the [API Reference](./2-api-reference.md) docs for your first exploration of the Interactivity API - -## Requirements of the Interactivity API - -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: - -#### A local 6.5 WordPress installation - -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. - -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 to have Gutenberg 17.5 or higher version installed and activated in your WordPress installation. - -#### Node.js - -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. - -#### Code requirements - -##### Add `interactivity` support to `block.json` - -To indicate that our block [supports](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/) the Interactivity API features, we do so by adding `"interactivity": true` to the `supports` attribute of our block's `block.json` - -``` -"supports": { - "interactivity": true -}, -``` - -##### Add `wp-interactive` directive to a DOM element - -To "activate" the Interactivity API in a DOM element (and its children) we add the [`wp-interactive` directive](./2-api-reference.md#wp-interactive) to it from our `render.php` or `save.js` - - -```html -
- -
-``` diff --git a/packages/interactivity/docs/README.md b/packages/interactivity/docs/README.md deleted file mode 100644 index e63ed6b82e4201..00000000000000 --- a/packages/interactivity/docs/README.md +++ /dev/null @@ -1,33 +0,0 @@ -# Interactivity API Docs - -👋 Hi! Welcome to the Interactivity API documentation. - - -> Interactivity API is a current [proposal](https://make.wordpress.org/core/2023/03/30/proposal-the-interactivity-api-a-better-developer-experience-in-building-interactive-blocks/) that **is only available in Gutenberg** at the moment and not in WordPress Core as it is still very experimental, and very likely to change. - -> As part of an [Open Source project](https://developer.wordpress.org/block-editor/getting-started/faq/#the-gutenberg-project) we encourage participation 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. - - -## Quick start - -The best place to start with the Interactivity API is this [**Getting started guide**](1-getting-started.md). There you'll will find a very quick start guide and the current requirements of the Interactivity API. - -## Take a deep dive - -At the [**API Reference**](2-api-reference.md) page you'll find detailed technical descriptions for the *Directives* and *Store* which are the main elements of the Interactivity API. - -You can also check [Getting Started - and other learning resources](https://github.com/WordPress/gutenberg/discussions/52894) among other [discussions in GitHub](https://github.com/WordPress/gutenberg/discussions/categories/interactivity-api) to learn more on this proposal. - -## Get Involved - -Feel free to open pull requests to improve any part of these docs, or to add other sections or files to the docs. - -If you are willing to help with the documentation, please add a comment to [#51928](https://github.com/WordPress/gutenberg/discussions/51928), and we'll coordinate everyone's efforts. - -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)** - -## 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. - -

Code is Poetry.

diff --git a/packages/interactivity/docs/2-api-reference.md b/packages/interactivity/docs/api-reference.md similarity index 97% rename from packages/interactivity/docs/2-api-reference.md rename to packages/interactivity/docs/api-reference.md index fa06bae4fedf88..7ca73c03fe2349 100644 --- a/packages/interactivity/docs/2-api-reference.md +++ b/packages/interactivity/docs/api-reference.md @@ -7,7 +7,7 @@ To add interactivity to blocks using the Interactivity API, developers can use: DOM elements are connected to data stored in the state and context through directives. If data in the state or context change directives will react to those changes, updating the DOM accordingly (see [diagram](https://excalidraw.com/#json=T4meh6lltJh6TCX51NTIu,DmIhxYSGFTL_ywZFbsmuSw)). -![State & Directives](assets/state-directives.png) +![State & Directives](./assets/interactivity-state-directives.png) ## Table of Contents @@ -69,7 +69,7 @@ Directives can also be injected dynamically using the [HTML Tag Processor](https ### List of Directives -With directives, we can directly manage interactions related to things such as side effects, state, event handlers, attributes or content. +With directives, you can directly manage interactions related to things such as side effects, state, event handlers, attributes or content. #### `wp-interactive` @@ -659,7 +659,7 @@ It would generate the following output: ``` -The prop that holds the item in the context can be changed by passing a suffix to the directive name. In the following example, we change the default prop `item` to `greeting`. +The prop that holds the item in the context can be changed by passing a suffix to the directive name. In the following example, the default prop changes from `item` to `greeting`. ```html