An Introduction to Block-Based Homepages with Genesis Framework

StudioPress recently released Revolution Pro, the first Genesis child theme to sport a block-based homepage.

If you’ve been around StudioPress and Genesis (or heck, just WordPress) for awhile, you’re familiar with the concept of a widgetized front page. Widgets weren’t really ideal as a layout tool, but they made it possible for theme developers to create attractive home page layouts that people could take advantage of even if they didn’t know code.

So it’s what we used.

But what if you could take advantage of the Gutenberg block editor for a home page layout? You can and StudioPress shows us how with Revolution Pro theme (and the Genesis Sample theme, too).

This post includes affiliate links. Every time you click and buy, I raise a toast to you from my yacht!

Why are blocks better than widgets for a home page?

In this WordPress 5.0+ block editor era, there’s no reason we can’t use blocks to create better home page layouts. As a matter of fact, it’s superior to widgets for multiple reasons.

1. Hard-coded widget areas for a specific layout

Let’s say you’ve got a home page with 4 widget areas used to display content in 4 columns. Looks nice, yeah?

But what if you only want 3 columns. Or 5 columns?

If you wanted to add an extra widget area, you’d need to register a new widget area. If you want to change the number of columns, you’d need to change the supporting CSS (across all relevant break points).

While some of the newer Genesis child themes (i.e. Essence Pro, Infinity Pro)  are flexible enough to account for those changes, most are not and would require getting into the code to change.

Blocks, like honey badgers, don’t give a $h!t about widget areas.

2. Hard-coded styles for specific widgets

Home page styles were frequently designed for a specific type of widget and looked weird if you wanted to use a different widget. For example, let’s say the Header Right widget area was pre-styled for a search widget, but you wanted to use a navigation menu widget there instead. Unless the theme developer accounted for styles for a menu in that widget area, it’d look like crap. ?

3. Your front page is actually… your front page

Creating a dynamic front page (i.e. a front page made up of widget areas) historically involves:

1. Registering desired widget areas in functions.php
2. Creating a front-page.php template file to display widget areas
3. Create a Page. Call it “Home” or “Front page” – the name doesn’t matter. Leave this page empty.
4. Go to Settings > Reading > Front Page Displays > and set that to the page created in Step 2.

With a block-based home page, you eliminate the first two steps. Now, you just create a Page, use the block editor to lay it out / design it, then set it to display as your Front Page.

This is so much more intuitive for users to have an actual Page you can directly edit vs messing with a bunch of widgets.

Those are just a handful of examples of how widgets are limited in their flexibility and usage. Blocks, on the other hand…

Create a block-based homepage

Hopefully you’re on board with me that blocks beat widgets in terms of simplicity and intuitive use. If so, let’s take a look at how to create a block based home page.

Method 1: I want to create a block-based homepage for my site

Good news. This is easy. First, you either need to have WordPress 5.0+ installed (and are using the block editor) OR you need to download the Gutenberg plugin for use with anything older than WP 5.0. (For the record, if you’re still on an older version of WordPress, why??)

Then, simply follow these steps:

1. Create a page. Use the block editor to create a beautiful layout.
2. Go to Settings > Reading > Front Page Displays > and set that to the page you want.

Hoping for something harder? Too bad, that’s it.

Method 2: I’m a theme developer and want to add block-based homepages to my themes.

In this scenario, we want to “bake in” a home page that uses the block editor in a pre-set layout, like the Revolution Pro theme does. Then, when a user installs your theme, they go through the theme onboarding process (requires Genesis 2.8+).

That user experience looks like:

1. Install/activate theme
2. Click the “Set up Homepage” button
3. Sit back and watch the beauty unfold
4. Go edit the freshly created home page (pre-populated with demo content!) to add their content

The developer experience is, well, more complex. That roughly involves:

• Create a file with the block markup (layout) and content you want to use for the front page
• Include any images you want to use on the front page
• Create a page template (used as the template for the front page)
• Create an onboarding file (used to load plugins, create the front page, and load theme demo content)

While you can find the documentation for the onboarding process here, I wanted to conceptually explain how it works.

Code logic and load order

As a theme developer, you’re familiar with the role of the child theme’s functions.php. Imagine we’re stepping through functions.php (only as far as the onboarding process goes)…

At some point, the Genesis Framework is called to come play. A lot of StudioPress themes do that like this:

// Starts the engine.
require_once get_template_directory() . '/lib/init.php';

In other themes, you might just see child theme setup stuff hooked directly into Genesis, like this:

add_action( 'genesis_setup', 'child_theme_setup', 15 );

However you want to do it, Genesis is loaded via a child theme’s functions.php.

Important note here: The Genesis Framework handles all the logic for the onboarding sequence.  From here on out, Genesis will look to the child theme for some files, but the logic is handled within Genesis.

When the framework loads, it goes looking for a file called onboarding.php within the framework. THAT file then goes hunting for config/onboarding.php in the child theme.

No onboarding file present?

If the child theme doesn’t have a file called onboarding.php inside of a /config folder in the theme root, then no further onboarding happens. If you tried to trigger the onboarding sequence by going to /wp-admin/admin.php?page=genesis-getting-started, you get this error:

