Block Directory Slated for WordPress 5.5 Version

Photo by Matthew T Rader on Unsplash

The Block Directory will soon be a new way block editor users discover, test and install new blocks for their website. It has been a cross-team endeavor as it involves updates on the plugin repository, the plugin update processes in core as well as an integration into the block editor’s Inserter.

Last year we live-streamed a Live Q & A with the team working on the Block Directory, Mel Choyce-Dwan, Alex Shiels and CK Lee. They showed us a few prototypes and mock-up. Here is the video, resources and transcript.

On August 6th, another Live Q & A took place this time with Kelly Dwan, Alex Shiels and Samuel “Otto” Wood.

With the new version (8.4) of the Gutenberg feature plugin, the Block Directory left the experimental stage. It is now slated to be merged with WordPress Core in version 5.5 to be released on August 11, 2020. You can already test it with the WordPress 5.5 Beta 3.

Gutenberg’s developers, design, meta and REST-API teams have been working hard to finish this rather complex feature. Alex Shiels’ meta team posted a summary issue on GitHub to track all the moving pieces.

In this post, I look at all the angles of the Block Directory, give you my first impressions and links to learn more. Get your favorite hot beverage and keep on reading….

Find Blocks in the Directory
Screenshot of the List of Blocks in the Block Directory

Table of Contents

Video: Block Directory for WordPress 5.5 a Live Q & A

We had a very lively discussion about the Block Directory, Kelly Dwan and Alex Shiels from the meta team and Samuel “Otto” Wood from the plugin review team. The audience questions made it very interactive! Transcript is in the works.

How will the Block Directory work for content creators?

The idea is that if a user needs a block that is not yet available on their site, they type a keyword in the search field of the Inserter, like “team” or “staff.”

In the background, the system first searches the current site and if it doesn’t find a block, it also searches in the Block Directory, a special corner of the WordPress plugin repository, where single block plugins are available. If it finds blocks, they will be displayed in the inserter, including a preview section.

From there, the user can decide which block to use and click the button “Add Block.” In the background the single-block plugin is installed and activated, and the user can continue creating the team page.

Should the first choice not work out, the user can go back to the search and select a different one that also will be installed, so they can test it as well.

The Block Directory is only available to content creators who also have the capabilities to install and activate plugins.

All the moving parts

For this to work there are a few requirements that need to align perfectly:

  • Plugin Directory needs to have a special section for the single-block plugins to feed the search. This will not work with the many plugins with 30 or 40 or even just two blocks.
  • The search feature returns the results in a format the block editor can display in the Inserter.
  • The block editor needs a process to search the WordPress Plugin directory via REST-API.
  • The Inserter needs a method to install and activate plugins on the site, considering the user privileges on the site, and only allow this for site administrators.
  • The plugin author needs to provide a preview image and a block.json file to participate in the Block Directory. There are a few more guidelines to consider. See below.
  • The user needs additional information like name of the author, ratings and the date of the last update displayed in the preview for the decision-making process. Not everyone makes decisions totally on looks. There is a latent trust element to consider.
  • The block editor also needs to monitor discarded plugins and uninstall unused blocks from the site once the post is saved. It’s a tricky proposition and probably needs some tweaking further down the line.
  • An updated Block Manager should also help to avoid a block graveyard on the site. Mentioned last year as part of the Block Directory designs by Mel Choyce-Dawn, it doesn’t seem to be part of this release, though.
  • Block Manager Figma Prototype
  • Block Manager Screens Figma Prototype
Figma Prototypes of Block Manager screens – not available yet.
Click on the images to see a larger version

List of Single Block plugins

In the plugin repository you can review the list of available blocks that feed the search results in the block editor. Right now it’s only 4 pages. And maybe half of them are actually visible through the Inserter in the block editor. I did a few spot checks against the Block Validator and most of them are missing the block.json files.

Once the final requirements are documented and the guidelines published, more plugin authors hopefully will update their plugins to be searchable via the block editor.

Video of the List of Blocks in the Block Directory

Examples of tested single block plugins:

Search for blocks

It works quite well except for the lack of plugins. The functionality is not yet finalized. In this GitHub issue, Enrique Sanchez, Steven Dufresne and others on the design team explore different variations and considerations for the search, select and install flow. Should the disabled block also show up in the inserter’s search results with a button to enable the already install block? Or blocks in deactivated plugins? There is some ongoing discussion on GitHub.

At this time you also can’t search the Block Directory deliberately from the Inserter. An issue for a “Search Block Directory” button is on GitHub.

Installation of new blocks

This is quite seamless for the user, in theory. Click on “Add Block” and without leaving the block editor, the new block becomes available. We ran into a few cases when we would get an error message, and we were asked to try again. When it wouldn’t work, we found the plugins installed and the block was available. Soon they will get the kinks out of this fabulous new feature.

Create-Block Scaffolding Tool for a Quick Start

Inspired by the create-react-app and wp-cli command, the Gutenberg team created the official Create-Block scaffolding tool for single block plugins. @wordpress/create-block. Marcus Kazmierczak prepared the “Create a Block Tutorial” for the developers’ handbook.

Cover: Slide deck Getting blocks from code to repo
Slidedeck with speaker notes.

Recently, at the JavaScript for WordPress conference I walked the audience through the interactive mode of the tool and how the files fit into the context of the Block Directory.

Speaking of Documentation, in a post on GitHub, Anne McCarty started a discussion on the next steps for block creation documentation, requesting your input on what would help you as plugin author to get better at learning how to build blocks. Check it out.

But I digress……

Guidelines for plugin authors: a work in progress

In December 2019, Alex Sheils, team lead on the meta team published a draft of guidelines for plugins to be added to the Block Directory.

The post on the make blog has many comments, as does the GitHub issue.

