Make WordPress Core

Updates from Helen Hou-Sandi Toggle Comment Threads | Keyboard Shortcuts

  • Helen Hou-Sandi 8:49 pm on November 30, 2016 Permalink |
    Tags: ,   

    Starter content for themes in 4.7 

    One of the hardest things for people setting up sites with WordPress for the first time is understanding what themes are and how a given theme can work for you, especially when there’s no content there to visualize. There are also significant gaps between local theme previews, screenshots, and .org previews. Even when there are easy-to-use site customization tools, it is difficult to figure out where to start and what things are going to be like.

    To help users along that path, 4.7 introduces the concept of “starter content” – theme-specific selections of content to help showcase a theme to users and serve as a starting point for further setup of new sites. Starter content works especially well in tandem with visible edit shortcuts, allowing users to not only see what content might work best where within a theme, but from there to be able to jump to building off of that base without having to initially spend time figuring out, say, which widgets areas map where.

    How it works

    Starter content is applied and displayed upon entering the customizer, with no changes appearing on the live site until customizer changes are explicitly saved and published. In 4.7, this initial view of a theme with starter content will only happen for “fresh sites” – new installs that have not yet had any posts, pages, widgets, or customizer settings updated. This state is indicated in the fresh_site option with a value of 1. The current limitation is in line with prioritizing initial site setup for this release, and allows for themes to begin implementing content and ensuring that there is a solid base before introducing more complicated logic and UI to “merge” starter content with existing content in a future release (#38624). That being said, if two themes in a given fresh site both have starter content, if the starter content from the first theme is applied and you make some changes to that starter content, when you switch to the second theme the starter content from that theme will override the starter content from the first theme only for the settings which have not been modified. Also remember that theme mods are always theme-specific, so starter content for theme switches will never be copied.

    Core provides a set of content that themes can select from (technical details below). These include a variety of widgets, pages, and nav menu items (including references for the pages), along with the ability to provide attachments, theme mods, and options. Any included images for attachments need to be from within a theme or plugin folder and cannot be loaded from an external URL. Twenty Seventeen will ship with starter content enabled; there are no plans to add the functionality to past default themes.

    How to use it

    Themes define a subset of core-provided starter content using add_theme_support() – let’s look at a breakdown of how Twenty Seventeen does things. In its setup function hooked to after_setup_theme, we see an array with collections of widgets, posts (pages), attachments, options, theme mods, and nav menus registered as the starter content. The customizer looks for this starter-content at after_setup_theme priority 100, so do make this call at that point or later:

    add_theme_support( 'starter-content', array( /*...*/ ) )


    Each widget area ID corresponds to one sidebar registered by the theme, with the contents of each widget area array being a list of widget “symbols” that reference core-registered widget configurations. Most default widgets are available (archives, calendar, categories, meta, recent-comments, recent-posts, and search), as well as text widgets with business hours (text_business_info) and a short prompt for an “about this site” style blurb (text_about). Themes should place widgets based on what works best in that area – for instance, business info in a footer widget of a business-centric theme, or a nicely styled calendar widget in the sidebar of a blog.

    Custom widgets can also be registered at the time of starter content registration or later filtered in, which will be more likely the case for plugins, as add_theme_support() for starter content will be overridden by any later calls.

    // Custom registration example
    add_theme_support( 'starter-content', array(
    	'widgets' => array(
    		'sidebar-1' => array(
    			'meta_custom' => array( 'meta', array(
    				'title' => 'Pre-hydrated meta widget.',
    			) ),
    // Plugin widget added using filters
    function myprefix_starter_content_add_widget( $content, $config ) {
    	if ( isset( $content['widgets']['sidebar-1'] ) ) {
    		$content['widgets']['sidebar-1']['a_custom_widget'] = array(
    			'my_custom_widget', array(
    				'title' => 'A Special Plugin Widget',
    	return $content;
    add_filter( 'get_theme_starter_content', 'myprefix_starter_content_add_widget', 10, 2 );

    Posts (Pages)

    Like widgets, core provides posts which can be referenced by symbols; all six currently in the core set are pages, but the starter content API can support various post types (including attachments, which are defined and handled separately). The symbols for the core-provided pages as of 4.7 are home, about, contact, blog, news, and homepage-section. The pages references by blog and news are both empty in the content area and are meant to be assigned as the page for posts (detailed with options below). Imported posts can further be used as post IDs when referenced using the symbol of the item within double curly braces, e.g. {{home}} for the static front page option.

    Posts, like widgets, are also easily customizable, either by overriding specific fields for a predefined item or by defining a new custom one entirely. The available fields are post_type, post_title, post_excerpt, post_name (slug), post_content, menu_order, comment_status, thumbnail (featured image ID), and template (page template name, as would be stored in post meta).

    // Overriding/supplementing a predefined item plus a custom definition
    add_theme_support( 'starter-content', array(
    	'posts' => array(
    		'about' => array(
    			// Use a page template with the predefined about page
    			'template' => 'sample-page-template.php',
    		'custom' => array(
    			'post_type' => 'post',
    			'post_title' => 'Custom Post',
    			'thumbnail' => '{{featured-image-logo}}',


    While attachments are post objects, they have special handling due to the sideloading of specified media. Media must be loaded from within the theme or plugin directory – external URLs are currently disallowed for performance reasons. The location of the media, either as a full file path or relative to the theme root, is indicated in the file array item, and some other post fields are available, with post_content mapping to description and post_excerpt to caption. Imported attachments can further be used by using their respective array keys as symbols used within double curly braces, e.g. {{featured-image-logo}} as the featured image (thumbnail) for a post. In the example below, an attachment is specified and used as the featured image for the about page.

    add_theme_support( 'starter-content', array(
    	'attachments' => array(
    		'featured-image-logo' => array(
    			'post_title' => 'Featured Logo',
    			'post_content' => 'Attachment Description',
    			'post_excerpt' => 'Attachment Caption',
    			'file' => 'assets/images/featured-logo.jpg',
    	'posts' => array(
    		'about' => array(
    			// Use the above featured image with the predefined about page
    			'thumbnail' => '{{featured-image-logo}}',

    Nav Menus

    Nav menus are also specially treated post objects. There are essentially two types of nav menu items – custom links, which require a title and url, and object references, which require type, object, and object_id, which can be a {{post}} symbolic reference.

    Options and Theme Mods

    Options and theme mods are more freeform and merely require a match for a name. Symbolic references to imported items are particularly useful here, such as for the page_on_front option and Twenty Seventeen’s multi-section homepage as stored in theme mods. Themes hosted on .org will likely be limited to theme mods and a subset of options; all other developers are encouraged to consider user experience and expectations first.

    What does this mean for themes?

    Core-provided content helps support a consistent preview experience across themes with high quality localized content, helping users understand how WordPress and that theme fit their needs. Theme authors are encouraged to select from core-provided content, but as is always the case with WordPress, starter content still has some flexibility, and will continue to mature as a feature over time.

    While theme review guidelines need to be finalized and documented, it is anticipated that themes being submitted to WordPress.org will be expected to select from core-provided content to promote consistency and to help keep the theme review process from becoming lengthier, with exceptions being made on a case by case basis. Themes being distributed outside of WordPress.org are not subject to the same review process; however, it is recommended that consistent user experiences be the primary consideration in how starter content is chosen and implemented.

    What’s next?

    Testing this feature with your theme or plugin does not require a fresh install every time – you can set the fresh_site option to 1 using the tool of your choice, such as wp-cli or phpMyAdmin. Do note that content merging logic has not been tackled so you may not quite get the exact same effect as a truly fresh install; however, since all of the changes are held in a customizer changeset and are not otherwise live on the site, there is no data loss, unless you save and publish the starter content overrides of course.

    In the future, all sites should be able to live preview new themes in ways that really showcase that theme’s capabilities, whether that’s with no content made yet or with a lot of existing content to work into the preview. This will take a lot of consideration around user expectations for content merging, and should be tackled as its own feature. There are also potentially interesting extensions such as UI for users to select from sets of content or selectively accept/reject staged changes.

    And finally, to best align preview experiences in various places, theme previews on .org should also leverage starter content. Helping hands are needed here – please ping me (@helen) in Slack should you be interested!

    • Luke Cavanagh 8:55 pm on November 30, 2016 Permalink | Log in to Reply

      Thanks for sharing.

    • Madalin Tache 9:05 pm on November 30, 2016 Permalink | Log in to Reply

      That’s a really good idea! Looking forward to it!:)

    • Hardeep Asrani 9:08 pm on November 30, 2016 Permalink | Log in to Reply

      That’s gonna be a game changer for themes. 🙂

    • t-p 11:39 pm on November 30, 2016 Permalink | Log in to Reply

      To be able to live preview new themes sounds awesome 🙂

    • WPDevHQ 11:40 pm on November 30, 2016 Permalink | Log in to Reply

      Awesome news for themes.

      Will this be carried over to WordPress.org theme preview or does that not work as a `fresh_site`?

    • Omaar Osmaan 11:57 pm on November 30, 2016 Permalink | Log in to Reply

      Awesome thank you!

    • evisiontheme 9:21 am on December 1, 2016 Permalink | Log in to Reply

      Really, great idea. Thanks for the sharing it. We look forward it soon.

    • NateWr 9:39 am on December 1, 2016 Permalink | Log in to Reply

      Looks great! I suppose this has been discussed, but is there any plan to support post meta in a more generic fashion? I’m thinking a key for `post_meta` which can itself be an assoc array with a key/value map. This could be useful for previewing data from plugin custom post types which rely more heavily on post meta.

      • Helen Hou-Sandi 3:16 pm on December 1, 2016 Permalink | Log in to Reply

        Untested at the moment, but I believe this is already technically possible, just requires some more hoop jumping at the moment in the form of having to filter it in using get_theme_starter_content as opposed to being able to specify it during initial registration. That is the case for plugins as it is though, so it’s not really that much of a hoop. So to do that, you would want to use a meta_input arg with the definition of that post, the same way post_title can be specified. Can you let me know if it works?

    • Mahesh Waghmare 9:51 am on December 1, 2016 Permalink | Log in to Reply

      +1, Its nice enhancement for theme developer.

    • Ahmad Awais 2:57 pm on December 1, 2016 Permalink | Log in to Reply

      Thanks a lot Helen and all the contributors for making this happen. It’s a huge deal for me and my clients.

  • Helen Hou-Sandi 7:02 pm on November 16, 2016 Permalink |
    Tags: , ,   

    Dev Chat Agenda for November 16 (4.7 week 13) 

    This is the agenda for the weekly dev meeting on November 16, 2016 at 21:00 UTC:

    • Meeting reminder: Weekly chat has been moved one hour later to 21:00UTC.
    • Schedule reminder: Tomorrow is the target for RC! RC means the list of tickets should be at zero (with the exception of the about page), as a release candidate is supposed to represent software you believe you can release. It is currently at 24.
    • Ticket reminder: For any tickets you’ve moved into the milestone, please get these resolved in the next day.
    • Dev notes:  These should all be published this week, with a collective field guide forthcoming from @aaronjorbin.
    • Getting ready for RC with a 4.7 open ticket scrub

    If you have anything to propose to add to the agenda or specific items related to the above, please leave a comment below. See you there!

  • Helen Hou-Sandi 4:01 am on November 11, 2016 Permalink |

    4.7 beta and RC plans 

    To push us to get tickets resolved and take advantage of some shifting in my own schedule, I’d like to propose that we work quickly toward a beta 4 on Monday (November 14) and move RC back from Tuesday to Thursday (November 17). There are still 31 tickets open; I would like to get to 15 or below by beta 4, and the only one that should be open when we get to RC is the one for the about page. Be on the lookout for ad hoc scrubs and pings over the next week 🙂

    As a reminder, a release candidate should represent the software that we believe will ship, with any commits coming during the RC period being limited to regressions and serious bug fixes in new features. 4.7 will be branched off once we get to RC, at which time guest committers may continue to commit to trunk, but any merges back to the 4.7 branch must be done by a permanent committer with the additional review of another permanent committer (which includes lead developers).

  • Helen Hou-Sandi 7:40 pm on October 19, 2016 Permalink |
    Tags: , ,   

    Dev Chat Agenda for October 19 (4.7 week 9) 

    This is the agenda for the weekly dev meeting on October 19, 2016 at 20:00 UTC:

    If you have anything to propose to add to the agenda or specific items related to the above, please leave a comment below. See you there!

  • Helen Hou-Sandi 8:01 pm on October 12, 2016 Permalink |
    Tags: , ,   

    Dev Chat Agenda for October 12 (4.7 week 8) 

    This is the agenda for the weekly dev meeting on October 12, 2016 at 20:00 UTC:

    If you have anything to propose to add to the agenda or specific items related to the above, please leave a comment below. See you there!

  • Helen Hou-Sandi 5:58 pm on October 11, 2016 Permalink |
    Tags: ,   

    The Road to 4.7 Beta 1 

    For the last 55 days, trunk has been in an alpha state and open for all commits. In 15 days this will change and the first beta for 4.7 will be released. During beta, no new enhancements or feature requests should be committed to WordPress core. While some may desire to wait for just one more thing, that is a rabbit hole which is inconsistent with the WordPress philosophies. Here is a list of things that need to happen during the next 15 days in order to get ready for Beta 1 on October 26th.

    The deadline for merging feature projects into WordPress core is in 8 days. There are currently three proposals for projects to merge published with several additional proposals actively being worked on. All committers and active contributors should review these proposals (I’ll add links to additional proposals when they are made):

    There are 60 enhancements and feature requests milestoned for 4.7.  Of these, 21 have no owner.  At the end of this week, all enhancements and feature requests without an owner will be punted.  Tickets will also be regularly evaluated this week.  Over the next two weeks, tickets will be evaluated during both scheduled and unscheduled bug scrubs, and tickets not moving forward will be removed from the milestone. The next scheduled bug scrub will be at Wednesday, October 12, 2016 17:00 UTC.

    During this week’s dev chat, we will discuss all the proposals that have been made thus far. If additional meetings for considering any of the proposals before the merge deadline are needed, this will be decided then.

  • Helen Hou-Sandi 6:12 pm on October 5, 2016 Permalink |
    Tags: , ,   

    Dev Chat Agenda for October 5 (4.7 week 7) 

    This is the agenda for the weekly dev meeting on October 5, 2016 at 20:00 UTC:

    If you have anything to propose to add to the agenda or specific items related to the above, please leave a comment below. See you there!

  • Helen Hou-Sandi 7:04 pm on September 28, 2016 Permalink |
    Tags: , ,   

    Dev Chat Agenda for September 28 (4.7 week 6) 

    This is the agenda for the weekly dev meeting on September 28, 2016 at 20:00 UTC:

    If you have anything to propose to add to the agenda or specific items related to the above, please leave a comment below. See you there!

  • Helen Hou-Sandi 5:25 pm on September 14, 2016 Permalink |
    Tags: , ,   

    Dev Chat Agenda for September 14 (4.7 week 4) 

    This is the agenda for the weekly dev meeting on September 14, 2016 at 20:00 UTC:

    If you have anything to propose to add to the agenda or specific items related to the above, please leave a comment below. See you there!

    • Pascal Birchler 6:11 pm on September 14, 2016 Permalink | Log in to Reply

      I might not be able to attend today’s dev chat, so here’s an update on i18n:

      #29783 (User Admin Language): in good shape, but not much testing happening so far. We could do much more when #26511 is in core though…

      #26511 (`switch_to_locale()`): needs some much needed performance testing. If anyone runs a large WordPress site, I could use your help!
      Also since there are some similarities with `switch_to_blog()`, I’ll open a new ticket to suggest adding a `WP_State` interface for such switching functions. Think `WP_Site_State`, `WP_Locale_State`, `WP_Post_State` (see #19572), etc. Not a blocker, but worth keeping in mind for future compatibility.

      #20491 (JS i18n): I documented the current state in the tasks with responsibilities etc. As of tomorrow I’ll have more time to work on it (mainly on the GlotPress side of things). Also have been thinking about a `switch_to_locale()` function in JS via Ajax…

    • Ronald Huereca 6:24 pm on September 14, 2016 Permalink | Log in to Reply

      I’d like https://core.trac.wordpress.org/ticket/38024 discussed as I believe it to be a fairly major bug in regard to automatic updates for plugins and themes.

  • Helen Hou-Sandi 3:03 pm on September 9, 2016 Permalink |
    Tags: , ,   

    Say Hello to Twenty Seventeen 👋🏽 

    It’s that time again: time to build a new default theme for WordPress!

    WordPress 4.7 will launch with a brand new theme – Twenty Seventeen. Designed by Mel Choyce (@melchoyce), Twenty Seventeen sports a modern look and will make a good base for any business website or product showcase.


    Check out the gallery below to preview our next default theme at full-size:

    (Higher resolution mockups)

    In addition to having a wide appeal, Twenty Seventeen will focus on providing a seamless initial theme setup so anyone can set up a website for themselves or their business with minimal hassle.

    Twenty Seventeen aims to show off some new core features and enhancements, such as:

    • A better flow for using a static page as your front page.
    • Visible edit icons in the Customizer, replacing the current hidden shift+click method.
    • Expanding custom header images to include video (think: atmospheric video headers!).
    • Dummy content for live previews.

    Mel will keep an eye on all things design during the creation of Twenty Seventeen. Laurel Fulford (@laurelfulford) and David Kennedy (@davidakennedy) will assist her, leading the theme’s development. Lots of opportunities exist this year for getting involved with Twenty Seventeen – we need your help, and lots of it! 🙏🏽

    Backing up the Twenty Seventeen team will be a team focusing on the core Themes API. This team is looking for new and experienced core developers with theme experience to help lead and contribute to specific features.

    Similar to feature projects, the initial development of the theme will be on GitHub. Once it’s usable and stable, the theme will be merged into core and the GitHub repo will be deprecated. After it’s merged, all issues should be reported to Trac.

    Twenty Seventeen will also use plain CSS — it won’t use preprocessors in the development of the theme. This will keep it simple, making the theme easier for everyone to understand, quicker for anyone to modify and better to maintain in the long run.

    Throughout the process of building Twenty Seventeen, the team will be collaborating with the Theme Review Team and the core development team to make sure it is up to core standards.

    How can you get involved?

    There will be weekly meetings every Friday at 18:00 UTC in #core-themes starting today. During that time, the focus will be on the theme itself. If you are interested in contributing, keep an eye out here for updates or join us in #core-themes in Slack.

    If you have some early thoughts on what would make this a great WordPress experience, or if you’re generally interested in participating, sound off in the comments. Please hold any design feedback for Friday’s meeting. where we can have a conversation about it in greater depth.

    Want to know more about default themes?

    Here are some links where you can find out more about past default themes:

compose new post
next post/next comment
previous post/previous comment
show/hide comments
go to top
go to login
show/hide help
shift + esc
Skip to toolbar