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

[bobbingwide]

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

• [x] develop a single block plugin called SB-Toolicons-block
• [x] 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.

[bobbingwide]

I started developing the block in the oik-blocks plugin as oik-block/toolicons.

I soon encountered a major problem trying to use the oik-block/toolicons block to display icons imported from @wordpress.icons. When I attempted to display an icon that had been imported it worked OK. But as soon as I added an image block I got errors. The image block displayed:

This block has encountered an error and cannot be previewed.

and the console log contained.

Uncaught TypeError: this.activateMode is not a function
    at media-views.js:2815
    at arrayEach (webpack-internal:///360:516)
    at Function.forEach (webpack-internal:///360:9368)
    at i._createModes (media-views.js:2814)
    at initialize (media-views.js:2763)
    at initialize (media-views.js:2943)
    at initialize (media-views.js:3296)
    at i.h.View (backbone.min.js:2)
    at i.constructor (wp-backbone.js:503)
    at i.constructor (media-views.js:2688)
react-dom.82e849f1.js:19662 The above error occurred in the <MediaUpload> component:
    in MediaUpload (created by WithFilters(MediaUpload))
    in WithFilters(MediaUpload) (created by MediaPlaceholder)
... 

Additional complications

A further complication was that I'd recently updated my Gutenberg source installation to test the fixes for some bugs I'd noticed and had updated node to version 12.

Node 14 was too high. There were problems with node-sass. And after after downgrading to node 12 I got:

Error: Missing binding C:\apache\htdocs\wordpress\wp-content\plugins\gutenberg-wordpress-source\node_modules\node-sass\vendor\win32-x64-72\binding.node
Node Sass could not find a binding for your current environment: Windows 64-bit with Node.js 12.x

Found bindings for the following environments:
  - Windows 64-bit with Node.js 10.x

This usually happens because your environment has changed since running `npm install`.
Run `npm rebuild node-sass` to download the binding for your current environment.

I asked for some assistance on the #core slack channel and was pointed to https://stackoverflow.com/questions/63672622/typeerror-this-activatemode-is-not-a-function-gutenberg-wordpress, The question contains a link to the exact same blog post I'd read yesterday. I would have tried the solution had I understood how to change .babelrc.

The (only ) answer suggests the following.

1. Use the @wordpress/scripts package for your build process. It doesn't seem to be an issue here.
2. Use the following helper... and then a load of JavaScript

This single block plugin is the easiest way to implement 1.
In the longer term, if this works, I imagine I'll have to change my existing build scripts to use wp-scripts.

[bobbingwide]

I think this screen capture helps to answer the other question that I was asking myself yesterday which is "Why is the save method being called when using the block inserter?"

In this screen capture we see the new Toolbar icons block for the first time.

• The first one is from oik-blocks - not yet disabled.
• I've hovered over the second one - which is oik-sb/toolicons
• There's a preview of the block showing the hardcoded output.
• It shows what gets saved by the current code.

It turns out this is done because I've coded an empty example in the block registration.

 example: {
        },

Who'd have thought eh? Another mystery partially explained. I've raised an issue bobbingwide/oik-blocks/issues/40

[bobbingwide]

• The first one is from oik-blocks - not yet disabled.
• I've hovered over the second one - which is oik-sb/toolicons

I was telling porkys. The preview is from oik-blocks/toolicons. The other block didn't work.

[bobbingwide]

Building the block with wp-scripts has resolved the conflict reported in https://github.com/bobbingwide/sb-toolicons-block/issues/1#issuecomment-698840176.

Removing the example: {}, code has not stopped save() from being called. Block validation for oik-block/blockicon is still failing. As previously mentioned, this is another issue. Time to continue developing a solution for this block.

[bobbingwide]

New requirements

Thinking about how this block might be used I realised it would make a lot more sense for the plugin to be able to produce the predefined toolbar output for a particular block / variation.

• The plugin would support the core blocks and variations; 131 at the latest count.
• It would use the same labels as in core for the tooltips / menu item labels.
• The descriptions would be added by the documentation team.
• The polyglots would provide the language versions.
• The toolbar display on the front end should appear the same as in the editor, with the standard controls automatically added.
• It should be possible to automatically display the available block transformations.
• The documentation for each toolbar item would appear below the main toolbar
• Where a drop down menu is used, if there isn't a defined icon, then the icon used will be the default setting. e.g. for 'Change text alignment' it would be the icon for 'Align text left'.
• Whether or not the More options drop down needs to be displayed for each block has to be decided.

The icons should also include the main toolbar icons/ buttons:

• Add block
• Undo
• Redo
• Details
• Outline

and

• Switch to draft

• Preview

• Update

• Settings

• Options

• Shortcut keys may not be necessary

• Other toolbars include the Rich text toolbar for image captions.

• The heading levels 1 to 6 toolbar.

[bobbingwide]

This is a screen capture of the first prototype of the block. It displays some of the toolbar icons for the heading block.

Notes:

• The toolbar doesnt yet show the common controls.
• The alignment icons are actually displayed in a drop down.
• Tags and Styling need improving.

[bobbingwide]

This screen capture shows 3 text alignment options under the Change text alignment tool. It also shows some styling issues for icons that don't have separating borders between them. It would be nice to properly share the appropriate CSS that's used in the toolbar.

[bobbingwide]

The bane of my life.

react_devtools_backend.js:2273 Warning: Each child in a list should have a unique "key" prop.

Check the render method of `edit`. See https://fb.me/react-warning-keys for more information.
    in Fragment (created by edit)
    in edit (created by Edit)
    in Edit (created by WithToolbarControls(Edit))
...

And loads more stack trace but nothing useful like tellng me which keys aren't unique. There are a load of stack overflow issues, indicating I'm not the only one with the problem. https://stackoverflow.com/questions/28329382/understanding-unique-keys-for-array-children-in-react-js

[bobbingwide]

in Fragment (created by edit)

Well, the message was telling me what was wrong. I'd stopped looking at the fine detail. I'd resolved the issues with <li> tags not having keys but not realised that the <Fragment> needed a unique key value as well.

[bobbingwide]

I've been battling with CSS all morning. Now Gutenberg's adding paragraphs into my nicely crafted block generated HTML.

[bobbingwide]

Andrew Leonard asked why I had the new icon for Link and Unlink and he had the old style from WordPress 5. The answer is that WordPress SEO replaces both the Link and Unlink icons.

This applies to the (smaller) rich text toolbar used for Captions

This image also shows the Replace button in the Audio block's toolbar. I need to write code to support the display of text rather than icons. Note that for the More options pull down there aren't any icons, except for 'Add to reusable blocks', and that's on the right hand side below where the Shortcut keys are displayed.