Skip to content

Genesis Developer Docs

Import Widgets During Genesis Theme Setup

Requires Genesis 3.1.0+ and WordPress 5.0.0+

One-click theme setup

Import widgets

Import any widget using a config/onboarding.php file like this:

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

return [
// Full config omitted for this example.
'dependencies' => [],
'content' => [],
'navigation_menus' => [],
'widgets' => [
'footer-1' => [
[
'type' => 'featured-post',
'args' => [
'title' => 'Featured Posts Example',
'posts_cat' => '0',
'posts_num' => 3,
'posts_offset' => '0',
'orderby' => 'date',
'order' => 'DESC',
'gravatar_size' => '45',
'gravatar_alignment' => 'alignnone',
'image_size' => 'thumbnail',
'image_alignment' => 'alignnone',
'show_title' => '1',
'show_byline' => '1',
'post_info' => '[post_date] By [post_author_posts_link] [post_comments]',
'show_content' => 'excerpt',
'content_limit' => '0',
'more_text' => '[Read More...]',
'extra_title' => '',
'extra_num' => '',
'more_from_category_text' => 'More Posts from this Category',
],
],
],
'footer-2' => [
[
'type' => 'featured-listings',
'args' => [
'title' => 'Featured Listings Example',
'posts_per_page' => '5',
],
],
],
'footer-3' => [
[
'type' => 'enews-ext',
'args' => [
'title' => 'eNews Extended Example',
'action' => '#',
'email-field' => '#',
'input_text' => 'Enter Email Address ...',
'button_text' => 'Subscribe',
],
],
],
],
];

The footer-n keys denote the widget area to import widgets into, as defined by Genesis or your theme.

You can import multiple widgets into a single widget area:

'footer-1' => [
// The first text widget.
[
'type' => 'text',
'args' => [
'title' => 'Text widget 1',
'text' => '<p>With an emphasis on typography, white space, and mobile-optimized design, your website will look absolutely breathtaking.</p><p><a href="#">Learn more about design</a>.</p>',
'filter' => 1,
'visual' => 1,
],
],
// The second text widget.
[
'type' => 'text',
'args' => [
'title' => 'Text widget 2',
'text' => '<p>Our team will teach you the art of writing audience-focused content that will help you achieve the success you truly deserve.</p><p><a href="#">Learn more about content</a>.</p>',
'filter' => 1,
'visual' => 1,
],
],
],

WordPress stores widget config as serialized arrays in the wp_options table.

You can retrieve fields you need to use for each widget type via WP-CLI:

> wp option get widget_text
> wp option get widget_enews-extended
> wp option get widget_featured-post

These commands reveal widget properties you can import:

> wp option get widget_featured-post
…
array (
    'title' => 'Fashion',
    'posts_num' => '2',
    'posts_offset' => '1',
    'orderby' => 'ID',
    'show_image' => 1,
    'image_size' => 'sidebar-thumbnail',
    'image_alignment' => 'alignleft',
    'show_title' => 1,
    'show_byline' => 1,
    'post_info' => '[post_date] By [post_author_posts_link]',
    'show_content' => '',
  ),
…

You can alternatively inspect widget data using an SQL client by browsing the wp_options table and viewing the widget_ rows. Or browse the widget source code and find the default properties in the class constructor:

// wp-content/themes/genesis/lib/widgets/featured-post-widget.php.
$this->defaults = [
'title' => '',
'posts_cat' => '',
'posts_num' => '',
'posts_offset' => 0,
'orderby' => '',
'order' => '',
'exclude_displayed' => 0,
'exclude_sticky' => 0,
'show_image' => 0,
'image_alignment' => '',
'image_size' => '',
'show_gravatar' => 0,
'gravatar_alignment' => '',
'gravatar_size' => '',
'show_title' => 0,
'show_byline' => 0,
'post_info' => '[post_date] ' . __( 'By', 'genesis' ) . ' [post_author_posts_link] [post_comments]',
'show_content' => 'excerpt',
'content_limit' => '',
'more_text' => __( '[Read More...]', 'genesis' ),
'extra_num' => '',
'extra_title' => '',
'more_from_category' => '',
'more_from_category_text' => __( 'More Posts from this Category', 'genesis' ),
];

You only need to specify widget properties if they differ from defaults for that widget.

Use imported page IDs as widget properties

Genesis imports content from your onboarding.php file before importing widgets. Content you import during theme setup is assigned a page ID by WordPress.

You can access imported content IDs in widget properties with the $imported_posts_[page_key] placeholder. For example, if you import an about page in your onboarding.php content array like this:

// Excerpt from child-theme/config/onboarding.php.
'content' => [
'about' => [
'post_title' => 'About Us',
'post_content' => require dirname( __FILE__ ) . '/import/content/about.php',
'post_type' => 'page',
'post_status' => 'publish',
'featured_image' => get_stylesheet_directory_uri() . '/config/import/images/about.jpg',
'comment_status' => 'closed',
'ping_status' => 'closed',
],
],

You can use this about page in a Featured Page widget like this:

// Excerpt from child-theme/config/onboarding.php.
'widgets' => [
'footer-1' => [
[
'type' => 'featured-page',
'args' => [
'title' => '',
'page_id' => '$imported_posts_about', // <-- Use the ID of the imported about page.
'show_image' => 1,
'image_size' => 'featured-image',
'image_alignment' => 'aligncenter',
'show_title' => 1,
'content_limit' => '',
'more_text' => '',
],
],
],
],

Genesis will replace $imported_posts_about with the page ID of the imported about page when creating this featured-page widget. Replace about with other content keys to use the ID of different imported pages, such as $imported_posts_contact.