wc-bootstrap/SETUP.md

WP Bootstrap Child Theme Template -- Setup Guide

This template creates a Bootstrap 5 child theme for the wp-bootstrap parent theme that overrides a WordPress plugin's Twig templates with Bootstrap 5 markup.

Placeholders Reference

Search and replace these placeholders across all files when instantiating a new project:

Project Identity

Placeholder	Description	Example
WooCommerce Bootstrap	Human-readable theme name	WP JobRoom Theme
wc-bootstrap	WordPress theme directory name (kebab-case)	wp-jobroom-theme
wc-bootstrap	WordPress text domain for i18n	wp-jobroom-theme
WC_BOOTSTRAP	PHP constant prefix (UPPER_SNAKE_CASE)	WP_JOBROOM_THEME
wc_bootstrap	PHP function prefix (lower_snake_case)	wp_jobroom_theme
WcBootstrap	PSR-4 PHP namespace	WPJobroomTheme
magdev	Composer vendor name	magdev

Plugin (upstream dependency)

Placeholder	Description	Example
WooCommerce	Human-readable plugin name	WP JobRoom
woocommerce	Plugin directory/handle name	wp-jobroom
woocommerce	Plugin text domain	wp-jobroom
Magdev\Woocommerce	Plugin PHP namespace	Magdev\WpJobroom
https://github.com/woocommerce/woocommerce.git	Plugin repository URL	https://src.example.com/user/wp-myplugin
woocommerce_render_page	Plugin's render page filter name	wp_jobroom_render_page
woocommerce_is_theme_wrapped	Plugin's is-wrapped filter name	wp_jobroom_is_theme_wrapped

Author & Repository

Placeholder	Description	Example
Marco Grätsch	Author's full name	Marco Graetsch
magdev3.0@gmail.com	Author's email	magdev3.0@gmail.com
https://src.bundespruefstelle.ch/magdev	Author's website URL	https://src.example.com/user
ssh://git@src.bundespruefstelle.ch:2022/magdev/wc-bootstrap.git	Theme repository URL	https://src.example.com/user/wp-myplugin-theme
ssh://git@src.bundespruefstelle.ch:2022/magdev/wc-bootstrap.git/issues	Issues tracker URL	https://src.example.com/user/wp-myplugin-theme/issues
https://src.bundespruefstelle.ch/magdev/wp-bootstrap	Parent theme repository URL	https://src.example.com/user/wp-bootstrap

Infrastructure

Placeholder	Description	Example
woocommerce-wordpress	Docker container name for WP-CLI	myplugin-wordpress

Files to Customize

After replacing placeholders, these files need project-specific customization:

Required Changes

1. inc/TemplateOverride.php -- Update the use import to match your plugin's actual Template class path (line: use Magdev\Woocommerce\Frontend\Template;)

2. functions.php -- Review and adapt:

   • CSS dependency array in enqueue_styles() -- add plugin style handles
   • Filter hooks -- match your plugin's actual filter names
   • Remove or adapt features you don't need (sticky header, register page, etc.)

3. composer.json -- Verify namespace mapping matches your inc/ directory structure

4. style.css -- Update the header to match your theme's specifics

5. .gitea/workflows/release.yml -- Update theme name in release title

Optional Additions

6. inc/ProfileMenu.php -- Create if your plugin has a navigation menu that needs Bootstrap 5 conversion (use wp-jobroom-theme's ProfileMenu.php as reference)

7. assets/css/theme-overrides.css -- Rename to wc-bootstrap.css and add plugin-specific CSS class overrides mapping to Bootstrap 5

8. templates/ -- Add template overrides mirroring your plugin's template structure

Architecture Overview

wp-bootstrap (parent theme, Bootstrap 5 FSE + Twig rendering)
  +-- wc-bootstrap (child theme, overrides plugin Twig templates with Bootstrap 5)
        +-- woocommerce (plugin, provides post types, logic, base Twig templates)

Template Override Flow

1. Plugin registers Twig FilesystemLoader with its templates/ directory
2. Child theme's TemplateOverride hooks init at priority 20 (after plugin at 0)
3. prependPath() adds child theme's templates/ before plugin's
4. Twig resolves templates: child theme first, plugin as fallback

Page Rendering Flow

1. Plugin's Router catches a request and renders plugin content via Twig
2. Plugin fires woocommerce_render_page filter with pre-rendered HTML
3. Child theme's render_page() intercepts, delegates to parent theme's TwigService
4. Parent theme wraps content in its page shell (header, footer, navigation)
5. _theme_wrapped context flag tells plugin templates to suppress their own wrapper

CSS Cascade

1. wp-bootstrap (parent) -- Bootstrap 5 framework
2. woocommerce -- Plugin's custom CSS
3. wc-bootstrap-style -- Child theme style.css (metadata)
4. wc-bootstrap-overrides -- Bootstrap 5 overrides for plugin classes

Plugin Requirements

For this template to work, the plugin must:

1. Use Twig with FilesystemLoader -- for template overriding via prependPath()
2. Expose a singleton Template class -- so the child theme can access the Twig environment
3. Fire a render page filter -- so the child theme can delegate rendering to the parent theme
4. Fire an is-wrapped filter -- so plugin templates know to suppress their outer wrapper
5. Register its styles with a known handle -- for CSS dependency chain ordering

Quick Start

# 1. Clone/copy this template
cp -r wp-theme-template/ wp-content/themes/my-new-theme/

# 2. Replace all placeholders (example using sed)
cd wp-content/themes/my-new-theme/
find . -type f \( -name "*.php" -o -name "*.md" -o -name "*.css" -o -name "*.json" -o -name "*.yml" -o -name "*.twig" \) \
  -exec sed -i 's/WooCommerce Bootstrap/My Plugin Theme/g' {} +
# ... repeat for all placeholders

# 3. Rename the CSS override file
mv assets/css/theme-overrides.css assets/css/my-plugin-theme.css

# 4. Install dependencies
composer install

# 5. Initialize git
git init && git checkout -b dev
git add . && git commit -m "Initial theme scaffold"

# 6. Start overriding plugin templates in templates/

Common Patterns

Adding a New Template Override

1. Find the plugin's template in plugins/woocommerce/templates/path/file.html.twig
2. Create the same path in themes/wc-bootstrap/templates/path/file.html.twig
3. Convert HTML to Bootstrap 5 components
4. Preserve all context variables and block names from the original
5. Preserve plugin JS-bound CSS classes (repeater fields, interactive widgets)

Layout Hierarchy

base.html.twig              -- Notifications, breadcrumbs, container wrapping
  +-- layouts/page.html.twig     -- Standard content pages
  +-- layouts/form.html.twig     -- Auth and edit forms (centered card)
  +-- layouts/single.html.twig   -- Detail pages (8+4 with sidebar)
  +-- layouts/archive.html.twig  -- Search/list pages (3+9 with filters)
  +-- layouts/account.html.twig  -- User account pages

Bootstrap 5 Component Mappings

Plugin Pattern	Bootstrap 5 Equivalent
Custom button classes	btn btn-primary, btn-outline-*
Custom alert/notification	alert alert-* with alert-dismissible
Custom grid system	row, col-*, row-cols-*
Custom form fields	form-control, form-floating, form-select
Custom cards	card, card-body, card-title
Custom modal/dialog	modal, modal-dialog, modal-content
Custom dropdown	dropdown, dropdown-menu, data-bs-toggle
Custom tabs	nav-tabs, tab-content, tab-pane
Custom pagination	pagination, page-item, page-link
Custom breadcrumb	breadcrumb, breadcrumb-item