wp-bootstrap/README.md

# WP Bootstrap

A modern WordPress Block Theme built from scratch with Bootstrap 5. Features responsive design, dark mode support, Twig template rendering, and full compatibility with the WordPress Site Editor.

## Features

- **Bootstrap 5 Frontend** -- Proper Bootstrap 5 HTML (navbar, cards, pagination, grid) rendered via Twig templates
- **Dark Mode** -- Toggle with localStorage persistence and `prefers-color-scheme` support
- **Full Site Editing** -- Compatible with the WordPress Site Editor for admin editing
- **Block Patterns** -- 16 patterns across 7 categories (hero, features, CTA, testimonials, pricing, contact, text)
- **Block Styles** -- 17 custom styles mapping Bootstrap components to WordPress blocks
- **Style Variations** -- 4 color schemes: Ocean, Forest, Sunset, Midnight
- **Responsive** -- Mobile-first design with Bootstrap's responsive grid
- **Translation Ready** -- Full i18n support with `en_US` and `de_CH` translations

## Requirements

- WordPress 6.7 or higher
- PHP 8.3 or higher
- Composer
- Node.js 20+

## Installation

### From Release Package

1. Download the latest `.zip` from [Releases](https://src.bundespruefstelle.ch/magdev/wp-bootstrap/releases)
2. Go to WordPress Admin > Appearance > Themes > Add New > Upload Theme
3. Upload the ZIP file and activate

### From Source

```bash
git clone ssh://git@src.bundespruefstelle.ch:2022/magdev/wp-bootstrap.git
cd wp-bootstrap
composer install
npm install
npm run build
```

Activate the theme in **Appearance > Themes** in the WordPress admin.

## Development

### Prerequisites

- Node.js 20+
- npm
- Composer
- PHP 8.3+

### Build Commands

| Command | Description |
| --- | --- |
| `npm run build` | Full production build (copy JS, compile SCSS, minify CSS) |
| `npm run dev` | Watch SCSS files and recompile on changes |
| `npm run scss` | Compile SCSS only |
| `npm run postcss` | Minify CSS with Autoprefixer and cssnano |
| `composer install` | Install PHP dependencies (Twig) |

### Build Pipeline

1. `copy:js` -- Copy Bootstrap JS bundle from `node_modules` to `assets/js/`
2. `copy:theme-js` -- Copy theme JS (dark-mode.js) from `src/js/` to `assets/js/`
3. `scss` -- Compile SCSS (`src/scss/`) to CSS (`assets/css/`)
4. `postcss` -- Autoprefixer + cssnano minification to `assets/css/style.min.css`

## Architecture

### Frontend Rendering

The theme uses a dual-rendering approach:

- **Site Editor (admin):** FSE block templates in `templates/` and `parts/` for visual editing
- **Frontend (public):** Twig templates in `views/` render Bootstrap 5 HTML via the `template_redirect` hook

The `TemplateController` intercepts frontend requests and renders the appropriate Twig template with data gathered by `ContextBuilder`. FSE templates remain untouched for the WordPress admin editor.

### Key PHP Classes

| Class | Purpose |
| --- | --- |
| `TwigService` | Singleton Twig environment with WordPress functions and globals |
| `TemplateController` | Hooks `template_redirect`, resolves and renders Twig templates |
| `ContextBuilder` | Gathers WordPress data (posts, menus, pagination, comments, sidebar) |
| `NavWalker` | Converts flat menu items to nested tree for Bootstrap dropdowns |

### Navigation Menus

Register menus in **Appearance > Menus**:

- **Primary Navigation** -- Displayed in the Bootstrap navbar with dropdown support
- **Footer Navigation** -- Displayed in the footer

If no menu is assigned, the primary location falls back to listing published pages.

### Project Structure

```txt
wp-bootstrap/
+-- assets/           Compiled CSS, JS, fonts
+-- inc/
|   +-- Template/     TemplateController, ContextBuilder, NavWalker
|   +-- Twig/         TwigService singleton
+-- languages/        Translation files (.pot, .po)
+-- patterns/         Block patterns (PHP)
+-- parts/            FSE template parts (header, footer, sidebar)
+-- src/
|   +-- js/           Source JavaScript
|   +-- scss/         Source SCSS
+-- styles/           Style variations (JSON)
+-- templates/        FSE templates (HTML)
+-- views/            Twig templates (Bootstrap 5 HTML)
|   +-- base.html.twig
|   +-- pages/        Page templates (index, single, page, archive, search, 404)
|   +-- partials/     Reusable parts (header, footer, pagination, sidebar, etc.)
|   +-- components/   UI components (post card, post loop)
+-- functions.php     Theme bootstrap
+-- style.css         Theme metadata
+-- theme.json        Design tokens and settings
```

## Technology Stack

- **PHP 8.3+** with PSR-4 autoloading
- **Twig 3.0** via Composer
- **Bootstrap 5.3+** CSS & JS (served locally)
- **Dart Sass** for SCSS compilation
- **PostCSS** with Autoprefixer and cssnano

## License

GPL-2.0-or-later. See <http://www.gnu.org/licenses/gpl-2.0.html>.

## Author

Marco Graetsch - <https://src.bundespruefstelle.ch/magdev>