[Theme Handbook Overhaul] Outline Chapter: Patterns

[justintadlock]

This is a sub-ticket of #816 for discussing the addition of a new Patterns chapter to the outline.

In December, it was decided that we'd add a new Patterns chapter to the outline (see updated post. There is currently a Block Patterns doc in the Features chapter. But, even as writing it, we knew we would need more docs (see notes).

The new chapter would be located at developer.wordpress.org/themes/patterns/.

This ticket aims to outline this new chapter since it was not in the Theme Handbook Overhaul project's initial outline. The current rough proposal is to have a new top-level chapter with the following sub-docs:

• Chapter Landing Page
• Introduction to Patterns
• Registering Patterns
• Pattern Categories
• Including Patterns in Templates
• Starter Page Patterns
• Starter Template Patterns
• Block Type Patterns
• Locked Patterns

The biggest thing I believe we need to do is ensure that we are covering all the specific sub-features that are possible with patterns. Is there anything missing from that list? Are there upcoming features in WP 6.5 that we need to include?

[github-actions]

Heads up @kafleg @carolinan @TeBenachi - the "themes" label was applied to this issue.

[github-actions]

Heads up @WordPress/docs-issues-coordinators, we have a new issue open. Time to use 'em labels.

[justintadlock]

CC: @richtabor, @annezazu - I know both of you had thoughts on having a dedicated Patterns chapter. Let me know if you'd change or add anything.

[carolinan]

Partially synced patterns: now called pattern overrides, are planned for 6.5. This could fit under locking or synced patterns though.

[carolinan]

I think that starter page patterns and starter template patterns could be one sub doc, because this is about where the patterns can be displayed in the pattern selection modal, correct? I mean the post types parameter?

[justintadlock]

I think that starter page patterns and starter template patterns could be one sub doc, because this is about where the patterns can be displayed in the pattern selection modal, correct? I mean the post types parameter?

Yes, I think they can be combined into a single doc.

[richtabor]

Partially synced patterns: now called pattern overrides, are planned for 6.5. This could fit under locking or synced patterns though.

Perhaps unofficially. I like to think of this feature as a capability of patterns, rather than a named feature.

[annezazu]

Big +1 on consolidating starter page patterns and thinking of pattern overrides as a capability rather than a feature. The only other item on my mind is to touch on managing patterns as that's been a pain point as you well know: WordPress/create-block-theme#287

[justintadlock]

Managing patterns is a good point to bring up, @annezazu. Given that there are no well-defined dev solutions for that, it might be worth mentioning in the "Intro" section since I think that doc should at least cover how the Pattern Library works (the library is one method of managing patterns to some degree).

[justintadlock]

Thanks for the feedback, everyone. I think we have enough to start with (and, of course, we can always change things as needed).

I'll leave this ticket open for a few days just in case there's any other feedback, but here's what I have for a starting point:

• Chapter Landing Page
  • Short intro describing the chapter.
  • Map with descriptions of each page in the chapter.
• Introduction to Patterns
  • Overview of what patterns are.
  • Show how to create/use patterns in the admin.
  • Discuss managing patterns and potential options for themers.
• Registering Patterns
  • How to register patterns
  • How to unregister patterns
  • Conditionally registering/unregistering patterns
  • Disabling core and remote patterns
  • Pattern categories
    • Core pattern categories
    • Register/Unregister
    • Potentially leave this open for its own doc if needed.
• PHP in Patterns
  • Patterns are registered in init
    • Global post and other data not available yet
  • Internationalization
  • Including media and other assets
• Patterns and Templates
  • How to include patterns inside templates
  • Relationship between patterns and template parts (e.g., replacements)
• Starter Patterns
  • Creating template patterns
  • Creating starter patterns
  • Reference: Adding starter patterns to your WordPress themes
• Block Type Patterns:
  • Adding patterns for specific block types
  • How this mechanism works in WP
  • Query Loop is a good example
• Pattern Locking / Curation??
  • How to lock individual blocks (e.g., lock)
  • How to lock groups/templates of blocks (templateLock)
  • Using the allowedBlocks setting (only works for Group?)
  • Note: a lot of this works for templates too, so we could potentially split this to the "Advanced Topics" chapter.

[carolinan]

Would user-created patterns and synced patterns also be mentioned in the introduction? I think it may be confusing to not mention some of the differences.

[justintadlock]

@carolinan - Yes, that would fall under the "Show how to create/use patterns in the admin" part. It'd be worth diving into the types of patterns and who can create/edit them.

[justintadlock]

I'm going to close this ticket since we have a solid outline. Thanks for the feedback everyone.

This chapter outline is now integrated into the Overhaul Outline Doc and the Tracking Ticket.