Creating Wrappers, Sidebars, Callouts and Other Formatting Flourishes with WordPress Gutenberg

As the author of several WordPress plugins, I initially encountered the new Gutenberg editor that became standard in WordPress 5.0 as a disruptive change I had to scramble to adapt to. Since then, I have grown to appreciate it for significantly expanding what you can do with WordPress, particularly in terms of creating custom content formats to support your own uses of the platform.

The new editor model is organized around blocks of content: paragraphs, headings, bullet lists, images, and embedded videos are all blocks, and the editor displays different formatting options depending on the content type. It’s also possible for blocks to be defined with InnerBlocks, meaning that you are allowed to embed other blocks inside them. For example, the new Columns block lets you format content in two or more columns of equal width, and each column can include multiple paragraphs, images, and so on.

In addition, blocks can be programmed to act like WordPress shortcodes — placeholders for dynamic content that requires server-side processing. I’ve used that technique in the event listings block for my RSVPMaker plugin. In this post, though, I’m focusing on formatting of ordinary content.

Some parts of the new WordPress editing experience still need improvement, but I’m encouraged by the pace at which enhancements to the core platform have been arriving. If the content formatting controls delivered as part of the base platform don’t quite meet your needs, there are a few ways you can achieve the effects you desire:

• Take advantage of plugins that provide a libraries of additional formatting blocks, enhancing both how you work in the editor and what visitors see on your site.
• Take advantage of the Additional CSS Class field you will find in the Advanced tab of every block to tag a specific block of content. Use the Customize utility’s Additional CSS tab to provide additional formatting commands targeting that content.
• Create your own Gutenberg plugins, as I’ve done with Floating Callout and My Marginalia, to meet your own needs or those of clients.

I share examples of each of these below.

Gutenberg Block Collections

Although I’ve created plugins that enable a single custom block to address a specific need, some talented interactive designers have created collections of components to meet common requirements. One of the best I’ve found so far is Editor Blocks by Danny Cooper, which includes some nice components for formatting team member or product description tables —

— plus a nice wrapper or container block that allows you to specify margins, padding, and a background color or image to wrap around any content, including one of their other components.

Here is what the editing experience looks like for that Teams block.

I’ve never liked WordPress page builders, or themes with their own built-in page builders, because they always seemed too restrictive or prescriptive about what content to put on the page or how to format it. To me, selecting a library of Gutenberg blocks is a nicer mix-and-match solution to getting what I want.

Setting a CSS Class

As a rule, I recommend installing the minimum number of plugins you need to get your website functioning the way you want it to function. That means installing a plugin just to get a particular formatting effect on a blog post or web page may not make sense, unless you think you will use that formatting block on multiple pages and posts.

The simplest alternative for someone who knows CSS coding is to take advantage of the fact that Gutenberg blocks always give you the option of adding an additional CSS class.

Here is an example, in the context of a paragraph that I would like to display as a float: right callout or sidebar on the front end. This technique will not change what I see in the editor, but it will allow me to change what website visitors see.

Here is what I’m aiming for:

The easiest way to add the formatting code associated with this class, without altering my website theme, is to enter it into the Additional CSS tab of the Customize utility.

For a similar sidebar effect, you can use the built-in Columns component and set the Additional CSS Class field for a paragraph within that column as shown here.

Result with some added CSS:

Here is the code that was used in these two examples:

p.callout {
	width: 50%;
	float: right;
	background-color: #000;
	color: #fff;
	padding: 10px;
	margin-left: 20px;
	font-size: large;
}
p.column-callout {
	background-color: #ddd;
	padding: 10px;
	border: thin dotted #000;
}

The Columns block works best when you want to present one or more blocks of content in parallel, where the height of the two columns will be approximately equal. A good use is displaying alternatives, like the instructions for the iOS and Android versions of an app. Since each column can contain multiple other blocks, a better way of formatting the entire column would be this:

.iosvsandroid div:first-child {
	padding: 5px;
	background-color: #eef;
}
.iosvsandroid div:nth-child(2) {
	padding: 5px;
	background-color: #efe;
}

