Introducing the OIT Block Template Generator

At tomorrow’s NC State IT Community Event, Jen will be giving a 10-minute lightning talk about reusing content in the WordPress block editor with reusable blocks and block templates. In her presentation, she’ll mention a developer tool we built to help us take advantage of block templates: the OIT Block Template Generator.

Side note: did you miss Jen’s presentation? You can check out the slides here! They contain lots of useful links and some code snippets. But also keep reading ’cause Brian’s stuff is cooler.

Since Jen has a lot of information she’s packing into a short time slot, she’s not going to get a chance to say a ton about this plugin. So let’s take a closer look here!

What’s a block template?

If you’re coming here right after Jen’s presentation, you can skip this part since she just explained it!

Block templates are a collection of blocks that can be pre-loaded when you create a new piece of content in WordPress. (They’re a little more than just that, too — see below.)

Out of the box, a new post, page, or custom post type is a blank canvas:

The WordPress block editor, with default behavior for a new page. No blocks have been added.

A block template allows you to define the blocks that should already be in the editor when a new post, page, or custom post type is created (with optional placeholder text or pre-loaded content).

Recently, Campus Enterprises decided to create a section on their website highlighting a new student worker each month. We worked with them to define a custom post type and a block template to ensure each profile had all of the elements they wanted:

The WordPress block editor, with a block template set for this post type. Several blocks have been pre-loaded.

Each time a new student profile is created, it’s created with a two-column layout, an image block, and some default content that can be customized by the author.

In addition to applying a block template to a custom post type, you can use a block template to build a custom block. This allows you to build a custom block quickly and easily. Instead of writing code for all of the different features of your block, you can just include core blocks that have the functionality you need, arranged however you want them to be arranged.

So if we didn’t want to use a custom post type, we could also create a Student Profile block that contains two columns, an image, and the same default content. That block could then be added to any post or page where you want to include a student profile.

Block templates are super handy, and have some neat features not mentioned here. They’re one of my favorite and most under-rated features of the block editor. Campus developers should definitely check out the block template documentation.

Generating a block template

Block templates can be coded by hand, either as:

  • A PHP array, when applied to a post type
  • JavaScript (following the syntax used for InnerBlocks), when used for building a custom block.

Neither of these are particularly difficult to code by hand. But you do need to know the attribute names and syntax, which can be a little cumbersome. (Our friend and former colleague Miles Elliott did build a block attribute glossary plugin that’s very helpful when doing this!)

But one of the strengths of the block editor is how it allows you to do page design and layout in a very visual interface. Speaking for myself, I can put together a multi-column layout with lots of blocks arranged the way I want them in the editor a lot faster than I can hand-code a block template that does the same thing.

Enter the OIT Block Template Generator!

The Block Template Generator is a super-simple WordPress plugin that lets you build a post or a page in the block editor, then generate the block template code that you can use for your plugin.

Start by mocking up the content you’d like to use as a template (eg. a short paragraph and a button block):

A paragraph block and a button block, added by the author to a new post.

Then, click the Generate a Block Template link in the WordPress toolbar. When the plugin is active, that link is available in the toolbar from both the editor and from the published page live on your website. (That means you can quickly create a new block template from any existing post or page you have.)

The "Generate a Block Template" link in the WordPress toolbar.

That takes you to a page in the WordPress Dashboard that gives you the block template versions of the content you just created, both as PHP and as the InnerBlocks syntax:

WordPress Dashboard page titled "Generate Block Template." The page contains a PHP array code block and an InnerBlocks code block generated from author-created content.

Copy the appropriate code block into your plugin, and enjoy all of the time you saved!

How to install this plugin

The OIT Block Template Generator is available to campus websites via Cthulhu. I recommend installing it on development or test websites only — not because it will cause any issues for your production website, but because it’s only going to be relevant to developers and will just be added clutter to non-dev users.

Some caveats: This plugin has not been deeply or extensively tested. It’s a quick-and-dirty development tool that was built in an afternoon, and it doesn’t handle all block attributes perfectly. For particularly complex block templates, you may need to do some editing by hand to get things to behave the way you want.

Contributions to improve the plugin in campus GitHub are very much encouraged! And if folks outside the campus community are reading this and are inspired to build a better plugin and upload it to the WordPress plugin directory, that’s also very encouraged!