From c432bdc02decf4c8bd9bcc69e4d18120d097f9f8 Mon Sep 17 00:00:00 2001 From: magdev Date: Sat, 28 Feb 2026 11:20:46 +0100 Subject: [PATCH] Update documentation for v0.1.0 release - README: document rendering bridge architecture, template coverage, directory structure, and how the interception pipeline works - CHANGELOG: comprehensive list of all features added across phases 1-9 - PLAN: update dependencies to reflect completed bridge implementation Co-Authored-By: Claude Opus 4.6 --- CHANGELOG.md | 28 ++++++++++++++++----- PLAN.md | 2 +- README.md | 71 ++++++++++++++++++++++++++++++++++++++++++++-------- 3 files changed, 84 insertions(+), 17 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9e6b7ea..ccdc95d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,12 +6,28 @@ All notable changes to this project will be documented in this file. ### Added -- Initial theme scaffold -- Bootstrap 5 base templates (base, page, form, single, archive, account) -- Template override mechanism via Twig `prependPath()` -- Parent theme rendering delegation via render page filter -- Theme wrapping support (`_theme_wrapped` context flag) -- CSS override stylesheet for plugin-to-Bootstrap class mapping +- Initial theme scaffold (style.css, functions.php, Composer autoload) +- Comprehensive template conversion plan (PLAN.md) +- **Phase 1**: Global templates (wrapper, breadcrumb, sidebar, quantity-input, form-login) and notices (success, error, info) +- **Phase 2**: Product archive and shop loop templates (archive-product, content-product, loop components, pagination, orderby, sale-flash) +- **Phase 3**: Single product page templates (image gallery, title, price, meta, stock, tabs, add-to-cart forms for simple/variable/grouped/external) +- **Phase 4**: Cart templates (cart table, empty cart, cart totals, shipping calculator, mini-cart, cross-sells) +- **Phase 5**: Checkout templates (form-checkout, billing/shipping forms, coupon, order review, payment methods, terms, thank-you) +- **Phase 6**: My Account templates (dashboard, navigation, orders, view-order, addresses, edit-address, edit-account, downloads, payment methods, login/register, password reset) +- **Phase 7**: Order details templates (order-details, order-details-item, order-details-customer, form-tracking, order-again) +- **Phase 9**: Supplementary templates (brands, OAuth auth, back-in-stock form) +- Reusable Twig components (card, pagination, price, rating, address-card, status-badge, quantity-input, form-field) +- WooCommerce-to-Twig rendering bridge (`TemplateOverride` + `WooCommerceExtension`) +- ~50 WooCommerce/WordPress Twig functions and 7 Twig filters +- Stack-based output buffering for nested template interception +- Bootstrap 5 override stylesheet (`wc-bootstrap.css`) +- Quantity +/- button JavaScript handler - Sticky header scroll shadow behavior +- Parent theme rendering delegation via `woocommerce_render_page` filter +- Theme wrapping signal via `woocommerce_is_theme_wrapped` filter - CI/CD release workflow (Gitea Actions) - Translation support (`.pot` template ready) + +### Skipped + +- **Phase 8** (Email templates): WooCommerce emails use `wc_get_template_html()` which bypasses the Twig rendering pipeline. Default email templates are sufficient; customization can be handled via dedicated email plugins. diff --git a/PLAN.md b/PLAN.md index 9753bd4..7443a12 100644 --- a/PLAN.md +++ b/PLAN.md @@ -506,7 +506,7 @@ New reusable components to create: **8** | Dependency | Status | Impact | | ---------- | ------ | ------ | | Docker environment | Not set up | Cannot test WP-CLI, i18n extraction; use local PHP server | -| WooCommerce plugin Twig layer | Required | `TemplateOverride` depends on `Magdev\Woocommerce\Frontend\Template` | +| WooCommerce-to-Twig bridge | Implemented | `TemplateOverride` intercepts `wc_get_template()` via before/after hooks; `WooCommerceExtension` provides ~50 Twig functions and 7 filters | | Parent theme Twig functions | Available | `__()`, `esc_html()`, `esc_attr()`, etc. registered by `TwigService` | | Bootstrap 5 CSS/JS | Available | Loaded by parent theme `wp-bootstrap` | | Composer autoloader | Available | PSR-4 for `WcBootstrap\` namespace | diff --git a/README.md b/README.md index 264eeff..94bd104 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,7 @@ A WordPress child theme of [WP Bootstrap](https://src.bundespruefstelle.ch/magde - PHP 8.3+ - [WP Bootstrap](https://src.bundespruefstelle.ch/magdev/wp-bootstrap) theme (parent) - [WooCommerce](https://github.com/woocommerce/woocommerce.git) plugin +- Composer ## Installation @@ -17,33 +18,83 @@ A WordPress child theme of [WP Bootstrap](https://src.bundespruefstelle.ch/magde 4. Run `composer install` in the theme directory 5. Activate the theme in WordPress Admin > Appearance > Themes -## What This Theme Does +## How It Works -The WooCommerce plugin ships with its own Twig templates using custom CSS classes. This child theme overrides those templates to use Bootstrap 5 components, ensuring visual consistency with the WP Bootstrap parent theme. +WooCommerce renders its pages using PHP templates loaded via `wc_get_template()`. This child theme intercepts that process with a **Twig rendering bridge** that replaces the PHP output with Bootstrap 5 styled Twig templates. + +The bridge hooks into WooCommerce's `woocommerce_before_template_part` and `woocommerce_after_template_part` actions. When a matching `.html.twig` template exists, it is rendered via the parent theme's TwigService and the original PHP output is discarded. If no Twig override exists, the default PHP template renders normally. ### Key Features -- Bootstrap 5 markup for all plugin templates -- Responsive design inheriting WP Bootstrap's grid system -- Dark mode support via WP Bootstrap's theme toggle +- **99 Twig template overrides** covering all customer-facing WooCommerce pages +- **Rendering bridge** (`WooCommerceExtension` + `TemplateOverride`) that intercepts WooCommerce's PHP template pipeline +- **~50 Twig functions** and **7 Twig filters** exposing WooCommerce and WordPress APIs to templates +- Bootstrap 5 responsive markup with dark mode support +- HPOS compatible (uses `WC_Order` methods only, no `$post` global) +- 8 reusable Twig components (card, pagination, price, rating, address-card, status-badge, quantity-input, form-field) - Translation-ready +### Template Coverage + +| Area | Templates | Status | +| ---- | --------- | ------ | +| Global & Notices | 9 | Done | +| Product Archive & Loop | 15 | Done | +| Single Product | 21 | Done | +| Cart | 9 | Done | +| Checkout | 12 | Done | +| My Account | 15 | Done | +| Order Details | 5 | Done | +| Supplementary (Brands, Auth, Back-in-Stock) | 7 | Done | +| Reusable Components | 8 | Done | +| Emails | -- | Skipped (incompatible pipeline) | + ## Development ### Directory Structure ```txt wc-bootstrap/ -├── assets/css/ # Custom CSS overrides -├── assets/js/ # Custom JavaScript -├── inc/ # PHP classes (PSR-4) -├── languages/ # Translation files -├── templates/ # Bootstrap 5 Twig template overrides +├── assets/ +│ ├── css/wc-bootstrap.css # Bootstrap override styles +│ └── js/quantity.js # Quantity +/- button handler +├── inc/ +│ ├── TemplateOverride.php # WC template interception (before/after hooks) +│ └── Twig/ +│ └── WooCommerceExtension.php # WC/WP Twig functions & filters +├── languages/ # Translation files +├── templates/ # Bootstrap 5 Twig template overrides +│ ├── archive-product.html.twig +│ ├── auth/ +│ ├── brands/ +│ ├── cart/ +│ ├── checkout/ +│ ├── components/ +│ ├── global/ +│ ├── loop/ +│ ├── myaccount/ +│ ├── notices/ +│ ├── order/ +│ └── single-product/ ├── composer.json ├── functions.php └── style.css ``` +### Architecture + +```txt +WooCommerce wc_get_template("cart/cart.php") + → woocommerce_before_template_part hook + → TemplateOverride checks for cart/cart.html.twig + → Found → renders via TwigService (with WooCommerceExtension functions) + → Starts output buffer + → PHP include (captured in buffer) + → woocommerce_after_template_part hook + → TemplateOverride discards buffered PHP output + → Result: Bootstrap 5 Twig output only +``` + ### Building Translations ```bash