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

```txt
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

```txt
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

```bash
# 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

```txt
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` |