With this code added through the Customize utility, any Columns block for which we have set the iosvsandroid class will be formatted with different color backgrounds for the first and second columns.

Note that compatibility with your theme is not guaranteed, either with a custom block delivered by a plugin or with custom CSS like what I’ve shown above. In fact, the code above worked well with one site I manage and not with another. Figuring out why can take some serious CSS genius detective work.

Create Your Own Plugin

If you have a specific format you use regularly, and don’t see an easy way to achieve it with the built-in WordPress blocks or an existing plugin, you can consider creating your own.

My examples:

• I have always liked presenting sidebar and callout content aligned float:right, as in the CSS example above. My Floating Callout plugin makes it easy to do that within the editing experience, without having to futz with CSS and HTML code each time.
• A client, Geeks on Tour, publishes show notes to accompany the recordings of its webcasts on tech for travelers. For example, the notes might include additional screen shots, links, or document downloads associated with each portion of the program. Each note is presented with a timestamp for the corresponding portion of the program in the left margin, with a link on the timestamp that takes you to that segment of the recording on YouTube. Geeks on Tour co-owner Chris Guld experimented with using the built-in Table block to format this content, but found it frustrating to work with. The My Marginalia plugin makes it easier.

The Gutenberg block development learning curve can be steep for anyone who is not already an advanced JavaScript programmer. Prior to studying Gutenberg, I had learned a few tricks with JQuery and was pretty good with PHP, MySQL, and finding my way around the various WordPress APIs. I was unaware that I had missed out on several generations of advances in JavaScript technology — and am still trying to come up to speed on React and related technologies Gutenberg is based on.

Making it harder, the documentation published on WordPress.org is not nearly as complete for the JavaScript APIs as it is for the PHP functions, hooks, and filters. How-to tutorials are starting to emerge, but I can’t always find one that answers my specific questions (the way I almost always can for the more established WordPress APIs). One good unofficial directory of tutorials is Gutenberg Hub.

Consider this snippet of JavaScript code:

That return statement sure looked like an error to me, the first time I saw that formatting! Shouldn’t there be quotation marks defining those HTML tags as strings? If you took a code fragment like that and pasted it into your JQuery (which I’m pretty sure I tried at some point), your browser would in fact throw hysterical errors. That’s because this code is not meant to be fed directly into a browser but rather “compiled” first into a form your browser can understand. Gutenberg builds on the React JavaScript framework developed by Facebook and released as open source, which was designed to enable high performance JavaScript-powered user interfaces.

The mix of HTML, custom tags like <InnerBlocks.Content /> that represent JavaScript components, and JavaScript variables like {wrapperStyle} is from a template language called JSX. Again, this is the source file for our software project, not the “distribution” version we will actually feed to a user’s browser. Once you get used to it, JSX is a convenient way of specifying a user interface without resorting to low-level JavaScript commands. The compilation process I mentioned doesn’t create a binary (like compiled C code), but it does minify and streamline the code, transforming those html tags into basic JavaScript commands like document.createElement(‘div’).

Honestly, I’m only halfway to understanding all this myself. To start creating Gutenberg plugins, I recommend looking up a good tutorial on a utility called Create Guten Block, which bundles together a number of software downloads to allow you to start creating these projects with minimal configuration. As a prerequisite, you will need to get node.js installed on the computer you’re using for development. Node gives you the JavaScript-enhanced command prompt you will use to install Create Guten Block and compile source code into optimized code for distribution as part of a WordPress plugin.

One of the ways I’m learning, as usual, is by looking at the source code from tutorials or other well-designed plugins and adapting it. When working on Floating Callout, I was struggling to get the code right for the Inspector component (the sidebar displayed in the editor that allows you to change settings associated with your block) until I appropriated the one from the Editor Blocks Wrapper component and started making changes (then sent the author a thank you note).

If you’re a web publisher or designer but not a programmer, you can spec out what you need and hire someone to create it for you.

The most important point I want to make with this whole post is that Gutenberg opens up new opportunities for writers, editors, designers, and site owners. It’s going to get a lot better, and I can’t wait.