From 6525e59c09ebfb09827a775a7c6e8c5a0d2ddbf6 Mon Sep 17 00:00:00 2001 From: Preston Davies Date: Tue, 23 May 2023 12:01:13 -0400 Subject: [PATCH 1/5] ToolsPanel and ToolsPanelItem Examples --- guides/tools-panel.md | 209 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 209 insertions(+) create mode 100644 guides/tools-panel.md diff --git a/guides/tools-panel.md b/guides/tools-panel.md new file mode 100644 index 0000000..6718bce --- /dev/null +++ b/guides/tools-panel.md @@ -0,0 +1,209 @@ +# ToolsPanel and ToolsPanelItem + +## Reference Guide WordPress Documentation: +* [ToolsPanel](https://developer.wordpress.org/block-editor/reference-guides/components/tools-panel/) +* [ToolsPanelItem](https://developer.wordpress.org/block-editor/reference-guides/components/tools-panel-item/) + +Both of these are **experimental**. + +## Use Case: +If you have controls that should exist within block support panels in the WP Admin block settings and you would like a fine grained ability on when to enable or have the user enable a specific control. This functionality also provides the benefit of resetting a control to a default state which can be helpful for users who may want to experiment with certain controls but have the ability to disable them independently. + +### Caveats: +* When enabling the controls they must be tied to a block support panel group ie: `border`, `color`, `dimensions`, `typography` or `styles`. +* It is best to use a `ToolsPanel` if there will be multiple `ToolsPanelItem`'s within a specific block support panel group. `ToolsPanelItem` is preferred if there is just a singluar `ToolsPanelItem` within a group. +* `ToolsPanel` provides a `resetAll` function that can take each `ToolsPanelItem`'s singular `resetAllFilter` by passing an array of +these functions through to the panel’s `resetAll` callback to iterate over to reset all data within that panel simultaneously. + +## Code Example: +The example below showcases three usages within an `edit.js` file within a custom block: +1. Using a `ToolsPanelItem` to create a singular control that adjusts the alignment of a block within the typography group +2. Using a `ToolsPanel` for multiple `ToolsPanelItem`'s in this situation there are multiple controls within the styles group that would be used together to create an animation +3. Using a `ToolsPanelItem` to create a singular control that adjusts the width of the block inside the dimensions group it also has the `isShownByDefault` which means it will always be displayed inside the block settings and does not need to be clicked on to enable and display. + +```bash +import { __ } from '@wordpress/i18n'; +import { useBlockProps, InspectorControls, useSetting, RichText } from '@wordpress/block-editor'; +import { + SelectControl, + __experimentalToggleGroupControl as ToggleGroupControl, + __experimentalToggleGroupControlOption as ToggleGroupControlOption, + __experimentalToolsPanel as ToolsPanel, + __experimentalToolsPanelItem as ToolsPanelItem, + __experimentalUnitControl as UnitControl, +} from '@wordpress/components'; + +const ExampleBlockEdit = (props) => { + const { attributes, setAttributes, clientId } = props; + const { title, width, animationName, animationDuration, animationEasing, alignment } = + attributes; + + const blockProps = useBlockProps({ + style: { + width, + textAlign: alignment, + animationName, + animationDuration, + animationTimingFunction: animationEasing, + }, + }); + + const units = useSetting('spacing.units'); + + const resetAll = () => { + setAttributes({ + animationName: '', + animationDuration: '', + animationEasing: '', + }); + }; + + return ( + <> + + !!alignment} + label={__('Alignment')} + onDeselect={() => setAttributes({ alignment: undefined })} + resetAllFilter={() => ({ + alignment: undefined, + })} + onSelect={() => setAttributes({ alignment: 'left' })} + panelId={clientId} + > + setAttributes({ alignment: value })} + > + + + + + + + + !!animationName} + label={__('Name')} + onDeselect={() => setAttributes({ animationName: undefined })} + onSelect={() => setAttributes({ animationName: 'fade-in' })} + > + setAttributes({ animationName: value })} + options={[ + { + label: __('Fade In'), + value: 'fade-in', + }, + { + label: __('Slide In Down'), + value: 'slide-in-down-fade', + }, + { + label: __('Slide In Up'), + value: 'slide-in-up-fade', + }, + { + label: __('Slide In Left'), + value: 'slide-in-left-fade', + }, + { + label: __('Slide In Right'), + value: 'slide-in-right-fade', + }, + ]} + /> + + !!animationDuration} + label={__('Duration')} + onDeselect={() => setAttributes({ animationDuration: undefined })} + onSelect={() => setAttributes({ animationDuration: '300' })} + > + setAttributes({ animationDuration: value })} + options={[ + { label: __('150ms'), value: '150' }, + { label: __('200ms'), value: '200' }, + { label: __('250ms'), value: '250' }, + { label: __('300ms'), value: '300' }, + { label: __('350ms'), value: '350' }, + { label: __('400ms'), value: '400' }, + { label: __('450ms'), value: '450' }, + { label: __('500ms'), value: '500' }, + ]} + /> + + !!animationEasing} + label={__('Easing')} + onDeselect={() => setAttributes({ animationEasing: undefined })} + onSelect={() => setAttributes({ animationEasing: 'ease' })} + > + setAttributes({ animationEasing: value })} + options={[ + { label: __('Ease'), value: 'ease' }, + { + label: __('Ease In'), + value: 'ease-in', + }, + { + label: __('Ease Out'), + value: 'ease-out', + }, + { + label: __('Ease In Out'), + value: 'ease-in-out', + }, + { + label: __('Linear'), + value: 'linear', + }, + ]} + /> + + + + + !!width} + label={__('Width')} + onDeselect={() => setAttributes({ width: undefined })} + resetAllFilter={() => ({ + width: undefined, + })} + isShownByDefault + panelId={clientId} + > + setAttributes({ width: value })} + units={units} + /> + + +
+ setAttributes({ title })} + /> +
+ + ); +}; +export default ExampleBlockEdit; +``` From 93db8635f702e64741fe7c487392d0522eb744ad Mon Sep 17 00:00:00 2001 From: Preston Davies Date: Tue, 23 May 2023 12:15:22 -0400 Subject: [PATCH 2/5] Update verbiage --- guides/tools-panel.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/guides/tools-panel.md b/guides/tools-panel.md index 6718bce..4a66f69 100644 --- a/guides/tools-panel.md +++ b/guides/tools-panel.md @@ -7,7 +7,7 @@ Both of these are **experimental**. ## Use Case: -If you have controls that should exist within block support panels in the WP Admin block settings and you would like a fine grained ability on when to enable or have the user enable a specific control. This functionality also provides the benefit of resetting a control to a default state which can be helpful for users who may want to experiment with certain controls but have the ability to disable them independently. +If you have custom controls that should exist within or be added to an existing block support panels group in the WP Admin block settings and you would like a fine grained ability on when to enable or have the user enable a specific control. This functionality also provides the benefit of resetting a control to a default state. ### Caveats: * When enabling the controls they must be tied to a block support panel group ie: `border`, `color`, `dimensions`, `typography` or `styles`. @@ -17,9 +17,9 @@ these functions through to the panel’s `resetAll` callback to iterate over to ## Code Example: The example below showcases three usages within an `edit.js` file within a custom block: -1. Using a `ToolsPanelItem` to create a singular control that adjusts the alignment of a block within the typography group -2. Using a `ToolsPanel` for multiple `ToolsPanelItem`'s in this situation there are multiple controls within the styles group that would be used together to create an animation -3. Using a `ToolsPanelItem` to create a singular control that adjusts the width of the block inside the dimensions group it also has the `isShownByDefault` which means it will always be displayed inside the block settings and does not need to be clicked on to enable and display. +1. Using a `ToolsPanelItem` to create a singular control that adjusts the alignment of a block within the `typography` group +2. Using a `ToolsPanel` for multiple `ToolsPanelItem`'s in this situation there are multiple controls within the `styles` group that would be used together to create an animation +3. Using a `ToolsPanelItem` to create a singular control that adjusts the width of the block inside the `dimensions` group it also has the `isShownByDefault` which means it will always be displayed inside the block settings and does not need to be clicked on to enable and display. ```bash import { __ } from '@wordpress/i18n'; From 55a0777b46aa0642cb6c6c13e455a58f812e1a90 Mon Sep 17 00:00:00 2001 From: Preston Davies Date: Wed, 24 May 2023 16:20:28 -0400 Subject: [PATCH 3/5] Preface and new panel information --- guides/tools-panel.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/guides/tools-panel.md b/guides/tools-panel.md index 4a66f69..8d57639 100644 --- a/guides/tools-panel.md +++ b/guides/tools-panel.md @@ -1,5 +1,8 @@ # ToolsPanel and ToolsPanelItem +## Preface: +WordPress recently adopted a new UI approach for grouping related settings in the Inspector Controls sidebar. Instead of grouping the settings in PanelBody components which create an accordion based user experience, the new ToolPanel approach allows users to toggle individual settings from a semantic group. This reduces the number of unused controls shown to the user when they open a block sidebar. This approach also makes it much easier for block extenders (developers) to add additional settings into these semantic panels. For example: a block has a custom typography setting which isn't already in core such as, writing mode, you can create a block extension and add your own custom setting into the typography panel of a block. + ## Reference Guide WordPress Documentation: * [ToolsPanel](https://developer.wordpress.org/block-editor/reference-guides/components/tools-panel/) * [ToolsPanelItem](https://developer.wordpress.org/block-editor/reference-guides/components/tools-panel-item/) @@ -7,7 +10,7 @@ Both of these are **experimental**. ## Use Case: -If you have custom controls that should exist within or be added to an existing block support panels group in the WP Admin block settings and you would like a fine grained ability on when to enable or have the user enable a specific control. This functionality also provides the benefit of resetting a control to a default state. +If you have custom controls that should exist within or be added to an existing block support panels group in the WP Admin block settings and you would like a fine grained ability on when to enable or have the user enable a specific control. This functionality also provides the benefit of resetting a control to a default state. Additionally new panels can be created using `ToolsPanel` as shown in the example below where a new `Animation` panel would be created. ### Caveats: * When enabling the controls they must be tied to a block support panel group ie: `border`, `color`, `dimensions`, `typography` or `styles`. From 0443df24a08f2147630704efc442ce97c8572301 Mon Sep 17 00:00:00 2001 From: Preston Davies Date: Thu, 25 May 2023 11:58:55 -0400 Subject: [PATCH 4/5] Update guides/tools-panel.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fabian Kägy --- guides/tools-panel.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/tools-panel.md b/guides/tools-panel.md index 8d57639..5afc2fb 100644 --- a/guides/tools-panel.md +++ b/guides/tools-panel.md @@ -24,7 +24,7 @@ The example below showcases three usages within an `edit.js` file within a custo 2. Using a `ToolsPanel` for multiple `ToolsPanelItem`'s in this situation there are multiple controls within the `styles` group that would be used together to create an animation 3. Using a `ToolsPanelItem` to create a singular control that adjusts the width of the block inside the `dimensions` group it also has the `isShownByDefault` which means it will always be displayed inside the block settings and does not need to be clicked on to enable and display. -```bash +```js import { __ } from '@wordpress/i18n'; import { useBlockProps, InspectorControls, useSetting, RichText } from '@wordpress/block-editor'; import { From ca54df60eddd36d83b849ffddc76e5422404da79 Mon Sep 17 00:00:00 2001 From: Preston Davies Date: Thu, 25 May 2023 12:05:22 -0400 Subject: [PATCH 5/5] Update caveats --- guides/tools-panel.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/guides/tools-panel.md b/guides/tools-panel.md index 8d57639..de8afbc 100644 --- a/guides/tools-panel.md +++ b/guides/tools-panel.md @@ -10,11 +10,10 @@ WordPress recently adopted a new UI approach for grouping related settings in th Both of these are **experimental**. ## Use Case: -If you have custom controls that should exist within or be added to an existing block support panels group in the WP Admin block settings and you would like a fine grained ability on when to enable or have the user enable a specific control. This functionality also provides the benefit of resetting a control to a default state. Additionally new panels can be created using `ToolsPanel` as shown in the example below where a new `Animation` panel would be created. +If you have custom controls that should exist within or be added to an existing block support panels group (ie: `border`, `color`, `dimensions`, `typography` or `styles`) in the WP Admin block settings and you would like a fine grained ability on when to enable or have the user enable a specific control. This functionality also provides the benefit of resetting a control to a default state. Additionally new panels can be created using `ToolsPanel` as shown in the example below where a new `Animation` panel would be created. ### Caveats: -* When enabling the controls they must be tied to a block support panel group ie: `border`, `color`, `dimensions`, `typography` or `styles`. -* It is best to use a `ToolsPanel` if there will be multiple `ToolsPanelItem`'s within a specific block support panel group. `ToolsPanelItem` is preferred if there is just a singluar `ToolsPanelItem` within a group. +* The `ToolsPanel` component can be used to create entirely new panels that can house `ToolsPanelItem`'s, or extensions can be made to an existing `ToolsPanel`'s by adding individual `ToolsPanelItem`'s to it. * `ToolsPanel` provides a `resetAll` function that can take each `ToolsPanelItem`'s singular `resetAllFilter` by passing an array of these functions through to the panel’s `resetAll` callback to iterate over to reset all data within that panel simultaneously.