From 72e546a1236df3e25846c32fe95e24ca83c2516f Mon Sep 17 00:00:00 2001 From: Nick Diego Date: Sun, 28 Jan 2024 14:11:36 -0600 Subject: [PATCH] Remove duplicate content and update links. --- docs/contributors/documentation/README.md | 2 +- .../applying-styles-with-stylesheets.md | 2 +- .../block-controls-toolbar-and-sidebar.md | 191 ------------------ .../writing-your-first-block-type.md | 174 ---------------- docs/how-to-guides/plugin-sidebar-0.md | 2 +- docs/manifest.json | 6 - docs/toc.json | 3 - .../src/components/block-controls/README.md | 4 +- .../src/toolbar/toolbar-button/README.md | 4 +- .../toolbar/toolbar-dropdown-menu/README.md | 4 +- .../src/toolbar/toolbar-item/README.md | 4 +- 11 files changed, 11 insertions(+), 385 deletions(-) delete mode 100644 docs/how-to-guides/block-tutorial/block-controls-toolbar-and-sidebar.md delete mode 100644 docs/how-to-guides/block-tutorial/writing-your-first-block-type.md diff --git a/docs/contributors/documentation/README.md b/docs/contributors/documentation/README.md index cca5c959ed1d9..ec8013cd99a21 100644 --- a/docs/contributors/documentation/README.md +++ b/docs/contributors/documentation/README.md @@ -111,7 +111,7 @@ An example, the link to this page is: `/docs/contributors/documentation/README.m The code example in markdown should be wrapped in three tick marks \`\`\` and should additionally include a language specifier. See this [GitHub documentation around fenced code blocks](https://help.github.com/en/github/writing-on-github/creating-and-highlighting-code-blocks). -A unique feature to the Gutenberg documentation is the `codetabs` toggle, this allows two versions of code to be shown at once. This is used for showing both `JSX` and `Plain` code samples. For example, [on this block tutorial page](/docs/how-to-guides/block-tutorial/block-controls-toolbar-and-sidebar.md). +A unique feature to the Gutenberg documentation is the `codetabs` toggle, this allows two versions of code to be shown at once. This is used for showing both `JSX` and `Plain` code samples. Here is an example `codetabs` section: diff --git a/docs/how-to-guides/block-tutorial/applying-styles-with-stylesheets.md b/docs/how-to-guides/block-tutorial/applying-styles-with-stylesheets.md index 41646bbe527cf..6397b57e83748 100644 --- a/docs/how-to-guides/block-tutorial/applying-styles-with-stylesheets.md +++ b/docs/how-to-guides/block-tutorial/applying-styles-with-stylesheets.md @@ -6,7 +6,7 @@ A block typically inserts markup (HTML) into post content that you want to style ## Before you start -You will need a basic block and WordPress development environment to implement the examples shown in this guide. See the [create a basic block](/docs/how-to-guides/block-tutorial/writing-your-first-block-type.md) or [block tutorial](/docs/getting-started/devenv/get-started-with-create-block.md) to get setup. +You will need a basic block and WordPress development environment to implement the examples shown in this guide. See the [Quick Start Guide](/docs/getting-started/quick-start-guide.md) or [block tutorial](/docs/getting-started/tutorial.md) to get set up. ## Methods to add style diff --git a/docs/how-to-guides/block-tutorial/block-controls-toolbar-and-sidebar.md b/docs/how-to-guides/block-tutorial/block-controls-toolbar-and-sidebar.md deleted file mode 100644 index 4436696b55261..0000000000000 --- a/docs/how-to-guides/block-tutorial/block-controls-toolbar-and-sidebar.md +++ /dev/null @@ -1,191 +0,0 @@ -# Block Controls: Block Toolbar and Settings Sidebar - -To simplify block customization and ensure a consistent experience for users, there are a number of built-in UI patterns to help generate the editor preview. Like with the `RichText` component covered in the previous chapter, the `wp.editor` global includes a few other common components to render editing interfaces. In this chapter, we'll explore toolbars and the block inspector. - -## Block Toolbar - -![Screenshot of the rich text toolbar applied to a Paragraph block inside the block editor](https://raw.githubusercontent.com/WordPress/gutenberg/HEAD/docs/assets/toolbar-text.png) - -When the user selects a block, a number of control buttons may be shown in a toolbar above the selected block. Some of these block-level controls are included automatically if the editor is able to transform the block to another type, or if the focused element is a RichText component. - -You can also customize the toolbar to include controls specific to your block type. If the return value of your block type's `edit` function includes a `BlockControls` element, those controls will be shown in the selected block's toolbar. - -```jsx -import { registerBlockType } from '@wordpress/blocks'; - -import { - useBlockProps, - RichText, - AlignmentToolbar, - BlockControls, -} from '@wordpress/block-editor'; - -registerBlockType( 'gutenberg-examples/example-04-controls-esnext', { - apiVersion: 3, - title: 'Example: Controls (esnext)', - icon: 'universal-access-alt', - category: 'design', - attributes: { - content: { - type: 'string', - source: 'html', - selector: 'p', - }, - alignment: { - type: 'string', - default: 'none', - }, - }, - example: { - attributes: { - content: 'Hello World', - alignment: 'right', - }, - }, - edit: ( { attributes, setAttributes } ) => { - const onChangeContent = ( newContent ) => { - setAttributes( { content: newContent } ); - }; - - const onChangeAlignment = ( newAlignment ) => { - setAttributes( { - alignment: newAlignment === undefined ? 'none' : newAlignment, - } ); - }; - - return ( -
- { - - - - } - -
- ); - }, - save: ( props ) => { - const blockProps = useBlockProps.save(); - - return ( -
- -
- ); - }, -} ); -``` - -Note that `BlockControls` is only visible when the block is currently selected and in visual editing mode. `BlockControls` are not shown when editing a block in HTML editing mode. - -## Settings Sidebar - -![Screenshot of the inspector panel focused on the settings for a Paragraph block](https://raw.githubusercontent.com/WordPress/gutenberg/HEAD/docs/assets/inspector.png) - -The Settings Sidebar is used to display less-often-used settings or settings that require more screen space. The Settings Sidebar should be used for **block-level settings only**. - -If you have settings that affects only selected content inside a block (example: the "bold" setting for selected text inside a paragraph): **do not place it inside the Settings Sidebar**. The Settings Sidebar is displayed even when editing a block in HTML mode, so it should only contain block-level settings. - -The Block Tab is shown in place of the Document Tab when a block is selected. - -Similar to rendering a toolbar, if you include an `InspectorControls` element in the return value of your block type's `edit` function, those controls will be shown in the Settings Sidebar region. -The following example adds 2 color palettes to the sidebar, one for the text color and one for the background color. - -```jsx -import { registerBlockType } from '@wordpress/blocks'; -import { __ } from '@wordpress/i18n'; -import { TextControl } from '@wordpress/components'; - -import { - useBlockProps, - ColorPalette, - InspectorControls, -} from '@wordpress/block-editor'; - -registerBlockType( 'create-block/gutenpride', { - apiVersion: 3, - attributes: { - message: { - type: 'string', - source: 'text', - selector: 'div', - default: '', // empty default - }, - bg_color: { type: 'string', default: '#000000' }, - text_color: { type: 'string', default: '#ffffff' }, - }, - edit: ( { attributes, setAttributes } ) => { - const onChangeBGColor = ( hexColor ) => { - setAttributes( { bg_color: hexColor } ); - }; - - const onChangeTextColor = ( hexColor ) => { - setAttributes( { text_color: hexColor } ); - }; - - return ( -
- -
-
- - { __( 'Background color', 'gutenpride' ) } - - -
-
- - { __( 'Text color', 'gutenpride' ) } - - -
-
- - setAttributes( { message: val } ) } - style={ { - backgroundColor: attributes.bg_color, - color: attributes.text_color, - } } - /> -
- ); - }, - save: ( { attributes } ) => { - return ( -
- { attributes.message } -
- ); - }, -} ); -``` - -Block controls rendered in both the toolbar and sidebar will also be used when -multiple blocks of the same type are selected. - -**Note :** In the example above, we added text and background color customization support to our block to demonstrate the use of `InspectorControls` to add custom controls to the sidebar. That said, for common customization settings including color, border, spacing customization and more, we will see on the [next chapter](/docs/how-to-guides/block-tutorial/block-supports-in-static-blocks.md) that you can rely on block supports to provide the same functionality in a more efficient way. diff --git a/docs/how-to-guides/block-tutorial/writing-your-first-block-type.md b/docs/how-to-guides/block-tutorial/writing-your-first-block-type.md deleted file mode 100644 index 4a690984011e0..0000000000000 --- a/docs/how-to-guides/block-tutorial/writing-your-first-block-type.md +++ /dev/null @@ -1,174 +0,0 @@ -# Create a basic block - -This guide takes you through creating a basic block to display a message in a post. This message will be fixed, we won't allow the user to edit the message, the goal of the guide is to show how to register and load a block. - -## Overview - -There are two main types of blocks: static and dynamic, this guide focuses on static blocks. A static block is used to insert HTML content into the post and save it with the post. A dynamic block builds the content on the fly when rendered on the front end, see the [dynamic blocks guide](/docs/how-to-guides/block-tutorial/creating-dynamic-blocks.md). - -
-This guide focuses on just the block, see the Create a Block tutorial for a complete setup. -
- -## Before you start - -Static blocks are implemented in JavaScript, so a basic level of JavaScript is helpful, see the [Getting Started with JavaScript](/docs/how-to-guides/javascript/README.md) for a refresher. - -Blocks are added to WordPress using plugins, so you will need a WordPress development environment - see the [setup guide](/docs/getting-started/devenv/README.md). - -This tutorial demonstrates the creation of a block in two ways, using JSX and using plain JavaScript. JSX requires a build step, so if you choose to follow the JSX path you will need JavaScript build tools (node/npm). See Step 0 below for details on getting set up. - -## Step-by-step guide - -### Step 0: Set up your project - -_**Note:** this step is only needed if you are going to use the JSX examples in the following steps. If you intend to work with the plain JavaScript examples these will run without a build step so you can proceed straight to 'Step 1: Configure block.json' below._ - -Before starting with the JSX examples you will need to set up your project. In your project directory run: - -```bash -npm init -``` - -This will create a `package.json` file. - -You will then need to add `@wordpress/scripts` as a development dependency to `package.json`. You can do this with: - -```bash -npm install @wordpress/scripts --save-dev -``` - -Next, add the following two lines to the `scripts` property in `package.json`: - -```json -"start": "wp-scripts start", -"build": "wp-scripts build" -``` - -You're all set! - -### Step 1: Configure block.json - -The functions of a static block are defined in JavaScript, however the settings and other metadata should be defined in a block.json file. - -Here are the basic settings: - -- `apiVersion`: Block API version -- `title`: Block title shown in inserter -- `name`: Unique name defines your block -- `category`: Category in inserter (text, media, design, widgets, theme, embed) -- `icon`: Dashicon icon displayed for block -- `editorScript`: JavaScript file to load for block - -The `block.json` file should be added to your plugin. To start a new plugin, create a directory in `/wp-content/plugins/` in your WordPress. - -Create a basic `block.json` file there: - - -```json -{ - "apiVersion": 3, - "title": "Example: Basic (ESNext)", - "name": "gutenberg-examples/example-01-basic-esnext", - "category": "layout", - "icon": "universal-access-alt", - "editorScript": "file:./build/index.js" -} -``` -### Step 2: Register block in plugin - -With the `block.json` in place, the registration for the block is a single function call in PHP, this will setup the block and JavaScript file specified in the `editorScript` property to load in the editor. - -Create a full plugin file, `index.php` like the following, the same PHP code works for both JSX and Plain code. - -```php - Hello world (from the editor)

