WordPress.org

Make WordPress Core

Opened 6 months ago

Closed 5 months ago

Last modified 5 months ago

#39109 closed defect (bug) (fixed)

Twenty Seventeen: starter content array needs a filter

Reported by: celloexpressions Owned by: ocean90
Milestone: 4.7.1 Priority: normal
Severity: normal Version: 4.7
Component: Bundled Theme Keywords: has-patch commit
Focuses: Cc:

Description

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.

Attachments (3)

39109.patch (763 bytes) - added by sanket.parmar 6 months ago.
39109.1.diff (3.2 KB) - added by celloexpressions 5 months ago.
Add inline documentation for new filter and breaking down the starter content array.
39109.2.patch (3.2 KB) - added by ocean90 5 months ago.

Download all attachments as: .zip

Change History (18)

#1 @sanket.parmar
6 months ago

  • Keywords has-patch added; needs-patch removed

#2 @helen
6 months ago

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.

#3 @flixos90
6 months ago

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?

#4 @celloexpressions
6 months ago

  • Keywords needs-patch added; has-patch removed

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.

This ticket was mentioned in Slack in #core by jeffpaul. View the logs.


6 months ago

@celloexpressions
5 months ago

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

#6 @celloexpressions
5 months ago

  • Keywords has-patch added; needs-patch removed

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.

This ticket was mentioned in Slack in #core by jeffpaul. View the logs.


5 months ago

This ticket was mentioned in Slack in #themereview by celloexpressions. View the logs.


5 months ago

This ticket was mentioned in Slack in #core by jeffpaul. View the logs.


5 months ago

#10 @celloexpressions
5 months ago

  • Keywords commit added

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.

#11 @dd32
5 months ago

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

This ticket was mentioned in Slack in #core by jeffpaul. View the logs.


5 months ago

#13 @jbpaul17
5 months ago

  • Owner set to ocean90
  • Status changed from new to assigned

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

@ocean90
5 months ago

#14 @ocean90
5 months ago

  • Resolution set to fixed
  • Status changed from assigned to closed

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.

#15 @ocean90
5 months ago

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.

Note: See TracTickets for help on using tickets.