The draft version is available on GitHub and has gone through some more discussions. Alex Shiels posted an update on the proposed guidelines on the Meta-Team blog

Here are the bullet points.

Block Directory plugins have the following characteristics:

  1. A specific type of WordPress plugin, with the same structure including a readme.txt file.
  2. Containing only blocks (typically one).
  3. Contain a minimum of server-side code.
  4. Do not have any UI outside the post editor.

8 Rules for Block Plugins for the Block Directory

The team has eight rules governing this first iteration. These restrictions are not to stifle plugin authors. They are meant to keep the scope of what kind of blocks are delivered to a site’s block editor restricted in this very first iteration.

  1. Block Plugins are for the Block Editor.
  2. Block Plugins are separate blocks.
  3. Plugin titles should reflect the block title.
  4. Block Plugins must include a block.json file.
  5. Block Plugins must not require payment or a paid account to function.
  6. Block Plugins should work independently.
  7. Server-side code should be kept to a minimum.
  8. Must not promote other blocks, plugins, or themes.

Alex Shiels published the latest version of the Block Plugin Guidelines. “These guidelines will be added to the official WordPress Detailed Plugin Guidelines, as a special section that applies to plugins submitted to the Block Directory” Shiels wrote.

The Block Directory is like a young plant. It needs to be watched and protected so it can grow into something bigger. One of my husband’s COVID-19 away-from-keyboard (afk) projects is to grow hot peppers in our backyard. We are city people, so gardening doesn’t come easily to us, and we don’t have any experience. The young pepper plants were eaten by the wildlife that visits our backyard about three times, and finally, we surrendered and put up a little fence and protect them from the iguanas, rabbits, squirrels and ducks. With the new location, they are outside the reach of our sprinklers, so Christian needs to put in an extra effort and water them if we there are no afternoon showers. He learns and listens, and iterates. That’s how work on the Block Directory will evolve. The team will watch, listen and iterate to make this a good place for plugins authors and users alike.

If your plugin doesn’t meet those criteria (yet), it is still very welcome as a ‘normal’ plugin for the plugins directory.

How to publish a plugin for the Block Directory – Block Plugin Checker

Alex Shiels published a post outlining the technical requirements and details Mid-July on how to publish a plugin for the Block Directory.

He built a completely new tool for plugin authors: Block Plugin Checker. They can use it to check if their plugins are ready for the Block Directory. The beauty is that this validator allows checks plugins that are still in development process before submitting it to the repository, or against a plugin already in the WordPress Plugin repository. I used it to check on our WIP plugin with a GitHub URL.

Checking my unfinished plugin, I learned quite a few things. Eventually, I could get a pass on it. My plugin is not yet in the repository as I am not finished debugging it. It’s good to know that once it’s finished, it will make it into the Block Directory.

Here are a few screenshots of “Errors” or “Warnings” I encountered while testing my plugin as well as others already in the repository, but they wouldn’t show up in the Inserter of the Block editor upon search.

Block Plugin Validator comments
Block Plugin Validator comments
Block Plugin Validator comments

With the Block Validator also comes a page explaining the messages. This, like everything else around the Block Directory, is still in the works. Please test and review things, and communicate with #meta team and #plugins team for more clarification and better understanding.

Should you try Block Plugin Checker and want to leave feedback on the UI, you can do so on this meta.trac ticket.

Note: Looking at some code, it seems the maximum size in PHP files’ to get past the Block Plugin Checker is 50 KB, ignoring /vendor/composer files

Uninstall unused plugins

In the GitHub repo we discovered two issues that have to do with the removal of unused plugins. The discussion is still ongoing.

I have the feeling that’s going to be the less an issue when the Block Manager will be introduced.

Disable the Block Directory all together

As with every new feature, there are voices that will ask how to disable things. Kelly Dawn, developer on the Block Directory wrote, “this should be all that’s needed to disable the block directory:“

add_action(
	'plugins_loaded',
	function() {
		remove_action( 'enqueue_block_editor_assets', 'wp_enqueue_block_editor_assets_block_directory' );
		remove_action( 'enqueue_block_editor_assets', 'gutenberg_enqueue_block_editor_assets_block_directory' );
	}
);Code language: JavaScript (javascript)

Love the Block Directory because of its promise

It’s been years since the manner in which we extend WordPress has been modified.

The Block Directory gives content creators and plugin authors an immediate, streamlined way to extend the content creation part with single blocks, which is even more exciting when you look at it in the context of Full-Site Editing experience, coming in a few months.

With all the moving parts, this first iteration of the Block Directory is a huge milestone. The newly created pathways for a background communication between block editor and block directory are an innovation for the plugin installation and update processes, without reinventing the wheel. It might be a hindrance of the full potential: for now only site administrators can use the Block Directory pathways, Editors and Authors roles cannot extend their content creation tool one block at a time. For now.

Many site owners are already overwhelmed by the number of blocks on their sites, when they installed one or two Block Collections plugins, and this is a refreshing way to rebuild one’s own block library from scratch one block at a time and be very deliberate on what one needs for a site. It’s not the time for it yet.

A good Block Manager area is in the works to help to make such a purge a less cumbersome endeavor. To make a risk-free decision to remove a block from the arsenal, you would need to know which block has been used for which post or page, so you can deal with the design or content ramifications of such a decision.

It will be interesting to see what plugin authors make for the block editor. There is so much creative potential in this one block plugin idea. There are many developers, who have been hesitant, as they haven’t conquered the block building develop processes yet. The new scaffolding tool create-block and its documentation and extension will hopefully help to bridge this gap.

These are exciting times full of possibilities and opportunities.

Resource List about the Block Directory

Featured image: Photo by Matthew T Rader on Unsplash

Changelog

Related Posts