From 3fb8e701868d474033eff5cf2ca9b0ba35965d37 Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Thu, 29 Jun 2023 08:22:25 +0100 Subject: [PATCH 01/11] first version of the Interactivity API README --- packages/interactivity/README.md | 65 +++++++++++++++++++++++++++++++- 1 file changed, 64 insertions(+), 1 deletion(-) diff --git a/packages/interactivity/README.md b/packages/interactivity/README.md index 508cc06588f752..621bb541b7f252 100644 --- a/packages/interactivity/README.md +++ b/packages/interactivity/README.md @@ -1 +1,64 @@ -# Interactivity +# Interactivity API + +## Installation + +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._ + +## Usage + +```js +import { store } from '@wordpress/interactivity'; + +store( { + effects: { + core: { + navigation: { + initMenu: ( { context, selectors, ref } ) => { + // ... some magic happens with this effect + } + }, + }, + }, + selectors: { + core: { + navigation: { + isMenuOpen: ( { context } ) => { + // ... some magic info is returned with this selector + } + }, + }, + }, + actions: { + core: { + navigation: { + openMenuOnHover( args ) { + // ... some magic happens on this action + }, + }, + }, +} ); +``` + +## Docs & Examples + +Interactivity API is a recent proposal and its Documentation is still in progress. In the meantime, here you have these resources to learn/read more about the 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” category](https://github.com/WordPress/gutenberg/discussions/categories/interactivity-api) in Gutenberg repo discussions +block-interactivity-experiments repo and its discussions section +- 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 + +## Contributing to this package + +This is an individual package that's part of the Gutenberg project. The project is organized as a monorepo. It's made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to [npm](https://www.npmjs.com/) and used by [WordPress](https://make.wordpress.org/core/) as well as other software projects. + +To find out more about contributing to this package or Gutenberg as a whole, please read the project's main [contributor guide](https://github.com/WordPress/gutenberg/tree/HEAD/CONTRIBUTING.md). + +

Code is Poetry.

From 5cce55e7ac7f73ee4268e136faf561bfebdbf6ce Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Thu, 29 Jun 2023 09:45:12 +0100 Subject: [PATCH 02/11] README v2 upon Luis feedback --- packages/interactivity/README.md | 77 +++++++++++++++----------------- 1 file changed, 35 insertions(+), 42 deletions(-) diff --git a/packages/interactivity/README.md b/packages/interactivity/README.md index 621bb541b7f252..aedac8d2f34ab9 100644 --- a/packages/interactivity/README.md +++ b/packages/interactivity/README.md @@ -1,5 +1,40 @@ # 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/explanations/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 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. + + +## Frequently Asked Questions + +At this point, some of the questions you have about the Interactivity API may be: + +##### What is this? + +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. + +##### Can I use it? + +You can test it, but it's still very experimental. + +##### How do I get started? + +A "Getting started guide" section of the Interactivity API Docs is in progress. In the meantime check the **Docs & Examples** section below for resources to learn. You can also ask for guidance at the [“Interactivity API” category](https://github.com/WordPress/gutenberg/discussions/categories/interactivity-api) in the Gutenberg repo. + +##### Where can I ask questions? + +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. + +##### Where can I share my feedback about the 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. + ## Installation Install the module: @@ -10,55 +45,13 @@ 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._ -## Usage - -```js -import { store } from '@wordpress/interactivity'; - -store( { - effects: { - core: { - navigation: { - initMenu: ( { context, selectors, ref } ) => { - // ... some magic happens with this effect - } - }, - }, - }, - selectors: { - core: { - navigation: { - isMenuOpen: ( { context } ) => { - // ... some magic info is returned with this selector - } - }, - }, - }, - actions: { - core: { - navigation: { - openMenuOnHover( args ) { - // ... some magic happens on this action - }, - }, - }, -} ); -``` - ## Docs & Examples Interactivity API is a recent proposal and its Documentation is still in progress. In the meantime, here you have these resources to learn/read more about the 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” category](https://github.com/WordPress/gutenberg/discussions/categories/interactivity-api) in Gutenberg repo discussions -block-interactivity-experiments repo and its discussions section - 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 -## Contributing to this package - -This is an individual package that's part of the Gutenberg project. The project is organized as a monorepo. It's made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to [npm](https://www.npmjs.com/) and used by [WordPress](https://make.wordpress.org/core/) as well as other software projects. - -To find out more about contributing to this package or Gutenberg as a whole, please read the project's main [contributor guide](https://github.com/WordPress/gutenberg/tree/HEAD/CONTRIBUTING.md). -

