Skip to content

Genesis Developer Docs

Genesis Onboarding

Requires Genesis 2.9.0+ and WordPress 5.0.0+

Onboarding is a theme setup wizard for Genesis child themes

Genesis Onboarding reduces frustrating manual theme setup by offering to automate parts of the theme setup process when a Genesis child theme is activated.

When activating a Genesis child theme with Onboarding support, users are redirected to a theme setup page:

Onboarding screen showing the Create Your New Homepage prompt.

Actions theme developers can take during Onboarding

Your child theme's onboarding.php config file determines what happens during the Onboarding process. You can:

Add Onboarding to your Genesis child theme

Add an onboarding.php file to your Genesis child theme's config folder.

Create the config folder in the root of your child theme (at the same level as style.css) if it does not exist already.

The onboarding.php file must return an array with a specific structure. Check out the onboarding.php file from the Genesis Sample theme as an example:

<?php
/**
* Genesis Sample.
*
* Onboarding config to load plugins and homepage content on theme activation.
*
* @package Genesis Sample
* @author StudioPress
* @license GPL-2.0-or-later
* @link https://www.studiopress.com/
*/

return array(
'dependencies' => array(
'plugins' => array(
array(
'name' => __( 'Atomic Blocks', 'genesis-sample' ),
'slug' => 'atomic-blocks/atomicblocks.php',
'public_url' => 'https://atomicblocks.com/',
),
array(
'name' => __( 'WPForms Lite', 'genesis-sample' ),
'slug' => 'wpforms-lite/wpforms.php',
'public_url' => 'https://wordpress.org/plugins/wpforms-lite/',
),
array(
'name' => __( 'Genesis eNews Extended', 'genesis-sample' ),
'slug' => 'genesis-enews-extended/plugin.php',
'public_url' => 'https://wordpress.org/plugins/genesis-enews-extended/',
),
array(
'name' => __( 'Simple Social Icons', 'genesis-sample' ),
'slug' => 'simple-social-icons/simple-social-icons.php',
'public_url' => 'https://wordpress.org/plugins/simple-social-icons/',
),
),
),
'content' => array(
'homepage' => array(
'post_title' => 'Homepage',
'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',
),
'blocks' => array(
'post_title' => 'Block Content Examples',
'post_content' => require dirname( __FILE__ ) . '/import/content/block-examples.php',
'post_type' => 'page',
'post_status' => 'publish',
'page_template' => 'page-templates/blocks.php',
'comment_status' => 'closed',
'ping_status' => 'closed',
),
'about' => array(
'post_title' => 'About Us',
'post_content' => require dirname( __FILE__ ) . '/import/content/about.php',
'post_type' => 'page',
'post_status' => 'publish',
'page_template' => 'page-templates/blocks.php',
'featured_image' => get_stylesheet_directory_uri() . '/config/import/images/about.jpg',
'comment_status' => 'closed',
'ping_status' => 'closed',
),
'contact' => array(
'post_title' => 'Contact Us',
'post_content' => require dirname( __FILE__ ) . '/import/content/contact.php',
'post_type' => 'page',
'post_status' => 'publish',
'featured_image' => get_stylesheet_directory() . '/config/import/images/contact.jpg',
'comment_status' => 'closed',
'ping_status' => 'closed',
),
'landing' => array(
'post_title' => 'Landing Page',
'post_content' => require dirname( __FILE__ ) . '/import/content/landing-page.php',
'post_type' => 'page',
'post_status' => 'publish',
'page_template' => 'page-templates/landing.php',
'comment_status' => 'closed',
'ping_status' => 'closed',
),
),
'navigation_menus' => array(
'primary' => array(
'homepage' => array(
'title' => 'Home',
),
'about' => array(
'title' => 'About Us',
),
'contact' => array(
'title' => 'Contact Us',
),
'blocks' => array(
'title' => 'Block Examples',
),
'landing' => array(
'title' => 'Landing Page',
),
),
),
);

