bobbingwide/sb-toolicons-block

Helps you to document tool icons for a block.

SB Toolicons block

• Contributors: bobbingwide
• Tags: block, toolicons, toolbar, icons
• Requires at least: 5.5.1
• Tested up to: 5.7-beta3
• Stable tag: 0.3.0
• Requires PHP: 7.2.0
• License: GPL-2.0-or-later
• License URI: https://www.gnu.org/licenses/gpl-2.0.html

Helps you to document tool icons for a block.

Description

Use the Toolicons block ( oik-sb/toolicons ) to produce a list of toolicons for the block you're documenting.

Installation

1. Upload the plugin files to the /wp-content/plugins/sb-toolicons-block directory, or install the plugin through the WordPress plugins screen directly.
2. Activate the plugin through the 'Plugins' screen in WordPress

OR ( not yet available as the plugin is not in the Block Directory )

With WordPress 5.5 or Gutenberg 9.0.0 or higher, and the authority to install plugins:

1. In the block editor, open the block inserter.
2. Search for the block by typing 'toolicons'.
3. Click on the 'Add block' button for the SB Toolicons block.
4. The SB Toolicons block plugin will be installed and activated.
5. And the block will be inserted into your content.

Frequently Asked Questions

Do I need to build this block?

No. The plugin is delivered with the production version of the block. If you do wish to modify the code then you can find instructions in the src folder.

Screenshots

1. Block toolbar variation showing core/column
2. Group toolbar variation showing Change text alignment
3. Tool icon variation showing all icons

Upgrade Notice

0.3.0

Now supports FSE blocks, up to Gutenberg 10.0.2

0.2.0

Now supports most of the core blocks ( 42 ) excluding those used in Full Site Editing.

0.1.0

First version that displays toolbars and their icons on the front-end for 8 of 131 core blocks.

0.0.0

Initial version copied from sb-children-block, which uses wp-scripts and oik-blocks where the use of import { iconname } from '@wordpress/icons'; broke the Image block in Gutenberg 9.0.0

Changelog

0.3.0

• Added: FSE blocks
• Changed: Update packages - for new icons
• Changed: Add logic for Show icon only toggle,#9
• Changed: Added some support for documenting the editor post header toolbar areas,#11
• Changed: Copy selectIcon,#4
• Tested: With Gutenberg 10.0.2
• Tested: With WordPress 5.7-beta3 and WordPress Multi Site
• Tested: With WordPress 5.6.2 and WordPress Multi Site
• Tested: With PHP 8.0
• Built: With node v12.8.4 and npm 6.4.11

0.2.0

• Added: Add Show all icons toggle for Tool icon variation,#9
• Added: Add 3 variations,#7
• Added: Add more core blocks,#1
• Added: Add display of Tranforms with optional link to the target block documentation,#8
• Changed: Update the cropGroup horizontal toolbar for core/image when Crop has been chosen,#6
• Changed: Cater for icons which are not in the @wordpress/icons library,#4
• Added: Add Show transforms option,#3
• Tested: With Gutenberg 9.1.1
• Tested: With WordPress 5.5.1
• Tested: With PHP 7.4

0.1.0

• Changed: Choose from 8 block types, #1
• Changed: Option to Show More Options
• Changed: First attempt at internationalization and localization
• Changed: Supports various toolgroups
• Tested: With Gutenberg 9.0.0
• Tested: With WordPress 5.5.1
• Tested: With PHP 7.4

0.0.0

• Added: Copied from sb-children-block
• Changed: Update from the toolicons block in oik-blocks
• Tested: With Gutenberg 9.0.0 ( built from source using node 12) and the delivered package.
• Tested: With WordPress 5.5.1

sb-toolicons-block's Issues

Options for the Tool icon variation

When the Toolicons variation is Tool icon there should be a number of different possible display formats,
controlled by toggles.

• Show Icon/text
• Show Label
• Show Description
• Show Accelerator keys
  • For Windows
  • For Apple

Internationalization and customization for toolicon.description fields

Consider implementing the description field as a textarea which can be customised by the author/editor when implementing the block.

For each tool icon the givens are:

• the tool icon image or text: icon or `text
• the tool tip: label
• the position in the toolbar

For the documentation, the description is something I've created from the existing documentation on wordpress.org, making it generic for each tool icon.
Given that the toolicon block is saved as static text, it makes sense to allow the author to customize the default description provided by the plugin. This will allow the author/editor to add styling that's missing from raw text or simply to improve the text.

Optionally the updated text could be saved in wp_options, so that it could be used consistently for the documentation for each blocks that uses the tool icon.

BTW. At present I don't have much idea how to do this.

Internationalization - ensure strings are translatable - both the Help text and the block's own strings

When I started developing the Toolbar icons block I assumed it would be possible to piggy back on string translations for strings that exacltly match those in core. These are the strings provided for textual buttons and tool tips.

It seems that, either I dont know how to use the wp-scripts commands to do this, or it's not actually possible to do what I want to do.

The pragmatic approach is to set the text domain for each string to sb-toolicons-block and use the tools the way I did for the sb-children-block plugin.

e.g.

const moreOptions =
	{
		icon: moreVertical,
		label: __( 'More options','sb-toolicons-block'),
		description: __( 'Display more options','sb-toolicons-block'),
		tools: [ toolicon.blockSettings, toolicon.copy, toolicon.duplicate, toolicon.insertAfter, toolicon.insertBefore,
			toolicon.moveTo, toolicon.editAsHTML, toolicon.group, toolicon.addToReusable, toolicon.removeBlock ],
		key: 'moreOptions'
	};

As you can see from the screen capture. I have successfully automatically translated the strings to the bbboing language.
Two errors detected.

1. It didn't translate the "Show More Options" string in the block's sidebar.
   Explanation: this string wasn't wrapped in __().
2. The original string should have been Show 'More options' menu items

Cater for icons which are not in the @wordpress/icons library

There are a number of tool icons which are not in the @wordpress/icons package.
These are summarised below.
As a workaround, for some of them, I have copied the Gutenberg source.

Icon	First encountered	Original source / Notes
h1-h6	core/heading	packages/block-library/src/heading/heading-level-icon.js
image	core/paragraph	<InlineImageIcon> from packages/components/src/toolbar/stories/index.js
changeContentPosition	core/cover	not resolved - tried to use <AlignmentMatrixControl.Icon value='center' />
vertical align icons	core/columns	packages/block-editor/src/components/block-vertical-alignment-toolbar/icons.js
navigation icons	core/navigation-link	packages/block-library/src/navigation-link/icons.js
colors selector	core/navigation	packages/block-library/src/navigation/block-colors-selector.js
block navigator	core/navigation	packages/block-library/src/navigation/use-block-navigator.js
search icons	core/search	packages/block-library/src/search/icons.js
outline (MenuIcon)	top toolbar	packages/block-editor/src/components/block-navigation/dropdown.js
select	top toolbar	packages/block-editor/src/components/tool-selector/index.js

The First encountered column is where I first noted the problem... It may have been while creating a toolgroup for a block / set of blocks.

Create a block to display Toolbar icons on the WordPress front end

In the oik-blocks plugin, for [blocks.wp-a2z.org], and other sites where I document WordPress blocks for the block editor ( called Gutenberg ), I have three blocks which display information about blocks and their icons.
These find the icons for each requested block and save the Icon as part of the static content.

In the official documentation for WordPress blocks the documentation for each block discusses the Toolbar icons. The icons are displayed from screen captures of each block.
Everytime a block's toolbar icons are changed the documentation becomes out of date.

With this block I intend to experiment with the ability to document the toolbar icons with programmatic support.

Potential benefits

• Reduced effort to maintain screen captures for each block.
• Accessibility improvements
• Opportunity to develop documentation under version control.
• Potential support for automatic localization

Requirements

• Ability to display on the front end the toolbar for a selected block
• showing the tools and actions supported by the block
• with options to display differing levels of detail, such as:
  • show all the options in the More options toolbar icon dropdown menu
  • show toolbar only
  • show alternatives for icons e.g. Show Block Settings & Hide Block Settings
• Internationalized
• Localized for UK English ( en_UK ) and the bbboing test language ( locale bb_BB )

Proposed solution

• develop a single block plugin called SB-Toolicons-block
• which delivers a block called Toolbar icons oik-sb/toolicons
• supports the toolbars for all the core blocks
• supports the toolbars for core block variations
• supports the common toolbar groups: heading, text align, block align, more rich text options, more options
• which uses an internal block called Toolbar icon
• which allows the user to choose any of the toolbar icons available in WordPress core

The Toolbar icon block:

• will display the icon ( in a variety of sizes if necessary)
• The toolbar's tooltip
• Some brief help that further explains the tooltip indicating what should happen.

e.g For the toolbar icon for aligning text left ( alignLeft ) it will show:

• the icon
• Align text left
• Use the Align text left drop-down from the toolbar, to align text to the left.

where I've invented the brief help based on current documentation for the paragraph block.

Inconsistent styling of the toolbar icons on the front end

When viewed in the front end on oik-plugins.com ( with theme genesis-oik ) the toolbar icons appear larger than on blocks.wp-a2z.org ( with theme genesis-a2z ). They should both appear as close as possible to what we see in the editor.
In this screenshot the toolbar icons on the LHS are too large and there is too much bottom padding.

Support block variations

As an extension to #1, I want to be able to create 3 different display types, each with their own options.
I'm hoping this can be done using block variations of the oik-sb/toolicons block.

data	Block toolbar	Group toolbar	Tool icon
name	blocktype	toolgroup	toolicon
icon	block-default	group?	icon?
Show toolbar toggle	Yes	Yes	No
Show drop down menus toggle	Yes	Yes	No
Show More options menu items toggle	Yes	No	No
Show Transforms toggle	Yes	No	No
Show Links toggle	Yes - see #8	No	No
Tool icon options	No	No	Yes - see #9

For Show Links the idea is to produce a link to the target block.

Toolicon block crashes in WordPress 5.9-RC2

The following block produced "This block encountered an error and cannot be previewed."
It occurred in core.wp-a2z with WordPress 5.9-RC2, no Gutenberg.

<!-- wp:oik-sb/toolicons {"blocktype":"core/navigation-link"} /-->

Console message
Uncaught TypeError: Cannot read properties of undefined (reading 'title')
at TransformItem (index.js:10030:72)
at index.js:10012:12
at Array.map ()
at Transforms (index.js:10011:32)
at toolIconStyled (index.js:8778:84)
at edit (index.js:7747:83)
at renderWithHooks (react-dom.js:15015:20)
at updateFunctionComponent (react-dom.js:17386:22)
at beginWork (react-dom.js:19093:18)
at HTMLUnknownElement.callCallback (react-dom.js:3942:16)

Alert for "Unrecognised block" getting in the way

I wanted to copy a paragraph from the documentation for core/post-hierarchical-terms but was thwarted by the alert message saying Unrecognised block. It appears far too many times. It was only a debug message so the code can be deleted.

Register block using `apiVersion: 2`

The Toolicons block and variations is registered using v1 of the registerBlockType API.
It needs to be:

• registered using apiVersion: 2
• internationalized,
• translated
• and localized.

Requirements

• Register the block using block.json
• Ensure the block can be selected
• Add some color and typography settings if applicable
• Add text align capability where applicable
• Internationalized and localized

Proposed solution

• Update package.json
• Change block.json for each block
• Change index.js to register the block from the server registration
• Change the server to register the block from block.json
• Update node_modules and rebuild
• (re) Internationalize and (re) localize
• remove webpack.config.js - it's no longer necessary

The scope is the source code of the plugin.

Process for updating node_modules

1. Remove the existing node_modules folder
2. npm install
3. npm install @wordpress/scripts --save-dev

See https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/

Add Show Links option to show links to block transformations

For Show Transforms, if Show Links is selected the idea is to produce a link to the target block's documentation.

In blocks.wp-a2z the format of the link is a hyphen separated concatenation of the US English block title with the full block name, prefixed by block/

See oik-blocks for logic that does something like this.

e.g. For the Spacer block it's block/spacer-core-spacer

In WordPress.org it's the hyphen separated block title, appended by block or embed, and prefixed by support/article/ .

e.g. For the Spacer block it's support/article/spacer-block.

For Twitter embed it's support/article/twitter-embed

Add support for documenting the editor post header toolbar areas

At the top of the editor is the Editor top bar ( aria-label ) which contains the Edit post header (edit-post-header ).
This consists of two areas:

• Edit post header toolbar ( edit-post-header__toolbar )
• Edit post header settings ( edit-post-header__settings )

The Edit post header toolbar contains a div with aria-label Document tools
The Edit post header settings div doesn't contain an aria-labelled div.

Prototype screenshot - unstyled

Requirement

• Create toolbar groups for both of these toolbars
• Create toolbar groups for each of the dropdown menus in these toolbars
• Consider how to document the items in the interface-pinned-items, which incudes the Settings icon
• The Settings icon is not pinnable
• The icons for Plugins such as Jetpack, Yoast SEO and Genesis are pinnable - any may move about in the interface-pinned-items area.

Proposed solution

• Implement two toolbar groups: "Document tools" headerToolbarLeft, and (for want of a better label) "Edit post settings" headerSettings
• Implement drop down groups

Note: The class names seem to change between Gutenberg versions. I'll try to use the latest.

Cater for blocks where the primary toolbar changes when an icon is selected

The toolbar for core/image changes when you select the crop tool icon.
We need to be able to document the initial view and the view when image cropping is being performed.

Attempted workaround

I tried a quick hack with the block name being core/image-crop but that broke the logic displaying the first part of the toolbar and the transforms. The block name was invalid

Proposed solution

Display block transformations on the front end

The toolbar displayed for each block includes a Transform to menu displayed from the block's icon.

Even if a block cannot be transformed to another block type it can be transformed to a Group.
Unless it's already been Grouped, in which case it can be Ungrouped.

Note: The pull down menu also supports the selection of Styles.

Requirements

• Ability to see the transformations for each block
• Optionally link to the documentation for the target block
• Either incorporate into the oik-sb/toolicons block or create it as a separate block type