; - }, - save: function () { - return

Hola mundo (from the frontend)

; - }, -} ); -``` - - -### Step 4: Build or add dependency - -In order to register the block, an asset php file is required in the same directory as the directory used in `register_block_type()` and must begin with the script's filename. - - - -Build the scripts and asset file which is used to keep track of dependencies and the build version. - -```bash -npm run build -``` - - -### Step 5: Confirm - -Open your editor and try adding your new block. It will show in the inserter using the `title`. -When inserted you will see the `Hello World (from the editor)` message. - -When you save the post and view it published, you will see the `Hola mundo (from the frontend)` message. - -**Troubleshooting** - If you run into any issues, here are a few things to try: - -- Check the filenames are correct and loading properly, -- Check the developer console in your browser for errors, -- If using JSX remember to build after each change - -## Conclusion - -This shows the most basic static block. The [block-development-examples](https://github.com/WordPress/block-development-examples) repository has complete examples for both. - -- [Basic Example with JSX build](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/basic-esnext-a2ab62) - -- [Basic Example Plain JavaScript](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/minimal-block-no-build-e621a6), - -**NOTE:** The examples include a more complete block setup with translation features included, it is recommended to follow those examples for a production block. The internationalization features were left out of this guide for simplicity and focusing on the very basics of a block. - -### Additional - -A couple of things to note when creating your blocks: - -- A block name must be prefixed with a namespace specific to your plugin. This helps prevent conflicts when more than one plugin registers a block with the same name. In this example, the namespace is `block-development-examples`. - -- Block names _must_ include only lowercase alphanumeric characters or dashes and start with a letter. Example: `my-plugin/my-custom-block`. - -### Resources - -- block.json [metadata reference](/docs/reference-guides/block-api/block-metadata.md) documentation - -- Block [edit and save function reference](/docs/reference-guides/block-api/block-edit-save.md) - -- [Dashicons icon set](https://developer.wordpress.org/resource/dashicons/) diff --git a/docs/how-to-guides/plugin-sidebar-0.md b/docs/how-to-guides/plugin-sidebar-0.md index 95bd26f7ee1f8..1c0abe86c30be 100644 --- a/docs/how-to-guides/plugin-sidebar-0.md +++ b/docs/how-to-guides/plugin-sidebar-0.md @@ -6,7 +6,7 @@ How to add a sidebar to your plugin. A sidebar is the region to the far right of ![Example sidebar](https://raw.githubusercontent.com/WordPress/gutenberg/HEAD/docs/assets/sidebar-up-and-running.png) -_Note: this tutorial covers a custom sidebar, if you are looking to add controls to the sidebar see the [Block Toolbar and Settings Sidebar](/docs/how-to-guides/block-tutorial/block-controls-toolbar-and-sidebar.md)_ +_Note: this tutorial covers a custom sidebar, if you are looking to add controls to the sidebar see the [Block Toolbar and Settings Sidebar](/docs/getting-started/fundamentals/block-in-the-editor.md)_ ## Before you start diff --git a/docs/manifest.json b/docs/manifest.json index e8c2e0d9d2b0f..e926281607f24 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -137,12 +137,6 @@ "markdown_source": "../docs/how-to-guides/block-tutorial/README.md", "parent": "how-to-guides" }, - { - "title": "Create a basic block", - "slug": "writing-your-first-block-type", - "markdown_source": "../docs/how-to-guides/block-tutorial/writing-your-first-block-type.md", - "parent": "block-tutorial" - }, { "title": "Use styles and stylesheets", "slug": "applying-styles-with-stylesheets", diff --git a/docs/toc.json b/docs/toc.json index 849de991c7808..94dea966cd3e0 100644 --- a/docs/toc.json +++ b/docs/toc.json @@ -59,9 +59,6 @@ { "docs/how-to-guides/accessibility.md": [] }, { "docs/how-to-guides/block-tutorial/README.md": [ - { - "docs/how-to-guides/block-tutorial/writing-your-first-block-type.md": [] - }, { "docs/how-to-guides/block-tutorial/applying-styles-with-stylesheets.md": [] }, diff --git a/packages/block-editor/src/components/block-controls/README.md b/packages/block-editor/src/components/block-controls/README.md index ee02e96e08b4d..58daea482ef39 100644 --- a/packages/block-editor/src/components/block-controls/README.md +++ b/packages/block-editor/src/components/block-controls/README.md @@ -49,7 +49,7 @@ export default function MyBlockEdit( { attributes, setAttributes } ) { ; ``` -See [this custom block tutorial page](/docs/how-to-guides/block-tutorial/block-controls-toolbar-and-sidebar.md) for more information and block controls examples. +See [this custom block tutorial page](/docs/getting-started/fundamentals/block-in-the-editor.md) for more information and block controls examples. Furthermore, the READMEs of various components inside the block editor package and the components package include examples that also utilize `BlockControls` and can be a good reference. @@ -69,7 +69,7 @@ Group of the block controls. Allows you to create and render multiple groups of Allows overriding the default `controls` if the `default` group is used. -See [this custom block tutorial page](/docs/how-to-guides/block-tutorial/block-controls-toolbar-and-sidebar.md) for more details and examples with block controls. +See [this custom block tutorial page](/docs/getting-started/fundamentals/block-in-the-editor.md) for more details and examples with block controls. - Type: `array` diff --git a/packages/components/src/toolbar/toolbar-button/README.md b/packages/components/src/toolbar/toolbar-button/README.md index 6bde73117b02c..99338e32c1b70 100644 --- a/packages/components/src/toolbar/toolbar-button/README.md +++ b/packages/components/src/toolbar/toolbar-button/README.md @@ -1,6 +1,6 @@ # ToolbarButton -ToolbarButton can be used to add actions to a toolbar, usually inside a [Toolbar](/packages/components/src/toolbar/README.md) or [ToolbarGroup](/packages/components/src/toolbar-group/README.md) when used to create general interfaces. If you're using it to add controls to your custom block, you should consider using [BlockControls](/docs/how-to-guides/block-tutorial/block-controls-toolbar-and-sidebar.md). +ToolbarButton can be used to add actions to a toolbar, usually inside a [Toolbar](/packages/components/src/toolbar/README.md) or [ToolbarGroup](/packages/components/src/toolbar-group/README.md) when used to create general interfaces. If you're using it to add controls to your custom block, you should consider using [BlockControls](/docs/getting-started/fundamentals/block-in-the-editor.md). It has similar features to the [Button](/packages/components/src/button/README.md) component. Using `ToolbarButton` will ensure the correct styling for a button in a toolbar, and also that keyboard interactions in a toolbar are consistent with the [WAI-ARIA toolbar pattern](https://www.w3.org/TR/wai-aria-practices/#toolbar). @@ -27,7 +27,7 @@ function MyToolbar() { ### Inside BlockControls -If you're working on a custom block and you want to add controls to the block toolbar, you should use [BlockControls](/docs/how-to-guides/block-tutorial/block-controls-toolbar-and-sidebar.md) instead. Optionally wrapping it with [ToolbarGroup](/packages/components/src/toolbar-group/README.md). +If you're working on a custom block and you want to add controls to the block toolbar, you should use [BlockControls](/docs/getting-started/fundamentals/block-in-the-editor.md) instead. Optionally wrapping it with [ToolbarGroup](/packages/components/src/toolbar-group/README.md). ```jsx import { BlockControls } from '@wordpress/block-editor'; diff --git a/packages/components/src/toolbar/toolbar-dropdown-menu/README.md b/packages/components/src/toolbar/toolbar-dropdown-menu/README.md index 866d98a89177f..4abcf3a9164e5 100644 --- a/packages/components/src/toolbar/toolbar-dropdown-menu/README.md +++ b/packages/components/src/toolbar/toolbar-dropdown-menu/README.md @@ -1,6 +1,6 @@ # ToolbarDropdownMenu -ToolbarDropdownMenu can be used to add actions to a toolbar, usually inside a [Toolbar](/packages/components/src/toolbar/README.md) or [ToolbarGroup](/packages/components/src/toolbar-group/README.md) when used to create general interfaces. If you're using it to add controls to your custom block, you should consider using [BlockControls](/docs/how-to-guides/block-tutorial/block-controls-toolbar-and-sidebar.md). +ToolbarDropdownMenu can be used to add actions to a toolbar, usually inside a [Toolbar](/packages/components/src/toolbar/README.md) or [ToolbarGroup](/packages/components/src/toolbar-group/README.md) when used to create general interfaces. If you're using it to add controls to your custom block, you should consider using [BlockControls](/docs/getting-started/fundamentals/block-in-the-editor.md). It has similar features to the [DropdownMenu](/packages/components/src/dropdown-menu/README.md) component. Using `ToolbarDropdownMenu` will ensure that keyboard interactions in a toolbar are consistent with the [WAI-ARIA toolbar pattern](https://www.w3.org/TR/wai-aria-practices/#toolbar). @@ -54,7 +54,7 @@ function MyToolbar() { ### Inside BlockControls -If you're working on a custom block and you want to add controls to the block toolbar, you should use [BlockControls](/docs/how-to-guides/block-tutorial/block-controls-toolbar-and-sidebar.md) instead. +If you're working on a custom block and you want to add controls to the block toolbar, you should use [BlockControls](/docs/getting-started/fundamentals/block-in-the-editor.md) instead. ```jsx import { BlockControls } from '@wordpress/block-editor'; diff --git a/packages/components/src/toolbar/toolbar-item/README.md b/packages/components/src/toolbar/toolbar-item/README.md index 31a0dfa1cf473..e219d085a2cba 100644 --- a/packages/components/src/toolbar/toolbar-item/README.md +++ b/packages/components/src/toolbar/toolbar-item/README.md @@ -1,6 +1,6 @@ # ToolbarItem -A ToolbarItem is a generic headless component that can be used to make any custom component a [Toolbar](/packages/components/src/toolbar/README.md) item. It should be inside a [Toolbar](/packages/components/src/toolbar/README.md) or [ToolbarGroup](/packages/components/src/toolbar-group/README.md) when used to create general interfaces. If you're using it to add controls to your custom block, you should consider using [BlockControls](/docs/how-to-guides/block-tutorial/block-controls-toolbar-and-sidebar.md). +A ToolbarItem is a generic headless component that can be used to make any custom component a [Toolbar](/packages/components/src/toolbar/README.md) item. It should be inside a [Toolbar](/packages/components/src/toolbar/README.md) or [ToolbarGroup](/packages/components/src/toolbar-group/README.md) when used to create general interfaces. If you're using it to add controls to your custom block, you should consider using [BlockControls](/docs/getting-started/fundamentals/block-in-the-editor.md). ## Usage @@ -49,7 +49,7 @@ function MyToolbar() { ### Inside BlockControls -If you're working on a custom block and you want to add controls to the block toolbar, you should use [BlockControls](/docs/how-to-guides/block-tutorial/block-controls-toolbar-and-sidebar.md) instead. Optionally wrapping it with [ToolbarGroup](/packages/components/src/toolbar-group/README.md). +If you're working on a custom block and you want to add controls to the block toolbar, you should use [BlockControls](/docs/getting-started/fundamentals/block-in-the-editor.md) instead. Optionally wrapping it with [ToolbarGroup](/packages/components/src/toolbar-group/README.md). ```jsx import { BlockControls } from '@wordpress/block-editor';