Code is Poetry.

From 65b6dd4bea40a0f798311c50ad254e0c772d9d60 Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Thu, 29 Jun 2023 09:48:25 +0100 Subject: [PATCH 03/11] headings adjusted --- packages/interactivity/README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/packages/interactivity/README.md b/packages/interactivity/README.md index aedac8d2f34ab9..00fb60e75aedab 100644 --- a/packages/interactivity/README.md +++ b/packages/interactivity/README.md @@ -15,23 +15,23 @@ The Interactivity API is [being used in some core blocks](https://github.com/sea At this point, some of the questions you have about the Interactivity API may be: -##### What is this? +#### What is this? 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. -##### Can I use it? +#### Can I use it? You can test it, but it's still very experimental. -##### How do I get started? +#### How do I get started? A "Getting started guide" section of the Interactivity API Docs is in progress. In the meantime check the **Docs & Examples** section below for resources to learn. You can also ask for guidance at the [“Interactivity API” category](https://github.com/WordPress/gutenberg/discussions/categories/interactivity-api) in the Gutenberg repo. -##### Where can I ask questions? +#### Where can I ask questions? 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. -##### Where can I share my feedback about the API? +#### Where can I share my feedback about the 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. From 053962a7881f908323f548e11bea602015afa67b Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Thu, 29 Jun 2023 10:42:04 +0100 Subject: [PATCH 04/11] minor adjustments --- packages/interactivity/README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/packages/interactivity/README.md b/packages/interactivity/README.md index 00fb60e75aedab..1643d519555d2a 100644 --- a/packages/interactivity/README.md +++ b/packages/interactivity/README.md @@ -15,23 +15,23 @@ The Interactivity API is [being used in some core blocks](https://github.com/sea At this point, some of the questions you have about the Interactivity API may be: -#### What is this? +### What is this? 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. -#### Can I use it? +### Can I use it? You can test it, but it's still very experimental. -#### How do I get started? +### How do I get started? -A "Getting started guide" section of the Interactivity API Docs is in progress. In the meantime check the **Docs & Examples** section below for resources to learn. You can also ask for guidance at the [“Interactivity API” category](https://github.com/WordPress/gutenberg/discussions/categories/interactivity-api) in the Gutenberg repo. +A "Getting started guide" section of the Interactivity API Docs is in progress. In the meantime check the **Docs & Examples** section below for resources to learn. You can also ask for guidance at the [“Interactivity API” category](https://github.com/WordPress/gutenberg/discussions/categories/interactivity-api) in Gutenberg repo discussions. -#### Where can I ask questions? +### Where can I ask questions? 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. -#### Where can I share my feedback about the API? +### Where can I share my feedback about the 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. From d109470b7842046fbf78bfb0aa9a9441c40a15b3 Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Mon, 10 Jul 2023 09:45:18 +0100 Subject: [PATCH 05/11] add docs folder --- .../docs/1-getting-started/README.md | 2 ++ .../docs/2-about-interactivity-api/README.md | 1 + packages/interactivity/docs/README.md | 28 +++++++++++++++++++ 3 files changed, 31 insertions(+) create mode 100644 packages/interactivity/docs/1-getting-started/README.md create mode 100644 packages/interactivity/docs/2-about-interactivity-api/README.md create mode 100644 packages/interactivity/docs/README.md diff --git a/packages/interactivity/docs/1-getting-started/README.md b/packages/interactivity/docs/1-getting-started/README.md new file mode 100644 index 00000000000000..9f01561e200e12 --- /dev/null +++ b/packages/interactivity/docs/1-getting-started/README.md @@ -0,0 +1,2 @@ +## Getting started with the Interactivity API + diff --git a/packages/interactivity/docs/2-about-interactivity-api/README.md b/packages/interactivity/docs/2-about-interactivity-api/README.md new file mode 100644 index 00000000000000..76dedcf21dc7a7 --- /dev/null +++ b/packages/interactivity/docs/2-about-interactivity-api/README.md @@ -0,0 +1 @@ +## About the Interactivity API \ No newline at end of file diff --git a/packages/interactivity/docs/README.md b/packages/interactivity/docs/README.md new file mode 100644 index 00000000000000..25d1ae0ac45801 --- /dev/null +++ b/packages/interactivity/docs/README.md @@ -0,0 +1,28 @@ +# Interactivity API Docs + +👋 Hi! Welcome to the Interactivity API documentation. + +The documentation consists of two major sections: + +- [Documentation]() (you're here) – Introduction, concepts, and guides +- [API reference]() – All the APIs exposed by the Interactivity API + +This site (Documentation) is where you will find all the information you need to start doing something awesome things with the Interactivity API. + +## Quick start + + + +## Take a deep dive + + + +## Get Involved + + + +## License + + + +

Code is Poetry.

From 62b1654b86f991c669cfb49ed8807ea5dabb044d Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Wed, 12 Jul 2023 17:35:18 +0100 Subject: [PATCH 06/11] requirements --- .../docs/1-getting-started/README.md | 29 ++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/packages/interactivity/docs/1-getting-started/README.md b/packages/interactivity/docs/1-getting-started/README.md index 9f01561e200e12..4ba4ca5e8c075a 100644 --- a/packages/interactivity/docs/1-getting-started/README.md +++ b/packages/interactivity/docs/1-getting-started/README.md @@ -1,2 +1,29 @@ -## Getting started with the Interactivity API +# Getting started with the Interactivity API +> **Note** +> This Interactivity API [is currently in a experimental phase](#) + +The Interactivity API is a standard system of directives, based on declarative code, for adding frontend interactivity to blocks. + +## Requirements + +To get started with Interactivity API you'll need to have a [proper WordPress development environment for blocks](https://developer.wordpress.org/block-editor/getting-started/devenv/) which should include: + +- A local WordPress installation +- Gutenberg 16.2 or superior +- Node v14 + +### A local WordPress installation + +You can use [the tool 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 started, [`wp-now`](https://www.npmjs.com/package/@wp-now/wp-now) is the fastest way to get a WordPress site up and running. + +### Gutenberg 16.2 or superior + +The Interactivity API is currently only available as an experimental feature from Gutenberg 16.2, so you'll need to have the Gutenberg plugin with this version (or a superior one), installed and activated. + +### Node v14 + +Block development requires Node, so you also need to get [Node v14](https://developer.wordpress.org/block-editor/getting-started/devenv/#node-development-tools) installed and running on your machine + + +## Quick Start Guide \ No newline at end of file From d10653b5923f28e440eaa6deb4cbf8b7aefaad0b Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Fri, 14 Jul 2023 11:38:04 +0100 Subject: [PATCH 07/11] minor adjustment --- packages/interactivity/docs/1-getting-started/README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/packages/interactivity/docs/1-getting-started/README.md b/packages/interactivity/docs/1-getting-started/README.md index 4ba4ca5e8c075a..6e0d77cb28d31f 100644 --- a/packages/interactivity/docs/1-getting-started/README.md +++ b/packages/interactivity/docs/1-getting-started/README.md @@ -15,15 +15,17 @@ To get started with Interactivity API you'll need to have a [proper WordPress de ### A local WordPress installation -You can use [the tool 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 started, [`wp-now`](https://www.npmjs.com/package/@wp-now/wp-now) is the fastest way to get a WordPress site up and running. +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 started, [`wp-now`](https://github.com/WordPress/playground-tools/tree/trunk/packages/wp-now) is the fastest way to get a WordPress site up and running. ### Gutenberg 16.2 or superior -The Interactivity API is currently only available as an experimental feature from Gutenberg 16.2, so you'll need to have the Gutenberg plugin with this version (or a superior one), installed and activated. +The Interactivity API is currently only available as an experimental feature from Gutenberg 16.2, so you'll need to have the Gutenberg plugin with this version or a superior one, installed and activated in your WordPress installation. ### Node v14 -Block development requires Node, so you also need to get [Node v14](https://developer.wordpress.org/block-editor/getting-started/devenv/#node-development-tools) installed and running on your machine +Block development requires Node, so you also need to ensure you have [Node v14](https://developer.wordpress.org/block-editor/getting-started/devenv/#node-development-tools) installed and running on your machine ## Quick Start Guide \ No newline at end of file From 8b8af12bfaa5aa5bf4ee5c6dbd219399feaba09f Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Fri, 14 Jul 2023 15:30:23 +0100 Subject: [PATCH 08/11] proper getting started structure --- .../1-getting-started/1-1-requirements.md | 21 ++++++++++++++++ .../1-2-quick-start-guide.md | 2 ++ .../docs/1-getting-started/README.md | 25 +------------------ 3 files changed, 24 insertions(+), 24 deletions(-) create mode 100644 packages/interactivity/docs/1-getting-started/1-1-requirements.md create mode 100644 packages/interactivity/docs/1-getting-started/1-2-quick-start-guide.md diff --git a/packages/interactivity/docs/1-getting-started/1-1-requirements.md b/packages/interactivity/docs/1-getting-started/1-1-requirements.md new file mode 100644 index 00000000000000..53f3ef03ed7fdb --- /dev/null +++ b/packages/interactivity/docs/1-getting-started/1-1-requirements.md @@ -0,0 +1,21 @@ +# Requirements + +To get started with Interactivity API you'll need to have a [proper WordPress development environment for blocks](https://developer.wordpress.org/block-editor/getting-started/devenv/) which should include: + +- A local WordPress installation +- Gutenberg 16.2 or superior +- Node v14 + +## A local 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 started, [`wp-now`](https://github.com/WordPress/playground-tools/tree/trunk/packages/wp-now) is the fastest way to get a WordPress site up and running. + +## Gutenberg 16.2 or superior + +The Interactivity API is currently only available as an experimental feature from Gutenberg 16.2, so you'll need to have the Gutenberg plugin with this version or a superior one, installed and activated in your WordPress installation. + +## Node v14 + +Block development requires Node, so you also need to ensure you have [Node v14](https://developer.wordpress.org/block-editor/getting-started/devenv/#node-development-tools) installed and running on your machine diff --git a/packages/interactivity/docs/1-getting-started/1-2-quick-start-guide.md b/packages/interactivity/docs/1-getting-started/1-2-quick-start-guide.md new file mode 100644 index 00000000000000..0fe96ed357b237 --- /dev/null +++ b/packages/interactivity/docs/1-getting-started/1-2-quick-start-guide.md @@ -0,0 +1,2 @@ +# Quick Start Guide + diff --git a/packages/interactivity/docs/1-getting-started/README.md b/packages/interactivity/docs/1-getting-started/README.md index 6e0d77cb28d31f..cdc5b3e48af1e3 100644 --- a/packages/interactivity/docs/1-getting-started/README.md +++ b/packages/interactivity/docs/1-getting-started/README.md @@ -5,27 +5,4 @@ The Interactivity API is a standard system of directives, based on declarative code, for adding frontend interactivity to blocks. -## Requirements - -To get started with Interactivity API you'll need to have a [proper WordPress development environment for blocks](https://developer.wordpress.org/block-editor/getting-started/devenv/) which should include: - -- A local WordPress installation -- Gutenberg 16.2 or superior -- Node v14 - -### A local 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 started, [`wp-now`](https://github.com/WordPress/playground-tools/tree/trunk/packages/wp-now) is the fastest way to get a WordPress site up and running. - -### Gutenberg 16.2 or superior - -The Interactivity API is currently only available as an experimental feature from Gutenberg 16.2, so you'll need to have the Gutenberg plugin with this version or a superior one, installed and activated in your WordPress installation. - -### Node v14 - -Block development requires Node, so you also need to ensure you have [Node v14](https://developer.wordpress.org/block-editor/getting-started/devenv/#node-development-tools) installed and running on your machine - - -## Quick Start Guide \ No newline at end of file +To get started with Interactivity API, first check you meet the requirements on your local machine and then follow this Quick Start Guide. \ No newline at end of file From b202edaaee5d77b664c43bfe15f753ab9f2edc2a Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Fri, 14 Jul 2023 17:10:43 +0100 Subject: [PATCH 09/11] first version structure and contents --- .../interactivity/docs/1-getting-started.md | 53 +++++++++++++++++++ .../1-getting-started/1-1-requirements.md | 21 -------- .../1-2-quick-start-guide.md | 2 - .../docs/1-getting-started/README.md | 8 --- .../docs/2-about-interactivity-api/README.md | 1 - packages/interactivity/docs/README.md | 10 +--- 6 files changed, 55 insertions(+), 40 deletions(-) create mode 100644 packages/interactivity/docs/1-getting-started.md delete mode 100644 packages/interactivity/docs/1-getting-started/1-1-requirements.md delete mode 100644 packages/interactivity/docs/1-getting-started/1-2-quick-start-guide.md delete mode 100644 packages/interactivity/docs/1-getting-started/README.md delete mode 100644 packages/interactivity/docs/2-about-interactivity-api/README.md diff --git a/packages/interactivity/docs/1-getting-started.md b/packages/interactivity/docs/1-getting-started.md new file mode 100644 index 00000000000000..3d57c43be58a86 --- /dev/null +++ b/packages/interactivity/docs/1-getting-started.md @@ -0,0 +1,53 @@ +# Getting started with the Interactivity API + +To get started with the Interactivity API, you can follow this [**Quick Start Guide**](#) by taking into account the [current requirements of the Interactivity API](#) (especially the need for Gutenberg 16.2 or superior). + +## 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 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 "Example Interactive" block into any post, and see how it behaves in the frontent when published. + +## 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/) which should include: + +- A local WordPress installation +- Gutenberg 16.2 or superior +- Node v14 + +### A local 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://github.com/WordPress/playground-tools/tree/trunk/packages/wp-now) is the easiest way to get a WordPress site up and running locally. + +### Gutenberg 16.2 or superior + +The Interactivity API is currently only available as an experimental feature from Gutenberg 16.2, so you'll need to have the Gutenberg plugin with this version or a superior one, installed and activated in your WordPress installation. + +### Node v14 + +Block development requires Node, so you also need to ensure you have [the proper version of Node](https://developer.wordpress.org/block-editor/getting-started/devenv/#node-development-tools) installed and running on your machine \ No newline at end of file diff --git a/packages/interactivity/docs/1-getting-started/1-1-requirements.md b/packages/interactivity/docs/1-getting-started/1-1-requirements.md deleted file mode 100644 index 53f3ef03ed7fdb..00000000000000 --- a/packages/interactivity/docs/1-getting-started/1-1-requirements.md +++ /dev/null @@ -1,21 +0,0 @@ -# Requirements - -To get started with Interactivity API you'll need to have a [proper WordPress development environment for blocks](https://developer.wordpress.org/block-editor/getting-started/devenv/) which should include: - -- A local WordPress installation -- Gutenberg 16.2 or superior -- Node v14 - -## A local 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 started, [`wp-now`](https://github.com/WordPress/playground-tools/tree/trunk/packages/wp-now) is the fastest way to get a WordPress site up and running. - -## Gutenberg 16.2 or superior - -The Interactivity API is currently only available as an experimental feature from Gutenberg 16.2, so you'll need to have the Gutenberg plugin with this version or a superior one, installed and activated in your WordPress installation. - -## Node v14 - -Block development requires Node, so you also need to ensure you have [Node v14](https://developer.wordpress.org/block-editor/getting-started/devenv/#node-development-tools) installed and running on your machine diff --git a/packages/interactivity/docs/1-getting-started/1-2-quick-start-guide.md b/packages/interactivity/docs/1-getting-started/1-2-quick-start-guide.md deleted file mode 100644 index 0fe96ed357b237..00000000000000 --- a/packages/interactivity/docs/1-getting-started/1-2-quick-start-guide.md +++ /dev/null @@ -1,2 +0,0 @@ -# Quick Start Guide - diff --git a/packages/interactivity/docs/1-getting-started/README.md b/packages/interactivity/docs/1-getting-started/README.md deleted file mode 100644 index cdc5b3e48af1e3..00000000000000 --- a/packages/interactivity/docs/1-getting-started/README.md +++ /dev/null @@ -1,8 +0,0 @@ -# Getting started with the Interactivity API - -> **Note** -> This Interactivity API [is currently in a experimental phase](#) - -The Interactivity API is a standard system of directives, based on declarative code, for adding frontend interactivity to blocks. - -To get started with Interactivity API, first check you meet the requirements on your local machine and then follow this Quick Start Guide. \ No newline at end of file diff --git a/packages/interactivity/docs/2-about-interactivity-api/README.md b/packages/interactivity/docs/2-about-interactivity-api/README.md deleted file mode 100644 index 76dedcf21dc7a7..00000000000000 --- a/packages/interactivity/docs/2-about-interactivity-api/README.md +++ /dev/null @@ -1 +0,0 @@ -## About the Interactivity API \ No newline at end of file diff --git a/packages/interactivity/docs/README.md b/packages/interactivity/docs/README.md index 25d1ae0ac45801..fc20d74446b426 100644 --- a/packages/interactivity/docs/README.md +++ b/packages/interactivity/docs/README.md @@ -2,16 +2,10 @@ 👋 Hi! Welcome to the Interactivity API documentation. -The documentation consists of two major sections: - -- [Documentation]() (you're here) – Introduction, concepts, and guides -- [API reference]() – All the APIs exposed by the Interactivity API - -This site (Documentation) is where you will find all the information you need to start doing something awesome things with the Interactivity API. - ## 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 From aaf039c4f059bb8abdc876c4ab044f6986cc2991 Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Mon, 17 Jul 2023 14:57:17 +0100 Subject: [PATCH 10/11] removed references to specific versions of Node --- packages/interactivity/docs/1-getting-started.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/packages/interactivity/docs/1-getting-started.md b/packages/interactivity/docs/1-getting-started.md index 3d57c43be58a86..96c18beb0925b9 100644 --- a/packages/interactivity/docs/1-getting-started.md +++ b/packages/interactivity/docs/1-getting-started.md @@ -42,12 +42,12 @@ To start working with the Interactivity API you'll need to have a [proper WordPr 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://github.com/WordPress/playground-tools/tree/trunk/packages/wp-now) is the easiest way to get a WordPress site up and running locally. +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. -### Gutenberg 16.2 or superior +### Latest vesion of Gutenberg (v16.2 or superior) -The Interactivity API is currently only available as an experimental feature from Gutenberg 16.2, so you'll need to have the Gutenberg plugin with this version or a superior one, installed and activated in your WordPress installation. +The Interactivity API is currently only available as an experimental feature from Gutenberg 16.2, so you'll need to have the latest version of the Gutenberg plugin (or at least v16.2) installed and activated in your WordPress installation. -### Node v14 +### Node -Block development requires Node, so you also need to ensure you have [the proper version of Node](https://developer.wordpress.org/block-editor/getting-started/devenv/#node-development-tools) installed and running on your machine \ No newline at end of file +Block development requires [Node](https://nodejs.org/en), so you'll need to have Node installed and running on your machine. Any version 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. \ No newline at end of file From 993c5df5a22d2f4be261f3c1127ff7184040216c Mon Sep 17 00:00:00 2001 From: JuanMa Garrido Date: Mon, 17 Jul 2023 17:57:46 +0100 Subject: [PATCH 11/11] minor adjustments --- packages/interactivity/docs/1-getting-started.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/interactivity/docs/1-getting-started.md b/packages/interactivity/docs/1-getting-started.md index 96c18beb0925b9..8ab73c3075b234 100644 --- a/packages/interactivity/docs/1-getting-started.md +++ b/packages/interactivity/docs/1-getting-started.md @@ -1,6 +1,6 @@ # Getting started with the Interactivity API -To get started with the Interactivity API, you can follow this [**Quick Start Guide**](#) by taking into account the [current requirements of the Interactivity API](#) (especially the need for Gutenberg 16.2 or superior). +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 superior). ## Quick Start Guide @@ -28,7 +28,7 @@ If you have a local WordPress installation already running, you can launch the c npx @wp-now/wp-now start ``` -At this point you should be able to insert the "Example Interactive" block into any post, and see how it behaves in the frontent when published. +At this point you should be able to insert the "Example Interactive" block into any post, and see how it behaves in the frontend when published. ## Requirements of the Interactivity API @@ -36,7 +36,7 @@ To start working with the Interactivity API you'll need to have a [proper WordPr - A local WordPress installation - Gutenberg 16.2 or superior -- Node v14 +- Node.js ### A local WordPress installation