From 69a82aca49548d212d57fd80e3a67de60d0f58e9 Mon Sep 17 00:00:00 2001 From: Nick Diego Date: Mon, 5 Feb 2024 17:32:33 -0600 Subject: [PATCH] Docs: Copy and formatting edits for the "The block in the Editor" guide (#58697) * Initial edits. * Additional edits. * Add image description. Co-authored-by: ndiego Co-authored-by: justintadlock --- .../fundamentals/block-in-the-editor.md | 48 +++++++++---------- 1 file changed, 23 insertions(+), 25 deletions(-) diff --git a/docs/getting-started/fundamentals/block-in-the-editor.md b/docs/getting-started/fundamentals/block-in-the-editor.md index 2089d8aba2f0ec..85a6dfe506db3e 100644 --- a/docs/getting-started/fundamentals/block-in-the-editor.md +++ b/docs/getting-started/fundamentals/block-in-the-editor.md @@ -1,17 +1,17 @@ # The block in the Editor -The Block Editor is a React Single Page Application (SPA) and every block in the editor is displayed through a React component defined in the `edit` property of the settings object used to [register the block on the client](https://developer.wordpress.org/block-editor/getting-started/fundamentals/registration-of-a-block/#registration-of-the-block-with-javascript-client-side). +The Block Editor is a React Single Page Application (SPA). Every block in the Editor is displayed through a React component defined in the `edit` property of the settings object used to [register the block](https://developer.wordpress.org/block-editor/getting-started/fundamentals/registration-of-a-block/#registration-of-the-block-with-javascript-client-side) on the client. The `props` object received by the block's `Edit` React component includes: -- [`attributes`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#attributes) - attributes object -- [`setAttributes`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#setattributes) - method to update the attributes object -- [`isSelected`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#isselected) - boolean that communicates whether the block is currently selected +- **[`attributes`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#attributes):** An object of all the block's attributes. +- **[`setAttributes`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#setattributes):** A method to update the attributes object. +- **[`isSelected`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#isselected):** A boolean value that communicates whether the block is currently selected -WordPress provides many built-in standard components that can be used to define the interface of the block in the editor. These built-in components are available via packages such as [`@wordpress/components`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-components/) and [`@wordpress/block-editor`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor/). +WordPress provides many built-in standard components that can be used to define the block interface in the Editor. These built-in components are available via packages such as [`@wordpress/components`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-components/) and [`@wordpress/block-editor`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor/).
-The WordPress Gutenberg project uses Storybook to document the user interface components that are available in WordPress packages. + The WordPress Gutenberg project uses Storybook to document the user interface components that are available in WordPress packages.
Custom settings controls for the block in the Block Toolbar or the Settings Sidebar can also be defined through this `Edit` React component via built-in components such as: @@ -28,34 +28,35 @@ The package [`@wordpress/components`](https://developer.wordpress.org/block-edit - [`ToggleControl`](https://wordpress.github.io/gutenberg/?path=/docs/components-togglecontrol--docs) - [`ExternalLink`](https://wordpress.github.io/gutenberg/?path=/docs/components-externallink--docs) -The package [`@wordpress/block-editor`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor/) includes a library of components and hooks for the Block Editor, including those to define custom settings controls for the block in the Editor. Some of the components most commonly used from this package are: +The package [`@wordpress/block-editor`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor/) includes a library of components and hooks for the Block Editor, including those to define custom settings controls for the block. Some of the components most commonly used from this package are: - [`RichText`](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/rich-text/README.md) - [`BlockControls`](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-editor/src/components/block-controls) - [`InspectorControls`](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/inspector-controls/README.md) - [`InnerBlocks`](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/inner-blocks/README.md) -- `PanelColorSettings` or `ColorPalette` -
-The package @wordpress/block-editor also provide the tools to create and use standalone block editors. +
+ The package @wordpress/block-editor also provides the tools to create and use standalone block editors.
A good workflow when using a component for the Block Editor is: -- Import the component from a WordPress package -- Add the corresponding code for the component to your project in JSX format -- Most built-in components will be used to set [block attributes](https://developer.wordpress.org/block-editor/getting-started/fundamentals/block-json/#using-attributes-to-store-block-data), so define any necessary attributes in `block.json` and create event handlers to update those attributes with `setAttributes` in your component -- If needed, adapt the code to be serialized and stored in the database +- Import the component from a WordPress package. +- Add the corresponding code for the component to your project in JSX format. +- Most built-in components will be used to set [block attributes](https://developer.wordpress.org/block-editor/getting-started/fundamentals/block-json/#using-attributes-to-store-block-data), so define any necessary attributes in `block.json` and create event handlers to update those attributes with `setAttributes` in your component. +- Adapt the code to be serialized and stored in the database if needed. ## 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. +To simplify block customization and ensure a consistent user experience, there are several built-in UI patterns to help generate the Editor preview of a block. + +The image below details the Block Toolbar and the Settings Sidebar of a selected Paragraph block. ![Diagram showing the Block Toolbar and the Settings Sidebar when a Paragraph block is selected](https://developer.wordpress.org/files/2023/12/block-toolbar-settings-sidebar.png) ### Block Toolbar -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 may be included automatically but 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. +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 may be included automatically, but 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 export default function Edit( { className, attributes: attr, setAttributes } ) { @@ -95,18 +96,15 @@ export default function Edit( { className, attributes: attr, setAttributes } ) { _See the [full block example](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/block-toolbar-ab967f) of the [code above](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/block-toolbar-ab967f/src/edit.js)._ - 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 -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**. +The Settings Sidebar is used to display less-often-used settings or those that require more screen space. The Settings Sidebar should be used for **block-level settings only** and is shown when a block is selected. -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. +If a setting only affects selected content inside a block, such as "bolding" text, **do not place the setting inside the Settings Sidebar**. Use a toolbar instead. 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. +Similar to rendering a toolbar, if you include an `InspectorControls` component in the `return` value of your block type's `Edit` function, those controls will be shown in the Settings Sidebar region. ```jsx export default function Edit( { attributes, setAttributes } ) { @@ -154,10 +152,10 @@ export default function Edit( { attributes, setAttributes } ) { ``` _See the [full block example](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/settings-sidebar-82c525) of the [code above](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/settings-sidebar-82c525/src/edit.js)._ -Block controls rendered in both the toolbar and sidebar will also be used when multiple blocks of the same type are selected. +Block controls rendered in both the toolbar and sidebar will also be available when multiple blocks of the same type are selected.
-For common customization settings including color, border, spacing customization and more, you can rely on block supports to provide the same functionality in a more efficient way. + For common customization settings, including color, border, spacing, and more, you can rely on block supports instead of a custom solution. Block supports provide a consistent UI with the same functionality as other Core blocks.
## Additional resources @@ -165,5 +163,5 @@ For common customization settings including color, border, spacing customization - [Storybook for WordPress components](https://wordpress.github.io/gutenberg/?path=/docs/docs-introduction--page) - [@wordpress/block-editor](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor/) - [@wordpress/components](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-components/) -- [`Inspector Controls`](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/inspector-controls/README.md) +- [`InspectorControls`](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/inspector-controls/README.md) - [`BlockControls`](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-editor/src/components/block-controls) \ No newline at end of file