The Ultimate Guide to building custom Collections in Genesis Blocks.

Collections were released to Genesis Blocks last November. Single click sections and full-page layouts are pretty sweet, but… if you were paying attention, you may have realized something. Genesis has long been a solution for agencies and freelancers who want a secure, performant, and optimized foundation for their own work. Child themes for the Genesis Framework have been an industry unto themselves, but in the world of the Block Editor (Gutenberg), the fundamentals are changing.

Collections are the modern analog of Genesis child themes. And you can make your own.

We have made and will continue to grow, a library of Collections that are beautifully geared for quickly creating amazing content and full sites. But if you’re an agency or freelancer, you can actually make (did someone say distribute??? 🤔) them yourself.

Let’s show you how! 

Github repo right here for anyone wanting to jump straight to reviewing the code.

Heads up: This tutorial includes a bit of coding. Nothing crazy, but we’ll be creating a small plugin.

Step 1: Design & Build our Content

Let’s spin up a WordPress site on Local, install Genesis Blocks and the Genesis Block Theme, and create a few beautiful pages.

Note: Genesis Block Theme isn’t a dependency. 

Our Collection is going to be for an interior design firm website and it’s going to be called “Luxe”. It will include 6 sections and a single “Home” page layout.

Here are the 6 sections, and if you want to see them live and in action, follow this link.

The sections

Each one of these Sections is built with a combination of WordPress core blocks and those in Genesis Blocks. Every bit of their styling is handled by the block style controls, nothing is coded or hidden away in the Customizer.

The photos have been sourced from Unsplash.

Step 2: Scaffold the Plugin

We’re going to build a (very) small and simple plugin. This plugin will contain the code for the Luxe Collection and its sections and make them available to the Genesis Blocks Layouts block if the Genesis Blocks plugin is active.

Remember we’re using Local to build this out so we have easy access to our site files. 

In our plugins folder, we add a folder for our plugin and a few subfolders and files:

plugins/
    genesis-luxe/
        assets/
        layouts/
        sections/
        genesis-luxe.php

Few things to note here:

• Because this plugin is designed to only handle a single Collection, we’re naming our plugin, and the plugins folder, the name of the Collection genesis-luxe.
• We have an assets folder where we store all our collection’s related images that are surfaced in Genesis Blocks to the end-user in the Layouts block interface.
• We have a layouts folder where we will store the HTML for our layouts.
• We have a sections folder where we will store the HTML for our sections.

In our genesis-luxe.php file we add a header block of text, formatted as a comment. WordPress reads this block of text for information about the plugin. In ours we have:

<?php
/**
 * Plugin Name: Genesis Luxe Collection
 * Plugin URI: https://studiopress.com
 * Description: The Luxe Collection for Genesis Blocks
 * Version: 0.1.0
 * Author: Rob Stinson
 * Author URI: https://studiopress.com
 * License: GPLv3
 * License URI: http://www.gnu.org/licenses/gpl-3.0.html
 */

We could actually include all of the code and template HTML within this single PHP file. However, because we want to give our users a number of layouts and sections, it’s better to break down our code into more manageable chunks, hence the sub-folders.

Step 3: Register the Collection & Add our Home Page Layout 

Now in our genesis-luxe.php file, we’re going to create a function that we’ll hook to the plugins_loaded action. This function will include all the informational data and reference the content data needed for our Collection.

In the code snippet below, we are going to focus on just the Home Layout of our Collection. This Layout actually includes all 6 of our Sections. A one-click full-page install of predesigned content.  ❤️

function genesis_luxe_hero() {
	// Ensure a proper version of Genesis Blocks is active before continuing.
	if ( ! function_exists( 'genesis_blocks_register_layout_component' ) ) {
		return;
	}
	// Register the Luxe Home Layout
	genesis_blocks_register_layout_component(
		[
			'type'       => 'layout',
			'key'        => 'genesis_luxe_home',
			'name'       => 'Luxe Home Page',
			'content'    =>  require 'layouts/home.php',
			'category'   => [
				'Text',
			],
			'keywords'   => [
				'Home',
			],
			'image'      => plugin_dir_url(__FILE__) . 'assets/luxe_layout_thumbnail_home.png',
			'collection' => [
			'slug'  => 'luxe',
			'label' => 'Luxe Collection',
			'thumbnail'      => plugin_dir_url(__FILE__) . 'assets/luxe_collection_thumbnail.png',
			],
		],
	);
}
add_action( 'plugins_loaded', 'genesis_luxe_hero', 12 );

So what’s going on here?

• Our function name (genesis_luxe_hero) is unique to our plugin. Don’t wanna conflict with other plugins!
• The if statement checks to make sure Genesis Blocks is active. If it’s not, the rest of the code doesn’t run.
• The array of data represents all the different pieces of information we can pass to Genesis Blocks in order for our Layout to work.
• For the thumbnail image assets we use plugin_dir_url(__FILE__) to reference our assets folder.
• We assign this Layout to the “Luxe” collection which at the same time…
• … registers the Luxe collection itself. We don’t need to do this separately. Nice!
• The value for the  content key points to a home.php file in our Layouts folder

Let’s now add the code for our Home Layout. 

In the layouts folder, we add a home.php file. In here we need to first add:

<?php
return '

';

It’s inside these single quotes we’ll drop in our content data for the Layout.

One of the cool things about how WordPress handles content data in the block editor is that it’s just HTML.

So to get our content data for our Home Layout, back in Gutenberg, we go to the page we’ve created our sections in. Click the 3 dots up the top right-hand corner of the screen and switch to code editor. This shows you the HTML for the blocks on your page. Copy the entire pages HTML to your clipboard like the below:

Once you have this code, paste it into the home.php file between those single quotes.

There is one small, slightly tedious step here now. We need to “escape” all single quotes in our code. Being a PHP file, PHP will interpret the single quote character as code to execute, rather than just content. In our above example, there is a single quote character in the word “let’s”. So in our home.php file, this needs to become  “let\’s”. 

Nifty online tool here to make escaping stuff easier.

With this done, our home.php file looks like this (over on GitHub as the file gets pretty big).

Right now we’ve covered 90% of what you need to know. With our plugin here active we can actually go create a new page and add our Luxe Home Page Layout:

Step 4: Add our 6 Sections to the Collection

For each of our sections we add a content file in the sections folder like this:

sections/
    about-1.php
    about-2.php
    hero.php
    process.php
    services.php
    testimonials.php

And just like we did for the home page layout, we visit the block editor and go to the code editor view. Here we grab the HTML for each individual section and then paste them between those single quotes in each content file. Don’t forget to escape where needed.

Now back in the main genesis-luxe.php file, we repeat what we’ve done previously with that genesis_blocks_register_layout_component for each of our 6 layouts. We can contain each of these with our same genesis_luxe_collection function. We tweak the array values to match each of our Sections and reference the appropriate image assets and content files.

In the end, our full genesis-luxe.php file looks like this (on Github again).

With all of our sections added, the Luxe Collection screen in Genesis Blocks now looks like this:

Step 5: Use & Share the Collection

That’s it! We’re all done. A completely custom collection, installable as a plugin and which is made available via the Genesis Blocks user experience.

Make sure you check out (or even checkout) the GitHub repo for this to get a really good understanding of the code. Here’s a zip of the plugin as well if you would like to install it on a site and play around.

Wrapping things up

Block Patterns / Collections are the future analog of the classic Child Theme. There is huge potential for agencies, freelancers, and creatives who adopt this approach to building with WordPress.

Let me know in the comments if you go ahead and build your own collections. I’d love to check them out!

Peace!