Onboarding file present -> PROCEED!

The child theme’s onboarding.php supports loading plugins, content, and language packs. For the purposes of this article, I’m going to follow the content. It’s an array that might look like this:

return array(
	'content'      => array(
		'homepage' => array(
			'post_title'     => 'Homepage',
			'post_name'      => 'homepage-gutenberg',
			'post_content'   => require dirname( __FILE__ ) . '/import/content/homepage.php',
			'post_type'      => 'page',
			'post_status'    => 'publish',
			'page_template'  => 'page-templates/blocks.php',
			'comment_status' => 'closed',
			'ping_status'    => 'closed',
		),
	),
);

Let’s continue down the manufacturing line. That array of data gets sucked into Genesis’ onboarding.php into a variable called $config that’s tucked into a function called genesis_onboarding_content(). Here’s what that function looks like:

/**
 * Returns an array of onboarding content provided by Genesis or the child theme.
 *
 * @since 2.8.0
 *
 * @return array
 */
function genesis_onboarding_content() {

	$config_file = locate_template( '/config/onboarding.php' );

	if ( ! is_readable( $config_file ) ) {
		return array();
	}

	$config = require $config_file;

	return isset( $config['content'] ) ? $config['content'] : array();
}

All that’s happened so far is that we’ve made the onboarding content from the child theme available to the Genesis Framework. It’s up to Genesis to use it.

Still with me?

Genesis uses it when it calls the genesis_onboarding_content() function from /lib/admin/onboarding/ajax-functions.php. That’s a new file added in Genesis 2.8.

If you look back to the previous code snippet, you can see that all the function does is return an array containing the content.

We’re still hanging out in ajax-functions.php.

$content = genesis_onboarding_content();

The value returned from the function is stuffed into a variable called $content. From there, that content is added to the database via wp_insert_post().

And, voila! A page is created in the user’s WordPress install that contains demo content.

What’s happening in the child theme onboarding file

So far, as the developer, all you’ve had to provide is a single file in a config folder: config/onboarding.php. Let’s unpack this file because that leads to the next steps of what else you need to include in your child theme files.

return array(
	'content'      => array(
		'homepage' => array(
			'post_title'     => 'Homepage',
			'post_name'      => 'homepage-gutenberg',
			'post_content'   => require dirname( __FILE__ ) . '/import/content/homepage.php',
			'post_type'      => 'page',
			'post_status'    => 'publish',
			'page_template'  => 'page-templates/blocks.php',
			'comment_status' => 'closed',
			'ping_status'    => 'closed',
		),
	),
);

The contents of this array are the parameters that get passed to wp_insert_post(). For the post_content, the theme goes hunting for /import/content/homepage.php (which subsequently references a couple of images also living in the /import/content/ folder). That file contains all the block markup that will become the post content for the Homepage. If you’ve ever worked with an XML import in WordPress, the concept is similar. You’ve got a file full of markup and that’s gonna get inserted as the post_content for that post entry in the database.

The next bit I want to point out is the page_template. That instructs the onboarding process to assign page-templates/blocks.php as the template for the Homepage. If you’ve ever created a custom template and assigned it to a page, that’s all that’s happening here.

Create homepage.php

Step 1. Create a WordPress page

Are you ready to try this out? The first thing you’ll want to do is go create a page that you want to be your theme’s home page. Use the block editor. Make it beautiful.

Step 2. Grab the markup from that page

Once you’ve done that, the next step is to grab the block markup for that page. From the editor screen, click the three little dots in the upper right corner to open a menu. Change the Editor view from Visual Editor to Code Editor.

Select all of the markup from the Code Editor and copy it.

Step 3. Create a php file

Head over to your code editor and create a folder called /import/ in your child theme root and then create a file in that folder called homepage.php. While you don’t HAVE to use the same naming convention or file organization, I’d recommend following it unless you have a good reason not to.

The homepage.php file must return a string containing the content you wish to import (you know, the stuff hanging out on your clipboard right now).

Step 4. Follow the official instructions

The good people at StudioPress wrote up instructions on how to structure homepage.php and what all needs to be in that file. Follow the instructions!

Create the blocks template

If you’ve ever created a landing page template, the blocks template is similar in concept. While this template isn’t required, it’ll ensure your home page doesn’t look goofy. The blocks template is used to:

• force a full-width page
• remove header markup and post title
• add a custom body class to help with styling

Here’s the template used for the block-based homepage on the Genesis Sample theme.

Put it all together

Whew. I think that’s the first time in a long time I’ve written a post that required me to use H5 headers. That was a lot.

My hope is that you now have a better understanding of how you can create a block-based homepage with WordPress 5.0+ (Gutenberg) and Genesis 2.8+. You’ve also learned that you can take it a step further by creating an onboarding sequence for your theme users that automatically generates the home page with pre-populated blocks.

What do you want to learn next? Leave me a comment. 🙂 For more resources on Genesis and Gutenberg, be sure to check out Bill Erickson’s blog.