Twenty Seventeen: Introduce a theme-specific filter twentyseventeen_starter_content for customizing the starter content array.

Add some documentation to the default starter content.

Merge of [39720] to the 4.7 branch.

Props sanket.parmar, celloexpressions.
See #39109.

git-svn-id: https://develop.svn.wordpress.org/branches/4.7@39721 602fd350-edb4-49c9-b593-d223f7449a82

src/wp-content/themes/twentyseventeen/functions.php

@@ -106,24 +106,29 @@ function twentyseventeen_setup() {
  	 */
 	add_editor_style( array( 'assets/css/editor-style.css', twentyseventeen_fonts_url() ) );
 
-	add_theme_support( 'starter-content', array(
+	// Define and register starter content to showcase the theme on new sites.
+	$starter_content = array(
 		'widgets' => array(
+			// Place three core-defined widgets in the sidebar area.
 			'sidebar-1' => array(
 				'text_business_info',
 				'search',
 				'text_about',
 			),
 
+			// Add the core-defined business info widget to the footer 1 area.
 			'sidebar-2' => array(
 				'text_business_info',
 			),
 
+			// Put two core-defined widgets in the footer 2 area.
 			'sidebar-3' => array(
 				'text_about',
 				'search',
 			),
 		),
 
+		// Specify the core-defined pages to create and add custom thumbnails to some of them.
 		'posts' => array(
 			'home',
 			'about' => array(
@@ -140,10 +145,11 @@ function twentyseventeen_setup() {
 			),
 		),
 
+		// Create the custom image attachments used as post thumbnails for pages.
 		'attachments' => array(
 			'image-espresso' => array(
 				'post_title' => _x( 'Espresso', 'Theme starter content', 'twentyseventeen' ),
-				'file' => 'assets/images/espresso.jpg',
+				'file' => 'assets/images/espresso.jpg', // URL relative to the template directory.
 			),
 			'image-sandwich' => array(
 				'post_title' => _x( 'Sandwich', 'Theme starter content', 'twentyseventeen' ),
@@ -155,12 +161,14 @@ function twentyseventeen_setup() {
 			),
 		),
 
+		// 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(
 			'panel_1' => '{{homepage-section}}',
 			'panel_2' => '{{about}}',
@@ -168,16 +176,20 @@ function twentyseventeen_setup() {
 			'panel_4' => '{{contact}}',
 		),
 
+		// Set up nav menus for each of the two areas registered in the theme.
 		'nav_menus' => array(
+			// Assign a menu to the "top" location.
 			'top' => array(
 				'name' => __( 'Top Menu', 'twentyseventeen' ),
 				'items' => array(
-					'link_home',
+					'link_home', // Note that the core "home" page is actually a link in case a static front page is not used.
 					'page_about',
 					'page_blog',
 					'page_contact',
 				),
 			),
+
+			// Assign a menu to the "social" location.
 			'social' => array(
 				'name' => __( 'Social Links Menu', 'twentyseventeen' ),
 				'items' => array(
@@ -189,7 +201,18 @@ function twentyseventeen_setup() {
 				),
 			),
 		),
-	) );
+	);
+
+	/**
+	 * Filters Twenty Seventeen array of starter content.
+	 *
+	 * @since Twenty Seventeen 1.1
+	 *
+	 * @param array $starter_content Array of starter content.
+	 */
+	$starter_content = apply_filters( 'twentyseventeen_starter_content', $starter_content );
+
+	add_theme_support( 'starter-content', $starter_content );
 }
 add_action( 'after_setup_theme', 'twentyseventeen_setup' );