Blog

It’s been roughly one year since WP Engine acquired StudioPress, the makers of the Genesis Framework. There’s been a lot of forward progress, but it may have left some people feeling unsure about how to work with Genesis or best take advantage of new features

In this post, I’d like to talk about some of those changes and how you can start using them as you customize or develop child themes.

Note: This post contains affiliate links. Every time you click on one and buy something, a hole opens up in my roof and dollar bills rain down on my head. Unfortunately, it’s never enough money to fix the hole.

Summary of features discussed in this article:

• Theme onboarding
• Gutenberg / Block Editor
• Genesis and AMP
• Custom Loop with query_args on any page
• Template files in the root directory
• Customize the Credits Text (no code required)
• Toggle breadcrumbs, the title, or featured images

New features in Genesis 2.8 to 3.1

Theme Onboarding (Introduced in Genesis 2.8)

Imagine a world where you install a child theme and … it actually looks like the demo! As of Genesis 2.8, developers can take advantage of a “theme onboarding” feature that gives end users a one-click option for installing recommended plugins, importing demo content, setting up the home page (or other pages), and creating/assigning a menu.

Brilliant.

Using theme onboarding

While Genesis supports this lovely feature, it’s up to theme developers to add onboarding to Genesis child theme(s) they create. You can only take advantage of this one-click setup if you’re working with a theme that specifically implements this.

At the time of this writing (and to the best of my knowledge), these are the StudioPress themes that currently include support for one-click setups:

• Authority Pro
• Essence Pro
• Genesis Sample
• Monochrome Pro
• Revolution Pro

If you know of other themes that support it or are a third-party theme developer and would like me to include your theme in the list, leave a comment.

Who benefits from theme onboarding?

• People who sell Genesis child themes: Your support costs just went down thanks to the ability to walk your users through theme setup with a single click.
• People who buy Genesis child themes: With a single click you can have your site set up to look like the demo, complete with imported sample content, images, and a menu. Of course, you still need to put in your own content, but this gives you a great starting point.

Genesis and Gutenberg (WordPress 5.0)

Unless you’ve been hiding under a rock or are simply new to the world of WordPress, you’ve heard about Gutenberg, a “block” editor that gives users a more intuitive way to create rich content.

This is less about what Genesis brings to the table and more about what Genesis child themes make available, specifically support for certain blocks and corresponding block styles.

While you can use the new editor with any StudioPress theme, the following ones have additional support built in for wide image alignment and block-editor styles to match front-end styles (essentially giving you a more realistic preview of what your published content will look like).

• Altitude Pro
• Authority Pro *
• Breakthrough Pro
• Essence Pro *
• Infinity Pro
• Magazine Pro
• Monochrome Pro *
• Revolution Pro *
• Sample *

* These themes also showcase block-based home page layouts.

Atomic Blocks plugin

In addition to default blocks provided by Gutenberg, there are also a variety of plugins that provide additional blocks you can use in your content. Plenty of them work just fine with Genesis, but the one I want to specifically call out is Atomic Blocks.

It includes things like a Call-To-Action block, a Pricing Table block, an Accordion block, and blocks for other types of popular content.

In case you didn’t know, Atomic Blocks is also part of the WP Engine family. This is excellent because it means there’s plenty of reason to believe that Atomic Blocks will continue to evolve (and that it will work seamlessly with Genesis).

Block-based homepage layouts

While we’re on the topic of home page layouts with Gutenberg, here’s how you can leverage the block editor to create one in any child theme.

Block-based layouts for any page

The idea of skipping the widgets and using blocks to layout a homepage is fantastic. AND, I probably don’t need to add (but will anyway) that you can use the block editor to create fancy page layouts for any page or post. 🙂

Before moving on, I’d be remiss if I didn’t drop a link to Bill Erickson’s articles on Gutenberg and his Developer’s Guide to Gutenberg Theme Development. He dives deep into code samples and explanations you’ll want to read if you’re creating child themes and want to maximize their Gutenberg-ness.

Genesis and AMP (Introduced in Genesis 3.0)

AMP is a technology created by Google to optimize a site for fast, nearly instant loading, and smooth-loading web pages across all devices. With Genesis 3.0 comes AMP specific tools to detect if the AMP plugin for WordPress is active on a site, and if so, output AMP compatible code.

StudioPress Developer Docs

Using Google AMP with Genesis

The idea of AMP is a little contentious, but, for site owners wanting to use it, Genesis has made it easier for you. Go here for instructions for implementing AMP on your site. Note that not all child themes are built in a way that’s compatible with AMP (for example, AMP doesn’t allow for the use of JavaScript, so if you’ve got a child theme loading any JS, too bad). Genesis doesn’t fix that for you (though Genesis does include a script for a responsive menu you can leverage in a child theme).

If you’re a developer and want to know more on the subject of AMP, look no further than Bill Erickson’s article on Building a Native AMP WordPress site.

Who benefits from Genesis AMP Support?

• Developers who have clients specifically requesting this feature. Note that you’ll want to use the newly added genesis_register_responsive_menus() function so that you don’t have to enqueue a responsive menu script in your child theme. Look at how this is done in the Genesis Sample theme as an example of responsive menu implementation in a post Genesis 3.0 world.

Custom loop with query_args (Introduced in Genesis 3.0)

For many moons, Genesis had a documented “Easter Egg” you could use in conjunction with the Blog Page template (page_blog.php) to generate a custom loop. This was done by creating a page and a custom field with the name query_args and then assigning that field a particular value.

It was an easy way to create an archive for a particular category, tag, etc.

Over 5 years ago, Bill Erickson educated me on why I shouldn’t use the Genesis Blog Page Template. I listened and stop using that Easter Egg awhile back.

In Genesis 3.0, the page_blog.php template was removed, but support was added to use the query_args custom field on any page to invoke a custom loop.

Here’s a quick rundown of how it works.

When the genesis_loop is run, there’s a conditional on line 22 that checks whether or not the loop is being run on a single page and whether there’s a custom field with the name “query_args”. If so, it takes the value of that field and passes it as an argument into genesis_custom_loop.

From there, the custom loop runs and — with no code — you get a custom query. Pretty cool.

Templates Files in the Root Directory (Introduced in Genesis 3.0)

In Genesis 3.0, the following template files were removed:

• 404.php
• page.php
• page_archive.php
• page_blog.php
• search.php
• single.php

These templates existed for backward compatibility and weren’t needed (the index.php in Genesis, which calls the genesis() function handles all scenarios those templates would be needed for.

But removing these templates caused breakage for some older themes and customizations added by users. So, one day after they were removed, these four were added back in (version 3.0.1):

• 404.php
• page.php
• search.php
• single.php

What about the other two? In both cases, the Genesis development team put code in place to “gracefully migrate” pages using page_blog.php or page_archive.php.

I have a feeling that the 4 remaining templates will be pulled from Genesis at some point in the future. I’m unaware of how child themes were relying on those templates in a way that would cause breakage, but I’d certainly steer clear of them in the future.

If you’re appropriately using the WordPress Template Hierarchy and following Genesis Child Theme Best Practices, you’ve got nothing to worry about.

Customize the Credits Text (Introduced in Genesis 3.1)

In the past, if you wanted to customize the copyright or “credits” text that appears in the footer of a website, you had to manually make the change in the code, using the genesis_footer_creds_text() filter or use the Genesis Simple Edits plugin.

Praise the Lord and pass the apple pie because now you can easily change that text from within the Theme Customizer. Go to Appearance > Customize to launch the customizer and, from there, go to Theme Settings > Footer.

Note that the genesis_footer_creds_text() filter NO LONGER “WORKS.” If you were using that filter to customize the footer creds, those customizations should automatically be pulled into the customizer upon updating to Genesis 3.1. Use the customizer moving forward to make changes to footer text.

Toggle breadcrumbs, the title, or featured images (Introduced in Genesis 3.1)

• Toggle on/off breadcrumbs on a per-page basis. You can turn on (or off) breadcrumbs for an entire site via the Theme Customizer, but now you can also toggle them on a per page basis.
• Toggle on/off page or post title. This is awesome! Let’s say you want to include the post title as part of the actual post content for some reason (i.e. you’re using the cover image block at the top of a post and it includes the title). In that case, you wouldn’t want to display the post title. In the past, you could achieve this programmatically or by using Bill Erickson’s Genesis Title Toggle plugin. But now? This feature is baked right into Genesis core.
• Toggle on/off featured images. Displaying featured images on archives is another site-wide setting available from the Theme Customizer. This new setting enables you have a featured image that displays on a content archive, but doesn’t display on the post itself.

To put it shortly (or not)…

Genesis is not dead. Far from it. While a lot of new front-facing features were added over the past year, many changes in the framework happened behind the scenes. For instance, deprecated code (such as XHTML output) was completely removed, the organization and structure of the code was overhauled, and there was a decisive move to follow a more object-oriented approach.

With a customer base of some 250k+ users, making big changes to software (especially removing some components of backwards compatibility) was risky, but the Genesis development team has done a solid job of mitigating those risks. I appreciate that they’re moving the software forward with a continued focus on leanness and performance.

Now comes the part of educating folks on how to leverage these changes. I’m attempting to do that a little bit with this article, but here are some other developers and resources you can look to for help.

Happy customizing!

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.