Custom Product Templates for Block Themes  🔗 **Source:** [Custom Product Templates for Block Themes](https://www.briancoords.com/custom-product-templates-for-block-themes/) > [!note]+ Document Notes > tags: [block-themes, woocommerce, wordpress-development, site-editor, template-hierarchy, custom-templates] > author: Brian Coords > source: briancoords.com > reference: https://www.briancoords.com/custom-product-templates-for-block-themes/ > date created: {{date:YYYY-MM-DD}} {{time:HH:mm}} > > # 🏷️ Title: Custom product templates for block themes > <!-- deep-read:sections start --> ## 🧭 Table of Contents - [📝 Summary](#-summary) - [📖 Main Content](#-main-content) - [🗒️ Notes](#️-notes) - [📚 References](#-references) - [🗣️ Paraphrase](#️-paraphrase) - [📰 Newsletter](#-newsletter) - [✅ Action Items](#-action-items) - [🧪 Hypotheses](#-hypotheses) - [📊 Methodology](#-methodology) - [❓ Questions](#-questions) - [🔮 Future Research](#-future-research) - [💡 Implications](#-implications) - [🧠 Learning Styles Assessment](#-learning-styles-assessment) - [📊 Accessibility Assessment](#-accessibility-assessment) - [🌍 DEIB Assessment](#-deib-assessment) - [✅ Logical Validity](#-logical-validity) - [🛡️ DARVO Analysis](#-darvo-analysis) - [🎯 Conclusion](#-conclusion) ### 🔗 References - [New plugin template registration API in WordPress 6.7](https://make.wordpress.org/core/2024/10/20/new-plugin-template-registration-api-in-wordpress-6-7/) - [`{$type}_template_hierarchy` filter reference](https://developer.wordpress.org/reference/hooks/type_template_hierarchy/) - [Example plugin: woo-example-product-templates](https://github.com/bacoords/woo-example-product-templates) ## 📝 Summary - Brian Coords shows how to give WooCommerce block themes custom product templates that apply to whole groups of products (e.g. a category, subscriptions), not just the one-off single-product override the site editor already allows. - It matters because WooCommerce product pages are simultaneously functional (variations, add-to-cart) and marketing surfaces, and bespoke Woo stores routinely need per-collection design control that block themes make awkward today. - Key stakeholders: WooCommerce store builders, block-theme developers, and plugin authors who want reusable per-taxonomy templates without a page builder. - The technique combines two core WordPress features: the plugin template registration API (`register_block_template()`, added in 6.7) and the long-standing `single_template_hierarchy` filter (since 4.7). One registers the templates; the other injects them into the hierarchy based on the product object. - Risks/tradeoffs: registering a template per category is expensive to render in the site editor, so the author registers only the templates he needs and keeps the logic deliberately simple. Instead of hard-coding a default design, his example falls back to the site's existing Single Product template. - Bottom line: with two modest hooks you can route different product collections to different block templates, editable in the site editor, without a settings UI or a bloated default-design payload. ## 📖 Main Content - The piece opens by situating block themes in the ongoing "are they unpopular?" debate, then argues that block themes can beat classic themes on design and performance "with work," with full in-editor customization as the payoff. - WooCommerce is called out as a low-marketshare case for block themes because storefronts are far more complex than a publication or marketing site. Core WooCommerce blocks are powerful, but almost nobody runs core Woo without extensions and customizations, and bespoke needs drive customization needs. - The specific pain point tackled: custom product template pages. Product pages must stay consistent and include expected commerce functionality, yet they are also marketing pages that sometimes need extra content and design flourish. - The site editor already supports one-off custom product templates, but each applies to a single product. The author wants templates that target collections — all products in a category, or all subscription products. - Feature 1 — Custom block templates: the plugin template registration API (introduced in WordPress 6.7) exposes one function, `register_block_template()`. Its original purpose was to let plugins ship default template designs for their custom post types (as WooCommerce does for Products), which historically only themes could do. But the function can register *any* new block template into the site editor. - Feature 2 — Template hierarchy filter: `{$type}_template_hierarchy` (available since WordPress 4.7), specifically `single_template_hierarchy`. Classic-theme developers know the template hierarchy as WordPress's flexible way of deciding which template renders. The demo "hi-jacks" the hierarchy and inserts custom templates based on the product post object. - The example plugin combines both: register custom templates, then inject them into the hierarchy, with extra touches for convenience and performance. The example targets templates by category, but the logic could adapt to product type or any product taxonomy. - Performance choice: the author registers only the templates he knows he needs rather than looping through all categories, because per-category registration is expensive — especially in the site editor, "which loves rendering unnecessary thumbnail iframe previews." He rejected building a settings page and deliberately kept it simple. - Default-design twist: normally you pass HTML markup as the `content` parameter to control the design from plugin code ("Built-in version control"). Instead, his example dynamically pulls the site's Single Product template as the default, so an un-overridden template always falls back to the main Single Product template. His advice: if you won't customize a template, don't register it — keep it lean. - Contested/uncertain: the author flags there may be "some rough edges" and invites readers to clone the repo or point an AI agent at it. Next planned topic is custom Product fields and how to surface them in product-page designs. ### 🗒️ Notes - **The gap being closed**: site editor gives you single-product one-offs; there's no built-in UI for "all products in category X share this template." This technique fills that gap in code. - **Two-hook architecture**: `register_block_template()` (make it exist in the editor) + `single_template_hierarchy` filter (decide when to use it based on the product object). Register + inject. - **API origin story**: template registration API was meant to let plugins provide default templates for CPTs — the thing that was previously theme-only. Woo uses it to supply Product/page templates when the theme lacks them. - **Reuse beyond intent**: the same function registers arbitrary block templates "whether there's a specific use for it or not" — the author uses it for a purpose its designers didn't specifically target. - **Scope of the demo**: category-based, but explicitly generalizable to product type or any product taxonomy. - **Deliberate simplicity**: no loop over all categories, no settings page. Only register templates you actually need. Rationale is site-editor performance (thumbnail iframe preview rendering). - **Fallback design decision**: rather than shipping a hard-coded default via the `content` param, dynamically inherit the site's Single Product template. Un-overridden templates degrade gracefully to the main template. - **Version-control aside**: including HTML markup in the plugin as `content` gives you "Built-in version control" of the design. - **Distribution nudge**: clone the repo, or "point your agent at it and tell it to use this technique." - **Forward pointer**: next post covers custom Product fields in product-page designs. ## 📚 References - [New plugin template registration API in WordPress 6.7](https://make.wordpress.org/core/2024/10/20/new-plugin-template-registration-api-in-wordpress-6-7/) - [`{$type}_template_hierarchy` hook (developer.wordpress.org)](https://developer.wordpress.org/reference/hooks/type_template_hierarchy/) - [bacoords/woo-example-product-templates (GitHub)](https://github.com/bacoords/woo-example-product-templates) ## 🗣️ Paraphrase - Block themes are debated, but the author has seen enough real-world block sites to believe they can, with effort, out-design and out-perform classic themes while staying fully editable. - WooCommerce block themes lag partly because storefronts are far more complex than content sites, and real stores always layer on extensions and customizations. - Product pages are hard because they must be both consistent commerce interfaces and flexible marketing pages. - The editor already does one-off product templates; the goal here is templates for collections of products. - Solution: pair the 6.7 template registration API with the old `single_template_hierarchy` filter — register the templates, then inject them based on the product. - Keep it lean: register only needed templates (site-editor previews make bulk registration costly), and let un-customized templates inherit the site's Single Product template instead of a hard-coded default. ## 📰 Newsletter - Building a WooCommerce store on a block theme and hitting the wall where the site editor only lets you customize one product at a time? Brian Coords has a tidy fix. By combining WordPress 6.7's `register_block_template()` with the venerable `single_template_hierarchy` filter (a 4.7-era classic), you can route entire product collections — a whole category, all your subscriptions — to their own editable block templates. - The elegant part is the restraint: no settings page, no looping over every category (the site editor's thumbnail-preview habit makes that pricey), and instead of hard-coding a default design, the templates gracefully fall back to your existing Single Product template. Clone [the example plugin](https://github.com/bacoords/woo-example-product-templates) or point your favorite coding agent at it. Next up in his series: custom Product fields. ## ✅ Action Items #### DevRel - Developer advocacy: build a short demo/screencast pairing `register_block_template()` with `single_template_hierarchy` for a WooCommerce category template. - Education: write a "block themes for WooCommerce" workshop module using this per-taxonomy pattern as the anchor example. - Developer experience: package a minimal starter template/quickstart from the example repo with inline comments explaining the register-then-inject flow. - Developer marketing: content series tie-in — sequence this with the upcoming custom Product fields post. - Community management: collect "rough edges" reports from people who try the repo and route them upstream. - Internal/external/cross-project: coordinate with the WooCommerce blocks team on whether per-collection templates deserve first-class UI. #### OSPO - Policy & Governance: Not applicable to this source — a personal technical tutorial with no governance dimension. - License Compliance: check the example repo's license before redistributing derived starters. - Security Management: Not applicable to this source — no security-sensitive surface discussed. - Software Inventory: Not applicable to this source — no SBOM concern. - Developer Support: offer office-hours support for teams adopting the register-then-inject pattern. - Community Engagement: Not applicable to this source — no funding/operator agreements involved. - Strategic Alignment: Not applicable to this source — out of scope for a single tutorial. #### Community - Maintainers: Not applicable to this source — no maintainer governance content. - Contributors: invite PRs to harden the example plugin's "rough edges." - Sponsors: Not applicable to this source. - Ecosystem: cross-reference with other WooCommerce block-theme customization guides. #### WordPress - Core: note that `register_block_template()` (6.7) and `single_template_hierarchy` (4.7) together enable per-collection templating. - Core Performance: profile site-editor cost of registering many block templates (thumbnail iframe previews). - Core AI: Not applicable to this source — beyond the author's "point your agent at it" aside. - **Core Program Team:** Not applicable to this source. - Documentation: DevHub could add an example of injecting custom templates via `single_template_hierarchy` based on a post object. - Themes: document how block themes can defer to plugin-registered default templates. - Training: add a lesson on template hierarchy filters for block-theme developers. #### The WPCC - Programs: Not applicable to this source — no funding/fellowship dimension. - Projects: Not applicable to this source. - Funding experiments: Not applicable to this source. ### FAIR - Technical independence: Not applicable to this source — no metadata/provenance dimension. - Policies and covenants: Not applicable to this source. - Productized governance artifacts: Not applicable to this source. ## 🧪 Hypotheses - Registering only the templates you need (vs. one per category) measurably reduces site-editor load time on stores with many product categories. - Falling back to the site's Single Product template produces fewer visual regressions than shipping a hard-coded default design in the plugin. - The `single_template_hierarchy` injection approach generalizes cleanly to product type and arbitrary product taxonomies without additional core support. - Store builders will adopt a code-only pattern over a settings-page UI when the code stays under a small complexity threshold. - Pointing an AI coding agent at the example repo yields a working per-category template with minimal human edits. ### 📊 Methodology - Load-time A/B: instrument the site editor on a store with N categories, comparing "register only needed" vs. "register all categories," measuring editor TTI and iframe-preview render counts. - Regression testing: visual-diff un-overridden templates under the dynamic Single-Product fallback vs. a static hard-coded default across theme updates. - Generalization test: fork the example, swap the category condition for product-type and a custom taxonomy, and verify correct template selection. - Adoption study: survey block-theme developers on preference thresholds for code vs. settings UI. - Agent trial: run several coding agents against the repo with a fixed prompt and score working output. ### ❓ Questions - How does `register_block_template()` interact with themes that already ship WooCommerce templates — who wins in the hierarchy? - What exactly are the "rough edges" the author warns about? - Does the dynamic Single-Product fallback survive theme switches and template edits cleanly? - Is there a caching path to avoid the site-editor thumbnail-preview cost when many templates are registered? - Could this pattern be upstreamed into a general-purpose plugin with a light UI without the performance penalty? ### 🔮 Future Research - A companion piece (already promised) on custom Product fields and surfacing them in product-page designs. - Benchmarks for site-editor performance as a function of registered-template count. - Patterns for per-taxonomy templates beyond WooCommerce (e.g., custom post types with rich taxonomies). - Guidance on when to ship a default design (`content` param) vs. inherit an existing template. ### 💡 Implications - Practice: block-theme WooCommerce builders gain a lightweight, editor-native way to differentiate product collections without page builders. - Policy: reinforces that plugin-registered templates are a legitimate distribution mechanism, not just a WooCommerce internal. - Security: minimal surface; no new input handling introduced by the pattern itself. - Education: a clean teaching example of combining a new API with an old filter. - Funding models: lowers the cost of bespoke Woo storefronts, potentially shifting work from custom page builders to block-native templating. ### 🧠 Learning Styles Assessment - Reading level estimate: roughly Flesch-Kincaid grade 9–11 — conversational but with domain jargon (template hierarchy, taxonomy, iframe previews). Flesch Reading Ease approximately 45–55. #### 👀 Visual learners - Present: two annotated screenshots of the site editor showing one-off vs. desired collection templates. - Improve: add an architecture diagram of register → inject → render, and a before/after of a category template. #### 🔊 Aural learners - Present: none. - Improve: a 3–4 minute audio walkthrough of the two-hook pattern. #### 🗣️ Verbal learners - Present: plain-language analogies ("hi-jack the template hierarchy"), defined terms. - Improve: a short glossary for `register_block_template()`, template hierarchy, and taxonomy. #### 🧩 Kinesthetic learners - Present: a clonable example repo to run hands-on. - Improve: a step-by-step checklist from install to a working category template. #### 🧠 Logical learners - Present: clear cause/effect on the performance tradeoff of bulk registration. - Improve: a decision tree for "register a default design vs. inherit Single Product." #### 🧑‍🤝‍🧑 Social learners - Present: an invitation to try it and share feedback. - Improve: a discussion thread or issues board prompt for shared "rough edges." #### 🧘‍♀️ Solitary learners - Present: self-paced repo exploration. - Improve: reflection prompts on where per-collection templates fit your store. #### 🌿 Naturalistic learners - Present: none. - Improve: frame "keep it lean" as ecosystem/resource stewardship of editor performance. ### 📊 Accessibility Assessment #### Screen reader semantics - Present: article uses headings (H2 section) and figures. - Improve: the two screenshots have empty `alt=""`; add descriptive alt text conveying what each editor state shows. #### Keyboard navigation - Present: standard article links. - Improve: ensure the lightbox image interaction (Interactivity API) is keyboard operable and dismissible. #### Contrast and readability - Present: standard blog typography. - Improve: verify 4.5:1 on links and code snippets. #### Text resizing and reflow - Present: responsive image `sizes`/`srcset`. - Improve: confirm code/inline `<code>` reflows at 200% zoom without clipping. #### Media and captions - Present: figures with images. - Improve: the empty alt text is the main gap; caption the screenshots. #### Forms and interactions - Present: none — no forms. - Improve: Not applicable to this source — no interactive forms present. #### Standards reference - Primary gap maps to WCAG 2.2 AA 1.1.1 Non-text Content (empty alt on informative screenshots) and 2.1.1 Keyboard (lightbox). ### 🌍 DEIB Assessment #### Cultural breadth - Present: neutral technical examples, no region-specific assumptions. - Improve: Not applicable to this source — technical tutorial with no cultural framing needed. #### Inclusive language - Present: plain, jargon-defined language; no exclusionary terms. - Improve: expand the glossary so newcomers aren't gated by assumed template-hierarchy knowledge. #### Neurodiversity support - Present: chunked sections, numbered feature headings, consistent structure. - Improve: add a short summary box up top for quick orientation. #### Representation - Present: Not applicable to this source — no people/identities depicted. - Improve: Not applicable to this source. #### Psychological safety - Present: welcoming tone, "let me know what you think," acknowledges rough edges honestly. - Improve: none needed. ### ✅ Logical Validity #### Strong reasoning - Causal: registering a template per category → expensive site-editor rendering (thumbnail iframe previews) → therefore register only needed templates. The mechanism is named, making the causal claim credible. - Analogical: framing the technique as "hi-jacking the template hierarchy" leverages classic-theme developers' existing mental model to explain a new maneuver. - Inductive: "I've seen enough block-based sites in the wild" supports the claim that block themes can beat classic themes — reasonable but anecdotal. #### Fallacies - Mild hasty generalization: "block themes- with work- can beat classic themes on design and performance" rests on personal observation ("enough block-based sites in the wild") rather than measured data. Fix: cite performance benchmarks or case studies. - Appeal to simplicity as virtue: "I kept it simple" is presented as self-justifying; the performance rationale supports it, but simplicity alone isn't proof of correctness. Fix: pair with a benchmark showing the lean approach's editor-load win. #### Tone of voice - Pragmatic, candid, peer-to-peer. Examples: "But I didn't do any of that. I kept it simple." and "There may be some rough edges." Confident but humble, developer-to-developer. ### 🛡️ DARVO Analysis - Deny: none — the author doesn't deny wrongdoing; he candidly flags limitations ("rough edges"). - Attack: none — no accusers or credibility attacks; the block-theme "debate" is engaged, not weaponized. - Reverse victim/offender: none. - Overall: DARVO patterns are absent. This is a cooperative technical tutorial, not a defensive or adversarial piece. ## 🎯 Conclusion - Bottom line: combine WordPress 6.7's `register_block_template()` with the 4.7-era `single_template_hierarchy` filter to give WooCommerce block themes editable, per-collection product templates — register the templates, then inject them based on the product object. - Practical next steps for readers: clone [woo-example-product-templates](https://github.com/bacoords/woo-example-product-templates) (or point a coding agent at it), start by targeting a single product category, register only templates you'll actually customize, and let the rest inherit the site's Single Product template. Watch for the follow-up on custom Product fields. ## 🔄 Refactor Appendix — Custom product templates for block themes > Density: 2–5 Literature atoms (H3), 0–3 Permanent candidates (H4). > Defaults: 3 Literature, 1 Permanent. ### 📚 Literature Atoms (H3) #### [H1] Two core hooks enable per-collection block product templates > [!quote] ID:rw_manual > For that, we’re going to rely on two core features of WordPress- one that’s very old, and one that’s relatively new. **Context & use**: - Transition into the technique, just before the "Custom block templates" section. - The whole method reduces to `register_block_template()` (6.7) plus the `single_template_hierarchy` filter (4.7) — register then inject. **Tags**: #xref **Highlight**: [view highlight](https://www.briancoords.com/custom-product-templates-for-block-themes/) <!-- atomicity: 1 idea ✓ --> #### [H2] Registration API registers any block template, not just CPT defaults > [!quote] ID:rw_manual > But this function actually lets you register any new block templates to show up in the site editor, whether there’s a specific use for it or not. **Context & use**: - In the "1. Custom block templates" section, reframing the API's original CPT-default purpose. - Justifies using `register_block_template()` for arbitrary per-collection templates. **Tags**: #xref **Highlight**: [view highlight](https://www.briancoords.com/custom-product-templates-for-block-themes/) <!-- atomicity: 1 idea ✓ --> #### [H3] Register only needed templates to protect site-editor performance > [!quote] ID:rw_manual > That’d be expensive, especially when loading the site editor, which loves rendering unnecessary thumbnail iframe previews for some reason. **Context & use**: - Explains why the author avoids looping over all categories. - Performance rationale for the "keep it lean" design choice. **Tags**: #xref #aphorisms **Highlight**: [view highlight](https://www.briancoords.com/custom-product-templates-for-block-themes/) <!-- atomicity: 1 idea ✓ --> #### [H4] Inherit the Single Product template instead of hard-coding a default > [!quote] ID:rw_manual > instead of the plugin hard-coding a default design for these templates, it dynamically pulls your site’s Single Product template as the default value **Context & use**: - Near the end, the key design departure from WooCommerce's default-design approach. - Un-overridden templates degrade gracefully to the main Single Product template. **Tags**: #xref **Highlight**: [view highlight](https://www.briancoords.com/custom-product-templates-for-block-themes/) <!-- atomicity: 1 idea ✓ --> ### 🧠 Permanent Candidates (H4) #### [P1] Compose old filters with new APIs to extend WordPress without core changes **Claim** (one sentence, Courtney's voice): Pairing a long-standing extension point with a newer registration API lets you add capabilities WordPress never shipped a UI for, without patching core or building settings screens. **Evidence pointer**: [[#H1]] **Scope & conditions**: Holds when the old filter still fires in the block context and the new API exposes the needed registration surface; breaks when core deprecates the filter or the registration cost (e.g. site-editor previews) outweighs the benefit. **Links**: - [[Block themes]] — because applies-in block-theme development - [[WordPress template hierarchy]] — because extends the classic hierarchy into block context - [[WooCommerce customization]] — because applies-in bespoke storefronts <!-- atomicity: 1 idea ✓ --> ### ✏️ Fleeting Queue - [F1] Watch for Brian Coords' promised follow-up on custom Product fields in product-page designs — https://www.briancoords.com/custom-product-templates-for-block-themes/ #fleeting #inbox - [F2] Benchmark site-editor load cost vs. number of registered block templates (thumbnail iframe previews) #fleeting #inbox ### → Things 3 (max 2 actions) - [ ] Clone woo-example-product-templates and test a category template on a staging WooCommerce block theme — https://github.com/bacoords/woo-example-product-templates #things <!-- deep-read:sections end --> 📄 **Full text:** [[Full Document Contents/Articles/Custom Product Templates for Block Themes.md|Custom Product Templates for Block Themes by briancoords.com]] ## Highlights - For that, we’re going to rely on two core features of WordPress- one that’s very old, and one that’s relatively new. ([View Highlight](https://read.readwise.io/read/01kx6gxy3r8675g57gefp6gnsn)) - Note: The two-hook architecture (6.7 registration API + 4.7 hierarchy filter) the whole technique reduces to. - Tags: atom/literature/h1 - But this function actually lets you register *any* new block templates to show up in the site editor, whether there’s a specific use for it or not. ([View Highlight](https://read.readwise.io/read/01kx6gypykg169vwfkx1z53488)) - Note: Reframes register_block_template() beyond its CPT-default origin — arbitrary per-collection templates. - Tags: atom/literature/h2 - That’d be expensive, especially when loading the site editor, which loves rendering unnecessary thumbnail iframe previews for some reason. ([View Highlight](https://read.readwise.io/read/01kx6gyww53kktffq8v40qej9s)) - Note: Performance rationale for registering only needed templates instead of looping all categories. - Tags: atom/literature/h3 - instead of the plugin hard-coding a default design for these templates, it dynamically pulls your site’s Single Product template as the default value ([View Highlight](https://read.readwise.io/read/01kx6gz233c5yc7p84n0ngh073)) - Note: Key departure from WooCommerce's default-design approach — graceful inheritance fallback. - Tags: atom/literature/h4