From d19f572c1a17c6c3de027d0a46f6df0ade836dfe Mon Sep 17 00:00:00 2001 From: Mitchell Austin Date: Thu, 2 May 2024 17:47:08 -0700 Subject: [PATCH 1/4] Update platform docs intro so following it actually works --- platform-docs/docs/intro.md | 95 ++++++++++++++++++++++++------------- 1 file changed, 62 insertions(+), 33 deletions(-) diff --git a/platform-docs/docs/intro.md b/platform-docs/docs/intro.md index 05cfa103492f33..c899c001581cc1 100644 --- a/platform-docs/docs/intro.md +++ b/platform-docs/docs/intro.md @@ -10,11 +10,11 @@ Let's discover how to use the **Gutenberg Block Editor** to build your own block ## What you'll need - [Node.js](https://nodejs.org/en/download/) version 20.10 or above. -- We're going to be using "vite" to setup our single page application (SPA) that contains a block editor. You can use your own setup, and your own application for this. +- We're going to be using "Vite" to setup our single page application (SPA) that contains a block editor. You can use your own setup, and your own application for this. ## Preparing the SPA powered by Vite. -First bootstrap a vite project using `npm create vite@latest` and pick `Vanilla` variant and `JavaScript` as a language. +First bootstrap a Vite project using `npm create vite@latest` and pick `React` variant and `JavaScript` as a language. Once done, you can navigate to your application folder and run it locally using `npm run dev`. Open the displayed local URL in a browser. @@ -22,64 +22,93 @@ Once done, you can navigate to your application folder and run it locally using To build a block editor, you need to install the following dependencies: + - `@wordpress/blocks` - `@wordpress/block-editor` - `@wordpress/block-library` - `@wordpress/components` +## Appease package expectations + +The package `@wordpress/block-library` expects an env variable `IS_GUTENBERG_PLUGIN` to be defined. The quickest way to meet this requirement is to add it with `define` to the Vite config in `vite.config.js`. If using another bundler/build tool refer to its documentation for how to do this. + +```js +import { defineConfig } from 'vite' +import react from '@vitejs/plugin-react' + +// https://vitejs.dev/config/ +export default defineConfig({ + // highlight-next-line + define: { 'process.env.IS_GUTENBERG_PLUGIN': false }, + plugins: [react()], +}) +``` + ## JSX -We're going to be using JSX to write our UI and components. So one of the first steps we need to do is to configure our build tooling, By default vite supports JSX and and outputs the result as a React pragma. The Block editor uses React so there's no need to configure anything here but if you're using a different bundler/build tool, make sure the JSX transpilation is setup properly. +We're going to be using JSX to write our UI and components as the block editor is built with React. Using the Vite bootstrap described above there’s no need to configure anything as it outputs the result as a React pragma. If you're using a different bundler/build tool, you may need to configure the JSX transpilation to do the same. ## Bootstrap your block editor -It's time to render our first block editor. +It's time to render our first block editor. Update your `src/App.jsx` file with the following code: - - Update your `index.jsx` file with the following code: ```jsx -import { createElement, useState } from "react"; -import { createRoot } from 'react-dom/client'; +import { useState } from "react"; import { BlockEditorProvider, BlockCanvas, } from "@wordpress/block-editor"; import { registerCoreBlocks } from "@wordpress/block-library"; +import { getBlockTypes } from "@wordpress/blocks"; // Default styles that are needed for the editor. -import "@wordpress/components/build-style/style.css"; -import "@wordpress/block-editor/build-style/style.css"; +import componentsStyles from "@wordpress/components/build-style/style.css?raw"; +import blockEditorStyles from "@wordpress/block-editor/build-style/style.css?raw"; +import blockEditorContentStyles from "@wordpress/block-editor/build-style/content.css?raw"; // Default styles that are needed for the core blocks. -import "@wordpress/block-library/build-style/common.css"; -import "@wordpress/block-library/build-style/style.css"; -import "@wordpress/block-library/build-style/editor.css"; - -// Register the default core block types. -registerCoreBlocks(); - -function Editor() { +import blocksCommonStyles from "@wordpress/block-library/build-style/common.css?raw"; +import blocksStyles from "@wordpress/block-library/build-style/style.css?raw"; +import blocksEditorStyles from "@wordpress/block-library/build-style/editor.css?raw"; + +const styles = ` + ${ componentsStyles } + ${ blockEditorStyles } + ${ blockEditorContentStyles } + ${ blocksCommonStyles } + ${ blocksStyles } + ${ blocksEditorStyles } +`; + +const registeredBlockTypes = getBlockTypes(); +// Registers the default core block types, avoiding doing so again during HMR. +if ( + ! registeredBlockTypes.length || + ! registeredBlockTypes.some((blockType) => blockType.name.startsWith('core/')) +) registerCoreBlocks(); + +export default function Editor() { const [blocks, setBlocks] = useState([]); return ( - /* - The BlockEditorProvider is the wrapper of the block editor's state. - All the UI elements of the block editor need to be rendered within this provider. - */ - + <> + {/* + The BlockEditorProvider is the wrapper of the block editor's state. + All the UI elements of the block editor need to be rendered within this provider. + */} + + {/* The BlockCanvas component renders the block list within an iframe - and wire up all the necessary events to make the block editor work. + and wires up all the necessary events to make the block editor work. */} - - + + + ); } - -// Render your React component instead -const root = createRoot(document.getElementById("app")); -root.render(); ``` That's it! You now have a very basic block editor with several block types included by default: paragraphs, headings, lists, quotes, images... From 39868a53bb241f1a8b075581dbeb842d2901e3ad Mon Sep 17 00:00:00 2001 From: Mitchell Austin Date: Mon, 9 Dec 2024 17:40:38 -0800 Subject: [PATCH 2/4] Remove outdated part about IS_GUTENBERG_PLUGIN env variable --- platform-docs/docs/intro.md | 16 ---------------- 1 file changed, 16 deletions(-) diff --git a/platform-docs/docs/intro.md b/platform-docs/docs/intro.md index c899c001581cc1..6b815f807bf103 100644 --- a/platform-docs/docs/intro.md +++ b/platform-docs/docs/intro.md @@ -27,22 +27,6 @@ To build a block editor, you need to install the following dependencies: - `@wordpress/block-library` - `@wordpress/components` -## Appease package expectations - -The package `@wordpress/block-library` expects an env variable `IS_GUTENBERG_PLUGIN` to be defined. The quickest way to meet this requirement is to add it with `define` to the Vite config in `vite.config.js`. If using another bundler/build tool refer to its documentation for how to do this. - -```js -import { defineConfig } from 'vite' -import react from '@vitejs/plugin-react' - -// https://vitejs.dev/config/ -export default defineConfig({ - // highlight-next-line - define: { 'process.env.IS_GUTENBERG_PLUGIN': false }, - plugins: [react()], -}) -``` - ## JSX We're going to be using JSX to write our UI and components as the block editor is built with React. Using the Vite bootstrap described above there’s no need to configure anything as it outputs the result as a React pragma. If you're using a different bundler/build tool, you may need to configure the JSX transpilation to do the same. From 8e07f04c5222d15a133f66c725277957c91886bd Mon Sep 17 00:00:00 2001 From: Mitchell Austin Date: Tue, 10 Dec 2024 15:15:51 -0800 Subject: [PATCH 3/4] Revise instructions --- platform-docs/docs/intro.md | 93 +++++++++++++++++++------------------ 1 file changed, 47 insertions(+), 46 deletions(-) diff --git a/platform-docs/docs/intro.md b/platform-docs/docs/intro.md index 6b815f807bf103..3eb79c31875eca 100644 --- a/platform-docs/docs/intro.md +++ b/platform-docs/docs/intro.md @@ -4,8 +4,7 @@ sidebar_position: 1 # Getting Started -Let's discover how to use the **Gutenberg Block Editor** to build your own block editor in less than 10 minutes**. - +Let's discover how to use the **Gutenberg Block Editor** to build your own block editor in less than 10 minutes. ## What you'll need @@ -22,7 +21,6 @@ Once done, you can navigate to your application folder and run it locally using To build a block editor, you need to install the following dependencies: - - `@wordpress/blocks` - `@wordpress/block-editor` - `@wordpress/block-library` - `@wordpress/components` @@ -33,7 +31,26 @@ We're going to be using JSX to write our UI and components as the block editor i ## Bootstrap your block editor -It's time to render our first block editor. Update your `src/App.jsx` file with the following code: +It's time to render our first block editor. We’ll do this with changes to three files – `index.html`, `src/main.jsx`, and `src/App.jsx`. + +First, we’ll add the base styles are for the editor UI. In `index.html` add these styles in the ``: +```html + + +``` +:::note + +There are more styles needed but can’t be added here because they are for the editor’s content which is in a separate document within an `