Introduced with WordPress 4.7, starter content allows you to define a default content (such as widgets, customizer settings, menus and pages) which will be displayed when user opens Customizer (Admin Panel -> Left Menu -> Appearance -> Customize) of a newly installed WP sites.
It useful to be defined for WP themes which are designed to be distrited or sell. If you build a WordPress Theme for a client project, you probably don’t need to define such content.
Available Only on Fresh WP Installation
As mention above thye starter content is available for fresh (newly installed sites), it means the starter content won’t be loaded if you have already publish pages or posts in your website.
How to Define a Starter Content for Your Theme
Let’s look at the following example (the starter content we use for our fGreen theme):
function fgreen_setup() {
// Define and register starter content to showcase the theme on new sites.
$starter_content = array(
'widgets' => array(
'sidebar-widget-area' => array(
'search',
'recent-posts',
'categories',
'archives',
),
'homepage-column-1-widget-area' => array(
'text_business_info'
),
'homepage-column-2-widget-area' => array(
'text_about'
),
'homepage-column-3-widget-area' => array(
'meta'
),
'footer-column-1-widget-area' => array(
'recent-comments'
),
'footer-column-2-widget-area' => array(
'recent-posts'
),
'footer-column-3-widget-area' => array(
'calendar'
),
),
'posts' => array(
'home',
'blog',
'about',
'contact'
),
// Create the custom image attachments used as slides
'attachments' => array(
'image-slide-1' => array(
'post_title' => _x( 'Slider Image 1', 'Theme starter content', 'fgreen' ),
'file' => 'images/slides/1.jpg', // URL relative to the template directory.
),
'image-slide-2' => array(
'post_title' => _x( 'Slider Image 2', 'Theme starter content', 'fgreen' ),
'file' => 'images/slides/2.jpg', // URL relative to the template directory.
),
'image-slide-3' => array(
'post_title' => _x( 'Slider Image 3', 'Theme starter content', 'fgreen' ),
'file' => 'images/slides/3.jpg', // URL relative to the template directory.
),
),
// Default to a static front page and assign the front and posts pages.
'options' => array(
'show_on_front' => 'page',
'page_on_front' => '{{home}}',
'page_for_posts' => '{{blog}}',
),
// Set the front page section theme mods to the IDs of the core-registered pages.
'theme_mods' => array(
'fgreen_slider_display' => 1,
'fgreen_slide1_image' => '{{image-slider-1}}',
'fgreen_slide1_content' => _x( '<h2>Lorem ipsum dolor sit amet</h2><p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p><a href="#" class="btn">Read more</a>', 'Theme starter content', 'fgreen' ),
'fgreen_slide2_image' => '{{image-slider-2}}',
'fgreen_slide2_content' => _x( '<h2>Lorem ipsum dolor sit amet</h2><p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p><a href="#" class="btn">Read more</a>', 'Theme starter content', 'fgreen' ),
'fgreen_slide3_image' => '{{image-slider-3}}',
'fgreen_slide3_content' => _x( '<h2>Lorem ipsum dolor sit amet</h2><p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p><a href="#" class="btn">Read more</a>', 'Theme starter content', 'fgreen' ),
),
'nav_menus' => array(
// Assign a menu to the "primary" location.
'primary' => array(
'name' => __( 'Primary Menu', 'fgreen' ),
'items' => array(
'link_home',
'page_blog',
'page_contact',
'page_about',
),
),
// Assign a menu to the "footer" location.
'footer' => array(
'name' => __( 'Footer Menu', 'fgreen' ),
'items' => array(
'link_home',
'page_about',
'page_blog',
'page_contact',
),
),
),
);
$starter_content = apply_filters( 'fgreen_starter_content', $starter_content );
add_theme_support( 'starter-content', $starter_content );
}
add_action( 'after_setup_theme', 'fgreen_setup' );Let’s look each of the parts:
The content is defined into after_setup_theme hook, we add ‘starter-content’ support as well.
Widgets: they are defined as an array, for each widget area ID (i.e. homepage-column-1-widget-area), we define widgets to be loaded. We can choose between:
- ‘text_business_info’
- ‘text_about’
- ‘archives’
- ‘calendar’
- ‘categories’
- ‘meta’
- ‘recent-comments’
- ‘recent-posts’
- ‘search’
These are the only widgets we can add as starter content.
We can add pages (added into ‘posts’ array. There default pages we can use (‘home’, ‘about’, ‘contact’, ‘blog’, ‘news’), or we can define custom as well.
The ‘attachments’ allows us to define media images. In the example above, we define images which we use as default Slide images. The path we define is relative to theme directory.
Using the ‘options’ we can define for example a Static Front Page display. It’s useful if you have a functionality displayed only on a Static Front page and you want to present that case i.e. a Homepage Slider available on that page.
Other useful functionality is ‘theme_mods’. It allows you to set Customizer options values set as a starter content, i.e. with setting fgreen_slider_display = 1, we define that Slider should be displayed into the Customizer example content.
The ‘nav_menus’ allows you to define menu elements for your theme menus. In the example above, we define pages for theme two menus it has ‘primary’ and ‘footer’.
Conclusion
In general, it’s a great idea as a theme developer to be able to define a starter content. But unfortunately, it’s very limited: it’s available only for fresh WordPress installations. Let’s how it will be improved in the next years 🙂
References
Here are useful links you could check for more info: