Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Theme Handbook Overhaul] Outline Chapter: Patterns #1415

Closed
justintadlock opened this issue Jan 19, 2024 · 13 comments
Closed

[Theme Handbook Overhaul] Outline Chapter: Patterns #1415

justintadlock opened this issue Jan 19, 2024 · 13 comments
Assignees
Labels
developer documentation (DevHub) Improvements or additions to developer documentation needs discussion Issue that need discussion and team's decision. Will be discussed at the meeting. [Status] Done Issue is completed themes Issues for Theme Developer Handbook

Comments

@justintadlock
Copy link

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?

@justintadlock justintadlock added developer documentation (DevHub) Improvements or additions to developer documentation needs discussion Issue that need discussion and team's decision. Will be discussed at the meeting. themes Issues for Theme Developer Handbook labels Jan 19, 2024
@justintadlock justintadlock self-assigned this Jan 19, 2024
Copy link

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

Copy link

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

@justintadlock
Copy link
Author

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
Copy link
Collaborator

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

@carolinan
Copy link
Collaborator

carolinan commented Jan 22, 2024

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
Copy link
Author

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
Copy link
Member

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
Copy link
Collaborator

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
Copy link
Author

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
Copy link
Author

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
  • 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
Copy link
Collaborator

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
Copy link
Author

@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
Copy link
Author

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.

@github-actions github-actions bot added the [Status] Done Issue is completed label Mar 5, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
developer documentation (DevHub) Improvements or additions to developer documentation needs discussion Issue that need discussion and team's decision. Will be discussed at the meeting. [Status] Done Issue is completed themes Issues for Theme Developer Handbook
Projects
None yet
Development

No branches or pull requests

4 participants