You've already forked wc-bootstrap
Initial theme scaffold from wp-theme-template
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
182
SETUP.md
Normal file
182
SETUP.md
Normal file
@@ -0,0 +1,182 @@
|
||||
# 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` |
|
||||
Reference in New Issue
Block a user