WordPress Plugin Authors Should Avoid Confusing Users When Naming Blocks

On May 4, the StudioPress development team made a small but significant user-facing change to its Atomic Blocks plugin (now rebranded to Genesis Blocks). It removed the “AB” branding from its block titles. This minor update changed block titles such as AB Accordion and AB Button to Accordion and Button, respectively. On the surface, this change probably seemed of little consequence to the developers on the project. However, for at least one user, it created a massive workload.

Unless users religiously followed the GitHub code commits, they would have missed this update. Stacked with several other code changes for a seemingly unrelated ticket, the team left a message that read, “Remove unnecessary ‘AB’ from block titles.”

The change made it into version 2.8.2 of the plugin, which launched a day later.

The problem was that there was no message in the change log that noted this. Users had no indication that the blocks from the plugin were being renamed. Typically, this would not be a big deal since the plugin team had merely dropped the “AB” prefix from the otherwise unchanged titles. However, what happens when one of those blocks’ titles matches a core block title?

That was the issue that Marcus Tibesar ran into. The AB Button block suddenly became the Button block. Thinking he was using the core WordPress Button, he made liberal use of it throughout his site. Throw in his decision to drop the plugin after StudioPress rebranded its plugin to Genesis Blocks, it became a bit of a disaster to clean up.

“I have been using the Button block for months now only to discover that I’m actually using the Atomic Blocks button block!” wrote Tibesar in a comment on the Atomic Blocks rebranding post.

Theoretically, he should have needed to update only any lingering blocks from Atomic Blocks that he had knowingly used. But, he was stuck with blocks that he had unknowingly added to his posts and pages through no fault of his own.

This particular scenario was made worse because WordPress 5.4, released on March 31, introduced a new Buttons (plural) block. The old single Button block was removed from the normal inserter. While not all block-naming issues are so convoluted, it still begs the question: how can plugin authors avoid causing these types of user-experience issues?

It is easy to throw blame toward StudioPress — and the team could perhaps use a scolding for not being clear about the change when it happened. However, this brings forth a couple of things the greater WordPress community needs to figure out. The first is whether plugin authors need to use a consistent, prefixed naming scheme for their blocks. The second is what can WordPress do to help mitigate issues.

Prefix All the Things

Buttons, buttons, and more buttons.

That is the common saying in the WordPress development world, right? Prefixing and namespacing guidelines generally apply to the actual code, which is where conflicts arise. However, there are times when prefixing public-facing text is warranted.

And those times are when plugins utilize a shared space.

The block editor is one such shared space. With more and more block plugins landing in the directory, it is time that plugin authors consider how block-naming schemes affect end-users. The issue is certainly not limited to Atomic/Genesis Blocks. This has been an ongoing trend with several block library plugins. Some do better than others, but it’s a toss-up each time a user installs such a plugin.

The easiest route is for plugin authors to simply prefix all custom blocks with their company branding (e.g., AB Button). On the other hand, not every block shares a title with one of the core blocks. For example, a block titled Product Carousel may not need to distinguish itself further from other blocks. It is unlikely that end-users are running multiple eCommerce plugins with blocks that share the same title.

“All, repeat all, should have a prefix,” said Tibesar. “The prefixes eliminate any confusion as to whether we users are selecting a core block or a third-party block. The most popular plugins appear at the top of the list, and it’s confusing from whence they came when prefixes are absent.”

At the very least, third-party blocks should have a prefix if their titles match one of the core blocks. End-users should not see two different Cover blocks in the block inserter, for example. Instead, they should see the core Cover and a second, uniquely-titled block. Prefixing is an easy way to do that. But, I could live with anything that does not cause user confusion.

Locating Instances of Block Usage

Manage Blocks screen.

In late 2019, the Gutenberg team released the first prototype of a potential block management area for the WordPress admin. The Manage Blocks screen from the prototype showcased an area that would allow users to manage every block on their site. One of the more important bits of information on this screen was an “Instances” count, which displayed the number of times a block was in use. It further linked to a screen with every post that had a particular block.

One of the reasons this feature is important is that it would allow end-users to locate posts that they may want to clean up. Using the Atomic/Genesis Button block as an example, Tibesar could track down all those old uses and make any changes he wanted.

He said he would absolutely welcome this feature in WordPress. “New users are tempted to load up on zillions of block plugins all to be forgotten later. Also, maintainers would use this tool when cleaning up broken sites. Just being able to see an overview of what blocks were used where, will allow publishers to dial back the number of block plugins installed on their sites, especially when new plugins and technologies emerge.”

Because this feature is not in core yet, he had to turn to the Find My Blocks plugin, which helped him identify 22 posts and pages where he had unknowingly used the Button block from Atomic/Genesis Blocks. In the long term, this is something that needs to be handled directly in WordPress. It is unlikely to be the last time a user needs to clean house and get rid of old blocks.