Twenty Seventeen: starter content array needs a filter

[celloexpressions]

There currently seems to be no way to extend the starter content provided in Twenty Seventeen in a child theme. I'd suggest applying a filter to the starter content array so that child themes (or plugins) can selectively add or remove items as they see fit without having to duplicate the entire array. This should also become a best practice for all themes.

While we're at it, there are no inline comments whatsoever around Twenty Seventeen's starter content registration. Since this is the only canonical complete implementation initially available, we should add some inline documentation to explain how the starter content array works.

Calling add_theme_support( 'starter-content', array( ... in a child theme seems to prevent starter content from working at all since the theme's starter content is registered already. The workaround would probably require removing theme support then adding it and duplicating the entire array until the filter is in place.

[helen]

Noting that it runs after translation/expansion of starter content, is there a reason why get_theme_starter_content doesn't work as a hook? We could also look at adding a hook pre-expansion, or something inside add_theme_support() if it comes to that. I just don't know about one that is theme-specific.

[flixos90]

I think the approach for adding a filter to the theme makes sense especially for child themes.

However I also agree that it could also be enhanced on the Core side of things. Regarding this filter, what are the thoughts about placing it in the add_theme_support() function as a dynamic filter with the theme slug in it?

[celloexpressions]

I like the idea of filtering in both places - in the theme as per 39109.patch​ (preferable for child themes) and also more clearly on the core side (which would be more-often useful for plugins). We also need hook docs and perhaps a few inline comments in the Twenty Seventeen array, for example to explain design decisions about what content is included or not included from the full core options and why.

[celloexpressions]

Add inline documentation for new filter and breaking down the starter content array.

[celloexpressions]

39109.1.diff​ adds inline documentation to 39109.patch​ for the new filter and also adds periodic inline documentation throughout the starter content array to explain what's happening and some of the decisions the theme makes. This makes Twenty Seventeen a much better example of how to register starter content as there is a better explanation of how it's working and what it's doing inline. The comments here are a first pass - if anyone sees any typos or possible additions/improvements please iterate on it.

Switching to has-patch since 39109.1.diff​ covers everything that would be needed for child themes, especially if other themes base their implementations on Twenty Seventeen (1.1+). Plugins would probably be more comfortable with filtering the expanded array via the existing core filter mentioned above than themes, but adding another filter in core pre-expansion would be the other potential change here.

[celloexpressions]

I'm going to mark this for commit for 39109.1.diff​.

Building a child theme, the first place I would look for a filter is in the parent theme, since I'd look there to see how I'd change what the parent registers. An exception could be if the child theme intends to completely replace the parent's starter content, in which case it would make sense to use a filter in core. I don't think that's particularly likely for starter content, though, and children will usually retain at least some of the parent functionality and the associated starter content.

If nothing else, 39109.1.diff​ improves Twenty Seventeen as an example implementation of starter content, particularly with the addition of inline documentation to explain how it's working (bringing this in line with the rest of the theme's inline documentation). The filter there doesn't hurt anything and we could add a core-side filter in the future as well if there's a need for that.

There are other changes to Twenty Seventeen in 4.7.1 necessitating a release of the theme alongside core; we should get the theme-side changes in (and the docs changes, if nothing else) for 4.7.1 since the theme may not need an update for 4.7.2.

[dd32]

I agree with the thoughts that there should probably be a filter in the starter content somewhere.

However, until there is one, having this in the theme is also a reasonable thing to do IMHO, so +1 from me for 39109.1.diff​

[jbpaul17]

Per today's bug scrub in #core: @ocean90 is going to tweak the patch and look to land this for 4.7.1.

[ocean90]

In 39720:

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

Add some documentation to the default starter content.

Props sanket.parmar, celloexpressions.
Fixes #39109.

[ocean90]

In 39721:

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.