Onboarding config details

Using a separate file for your post_content

We recommend storing page content you wish to import in a separate file.

Instead of including a long string in your onboarding.php config, like this:

'post_content' => '<!-- wp:paragraph --><p>This is a simple paragraph block, but your imported content can contain much more exciting content than this.</p><!-- /wp:paragraph -->';

You can require a file that returns the string instead, like this:

'post_content' => require dirname( __FILE__ ) . '/homepage.php',

This homepage.php file can be named as you wish. It can live in your config directory, but you may wish to place it in a subdirectory such as config/import/:

'post_content' => require dirname( __FILE__ ) . '/import/homepage.php',

The homepage.php file must return a string containing the content you wish to import:

<?php
/**
* Your Theme Name
*
* Homepage content optionally installed after theme activation.
*
* @package Theme Name
* @author Your Name
* @license GPL-2.0-or-later
* @link https://example.com/
*/


$theme_name_homepage_content = <<<CONTENT
<!-- wp:paragraph -->
<p>This is a simple paragraph block, but your imported content can contain much more exciting content than this.</p>
<!-- /wp:paragraph -->
CONTENT;


return $theme_name_homepage_content;

Note that the string is returned on the final line. If you omit the return statement, no content will be imported during Onboarding and your pages will be blank.

Your raw page content should be copied from the code editor. The code editor is accessible from the menu in the top-right of the block editor:

The menu from the block editor showing how to access the code editor mode.

The opening <<<CONTENT and closing CONTENT; string delimiters in the homepage.php code snippet are a PHP feature called the heredoc syntax.

The heredoc syntax is an alternative to wrapping multi-line strings with quote marks. It prevents you from having to escape single or double quotes within your string. PHP will also process internal variables such as $my_var or {$my_array['key']}.

You can replace the CONTENT identifier with your own delimiter if you wish, as long as you use the same for the starting and ending one. The line with the ending CONTENT; delimiter must contain no other characters aside from the identifier and the semicolon, and no white space at the start of the line.

Each page or post you create can import the same sample content, or you can create a separate file with different content for each page, then update the post_content value for each imported page to point to that file.

To test the onboarding process

  1. Activate another theme from the Appearance → Themes page.
  2. Activate your theme. You should be redirected to the onboarding page.
  3. Click “Set up your homepage” and wait for the setup steps to complete.
  4. Click “View your homepage” or “Edit your homepage” to see the imported homepage content.

You can repeat the Onboarding process by leaving your theme active and visiting /wp-admin/admin.php?page=genesis-getting-started instead of deactivating and reactivating your theme. Note that new pages will be created each time. Pages are not deleted or overwritten during Onboarding.

Points to note

The Onboarding feature is new and will continue to improve, but there are some things to be aware of at present.

  1. Onboarding requires WordPress 5.0.0+ and Genesis 2.9.0+. The onboarding config file has no effect if both of these requirements are not met.
  2. Widgets and media cannot yet be imported.
  3. The redirect to the onboarding page occurs when themes are activated via the Appearance → Themes screen only. A redirect will not occur when activating themes via the Customizer or WP-CLI. You are welcome to direct people to /wp-admin/admin.php?page=genesis-getting-started to complete the theme onboarding process in your support documentation or elsewhere. Running the setup process multiple times will create additional pages, but is otherwise not destructive.
  4. The text used on the onboarding admin screen is not currently filterable, including the “Create your new homepage” title. We expect to add the ability to change this via your config file in the future.
  5. Only plugins from the WordPress.org plugins repository are currently supported as dependencies.
  6. Be aware that Blocks displaying posts can not be guaranteed to display in the same way as your demo content. It's not safe to assume that all of a site's posts have featured images set, for example, or that a site contains any posts at all.

If you need to use images in your imported page content, for now you can use this workaround from the Genesis Sample theme where demo images are stored in the child theme folder and linked directly in the imported content.

We encourage you to experiment with Onboarding, and we welcome your feedback.