WordPress.org

Make WordPress Core

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

  • Helen Hou-Sandi 6:26 am on December 3, 2016 Permalink |
    Tags:   

    There is a quiet RC2 now available – it is a fair number of commits (50+), so please take a look through those and test as you can.

     
  • 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( /*...*/ ) )

    Widgets

    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}}',
    		),
    	),
    );
    

    Attachments

    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?

        • NateWr 9:06 pm on December 6, 2016 Permalink | Log in to Reply

          Hey thanks Helen. I missed this reply in my notifications so just seeing it now. I’ll try to give this a go in the next couple weeks and let you know.

    • 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.

    • rheinardkorf 11:15 pm on December 5, 2016 Permalink | Log in to Reply

      Love it! Handy for developers and those looking for themes. Nothing more annoying than previewing a theme with current standard content. Great improvement.

    • Armando Duran 12:46 am on December 7, 2016 Permalink | Log in to Reply

      I tried this on an existing install. For a moment I thought that the fresh_site option would be there after upgrading to 4.7 but then I realized that after adding the option manually on the DB, starter content was there!

      love this feature … and the new 4.7 version of course!

    • Volkv 9:50 am on December 7, 2016 Permalink | Log in to Reply

      But it doesnt work right for me. After fresh 4.7 install I got 20/17 theme loaded WITHOUT any starter pre-loaded content – only with default widgets. Starter changes appears ONLY after I click on customizer button.

      Same behavior with my own theme. Is it bug or what am I doing wrong?

      • WebMan Design | Oliver Juhas 9:23 am on December 20, 2016 Permalink | Log in to Reply

        This is actually intentional. Starter content is present in theme customizer only to preview how the theme looks/works with a content in place. Once you save the customizer settings the starter content should by ported into your website and you should actually see it in your pages/posts, widgets,…

    • Mal 11:06 am on December 7, 2016 Permalink | Log in to Reply

      It doesn’t work for me.

      I just installed WordPress 4.7 and put this in the functions.php file:

      
      function my_setup() {
      	add_theme_support( 'starter-content', array(
      		'options' => array(
      			'test123' => 'test',
      		),
      	) );
      }
      add_action( 'after_setup_theme', 'my_setup' );
      

      The frest_site option was added to the database automatically with value of 1.

      In footer.php when I run var_dump(get_theme_starter_content()); I get the correct result but when I run var_dump(get_option('test123')); right next to it I’m only getting false.

      I tried to debug that but I can’t figure out what this is supposed to do preg_match( '/^{{(?P.+)}}$/', $value, $matches ) in import_theme_starter_content()?

      I also noticed that all arrays need to be serialized which was kind of unexpected:

      
      add_theme_support( 'starter-content', array(
      	'options' => array(
      		'test123' => 'test',
      		'test1234' => maybe_serialize( array(
      			'something' => 'test',
      		) ),
      	),
      ) );
      
    • WebMan Design | Oliver Juhas 11:14 am on December 18, 2016 Permalink | Log in to Reply

      Hi,

      This is a great feature, thank you! I have successfully tested it with standard one-site WordPress installation. But for some reason it does not work for me on WordPress multisite. So, my question is:

      Does themes starter content work with WordPress network (a multisite) installation?

      Thanks for the answer in advance!

  • 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 |
    Tags:   

    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.

c
compose new post
j
next post/next comment
k
previous post/previous comment
r
reply
e
edit
o
show/hide comments
t
go to top
l
go to login
h
show/hide help
shift + esc
cancel
Skip to toolbar