# Brandy WordPress Theme - Developer Documentation

> **Version:** 1.4.3  
> **Author:** YayCommerce  
> **License:** GPLv3 or later

Brandy is a modern WordPress Block Theme (Full Site Editing) with deep WooCommerce integration, featuring a custom React-based customizer, advanced builder system, and comprehensive e-commerce functionality.

---

## Table of Contents

- [Overview](#overview)
- [Architecture](#architecture)
- [Development Setup](#development-setup)
- [Build System](#build-system)
- [Directory Structure](#directory-structure)
- [Key Features](#key-features)
- [Development Workflow](#development-workflow)
- [Customizer System](#customizer-system)
- [Builder System](#builder-system)
- [WooCommerce Integration](#woocommerce-integration)
- [Block Settings](#block-settings)
- [Patterns & Templates](#patterns--templates)
- [Coding Standards](#coding-standards)
- [Testing](#testing)
- [Deployment](#deployment)

---

## Overview

Brandy is designed for modern WordPress development with a focus on:

- **Full Site Editing (FSE)** - Block-based theme with `theme.json` configuration
- **WooCommerce Optimization** - Custom templates, blocks, and checkout experience
- **React-Based Customizer** - Advanced customization interface built with React, TypeScript, and Vite
- **Header/Footer Builder** - Drag-and-drop builder for site structure
- **Modern Tooling** - Vite, TypeScript, SCSS, Gulp, and Composer

---

## Architecture

### Tech Stack

**Backend:**
- PHP 5.3+ with PSR-4 autoloading
- WordPress 5.0+ (tested up to 6.8.3)
- Composer for dependency management
- WooCommerce deep integration

**Frontend:**
- React 18.2+ with TypeScript
- Vite for fast development and building
- TailwindCSS + Styled Components (Twin.macro)
- SCSS with Gulp preprocessing
- Babel for JavaScript transpilation

**State Management:**
- Zustand for React state
- WordPress Customizer API integration

---

## Development Setup

### Prerequisites

```bash
# Required
- Node.js 16+ and Yarn
- PHP 5.3+
- Composer
- WordPress 5.0+
- WooCommerce (recommended)

# Optional
- WP-CLI
```

### Installation

1. **Clone or navigate to the theme directory:**

```bash
cd wp-content/themes/brandy
```

2. **Install app dependencies:**

```bash
bash run.sh dev-init
```

---

## Build System

### Development Mode

Run all development processes concurrently:

```bash
# Run specific apps
bash run.sh dev
```
This command starts:
- Customizer dev server (Vite)
- Dashboard dev server (Vite)
- Post editor dev server (Vite)
- Frontend dev server (Vite)
- SCSS watcher (Gulp)
- JS watcher (Gulp)

### Build for Production

```bash
bash run.sh release
```

---

## Directory Structure

```
brandy/
├── apps/                           # React applications
│   ├── customizer/                 # Theme customizer (React + TypeScript)
│   │   ├── src/                   # Source files
│   │   ├── vite.config.ts         # Vite configuration
│   │   └── package.json
│   ├── theme-dashboard/           # Admin dashboard
│   ├── post-editor/               # Block editor enhancements
│   └── frontend/                  # Frontend scripts
│
├── assets/                        # Compiled assets
│   ├── css/                      # Compiled stylesheets
│   ├── js/                       # Compiled scripts
│   ├── fonts/                    # Theme fonts
│   ├── images/                   # Theme images
│   └── sample-data/              # Demo content
│
├── devs/                         # Development sources
│   ├── scss/                     # SCSS source files
│   │   ├── frontend/            # Frontend styles
│   │   ├── admin/               # Admin styles
│   │   └── sharing/             # Shared styles
│   └── js/                       # JS source files
│
├── inc/                          # PHP classes (PSR-4: Brandy\)
│   ├── Abstracts/               # Abstract base classes
│   ├── Admin/                   # Admin functionality
│   ├── BlockSettings/           # Custom block settings
│   ├── BlocksOverride/          # Block modifications
│   ├── Builder/                 # Header/Footer builder
│   ├── Core/                    # Core functionality
│   ├── Customizer/              # Customizer integration
│   │   ├── Elements/           # Customizer elements
│   │   ├── Layouts/            # Layout configurations
│   │   └── Panels/             # Customizer panels
│   ├── FSE/                     # Full Site Editing handlers
│   ├── Functions/               # Template functions
│   ├── Integrations/            # Third-party integrations
│   ├── Niches/                  # Niche/industry templates
│   ├── Newsletter/              # Newsletter integrations
│   ├── Utils/                   # Helper utilities
│   └── WooCommerce/             # WooCommerce integration
│
├── patterns/                     # Block patterns (PHP)
├── parts/                        # Template parts (HTML)
├── templates/                    # Full page templates (HTML)
├── template-parts/               # PHP template partials
│   ├── builder/                 # Builder elements
│   ├── common/                  # Common components
│   ├── icons/                   # SVG icons
│   ├── flags/                   # Country flags
│   └── layouts/                 # Layout templates
│
├── woocommerce/                  # WooCommerce template overrides
│   ├── archive-product.php
│   ├── single-product/
│   ├── cart/
│   ├── checkout/
│   └── myaccount/
│
├── styles/                       # Block styles (JSON)
│   ├── default.json
│   ├── woocommerce.json
│   └── blocks/
│
├── theme.json                    # Theme configuration
├── functions.php                 # Theme entry point
├── composer.json                 # PHP dependencies
├── package.json                  # Node dependencies
├── gulpfile.js                   # Gulp task runner
└── phpcs.xml                     # PHP CodeSniffer rules
```

---

## Key Features

### 1. Full Site Editing (FSE)

The theme is built on WordPress Block Themes with:
- `theme.json` for global styles and settings
- HTML template files in `templates/` and `parts/`
- Custom block styles and variations
- Block patterns for quick page building

### 2. Custom React Customizer

Located in `apps/customizer/`:
- Built with React 18 + TypeScript
- Real-time preview integration
- Drag-and-drop header/footer builder
- Typography, colors, and spacing controls
- WooCommerce-specific settings

**Key Technologies:**
- Vite for fast builds
- Zustand for state management
- TailwindCSS + Styled Components
- React Popper for tooltips

### 3. Header & Footer Builder

PHP-based builder system in `inc/Builder/`:
- Row-based layout system
- Custom elements (logo, menu, cart, search, etc.)
- Responsive settings per row
- Off-canvas mobile menu support
- Dynamic element rendering

### 4. WooCommerce Deep Integration

Comprehensive e-commerce features:
- Custom product layouts
- Cart/Checkout customization
- Product hover effects and zoom
- Product filters and badges
- Mini cart drawer
- Wishlist integration
- Multiple checkout styles

### 5. Advanced Block Settings

Custom block enhancements in `inc/BlockSettings/`:
- Button size controls
- Post author tooltips
- Featured image placeholders
- Responsive content controls

### 6. Niches System

Pre-built templates for different industries in `inc/Niches/`:
- WooCommerce stores
- Default layouts
- Sample data import
- Custom patterns per niche

---

### 1. Creating a Block Pattern

```php
// patterns/your-pattern.php
<?php
/**
 * Title: Your Pattern
 * Slug: brandy/your-pattern
 * Categories: featured
 */
?>

<!-- wp:group -->
<div class="wp-block-group">
    <!-- Your block markup -->
</div>
<!-- /wp:group -->
```

### 2. Adding Styles

```scss
// devs/scss/frontend/_your-component.scss
.your-component {
    // Your styles
}

// Import in main.scss
@import 'your-component';
```

### 3. WooCommerce Template Override

```php
// woocommerce/your-template.php
<?php
/**
 * Your Custom WooCommerce Template
 *
 * @package Brandy
 */

defined('ABSPATH') || exit;

// Your template code
?>
```

---

## Customizer System

### Architecture

The customizer system bridges WordPress Customizer API with a React UI:

**PHP Side (`inc/Customizer/`):**
- Panel and section registration
- Settings and controls
- Partial refresh handlers
- Dynamic CSS generation

**React Side (`apps/customizer/src/`):**
- Custom control components
- Real-time preview updates
- Drag-and-drop interfaces
- State management with Zustand

### Key Components

**Panels:**
- Header Panel - Header builder and settings
- Footer Panel - Footer builder and settings
- WooCommerce Panel - Product catalog and shop settings
- General Panel - Typography, colors, buttons

**Elements (`inc/Customizer/Elements/`):**
- Logo, Menu, Cart, Search, Account
- Social icons, Newsletter, Currency switcher
- Custom HTML, Dividers, Buttons
- Payment methods, Copyright

### Adding a Custom Element

```php
// inc/Customizer/Elements/YourElement.php
namespace Brandy\Customizer\Elements;

use Brandy\Abstracts\AbstractBaseElement;

class YourElement extends AbstractBaseElement {
    protected static $element_name = 'your_element';

    protected function get_label() {
        return __('Your Element', 'brandy');
    }

    protected function get_icon() {
        return '<svg>...</svg>';
    }

    protected function get_default_data() {
        return [
            'visible' => true,
            'text' => 'Your Element Text',
        ];
    }

    public function render($settings, $device = 'desktop') {
        // Render your element
        echo '<div class="your-element">' . esc_html($settings['text']) . '</div>';
    }
}
```

---

## Builder System

### Overview

The Builder system (`inc/Builder/`) creates dynamic headers and footers:

**Components:**
- `HeaderBuilder` - Renders header rows and elements
- `FooterBuilder` - Renders footer rows and elements
- `ToggleOffCanvasBuilder` - Mobile menu drawer
- `ElementBuilder` - Renders individual elements
- `RowBuilder` - Manages row layout and settings

### Row Structure

Rows contain columns with elements:

```php
[
    'row_id' => 'unique_id',
    'layout' => 'default', // or 'left-right', 'center'
    'settings' => [
        'background' => '#ffffff',
        'padding' => ['top' => 20, 'bottom' => 20],
    ],
    'columns' => [
        'left' => ['logo', 'menu'],
        'center' => ['search'],
        'right' => ['cart', 'account'],
    ]
]
```

### Element Rendering

```php
// Template: template-parts/builder/elements/your-element.php
<?php
/**
 * Your Element Template
 *
 * @var array $settings Element settings
 * @var string $device Current device (desktop/mobile)
 */

defined('ABSPATH') || exit;

$text = $settings['text'] ?? 'Default Text';
?>

<div class="brandy-your-element" data-device="<?php echo esc_attr($device); ?>">
    <?php echo esc_html($text); ?>
</div>
```

---

## WooCommerce Integration

### Custom Templates

Override WooCommerce templates in `woocommerce/`:

**Product Loop:**
- `loop/price.php` - Custom pricing display
- `loop/rating.php` - Star ratings
- `loop/add-to-cart.php` - Add to cart button

**Single Product:**
- `single-product/tabs/` - Product tabs
- `single-product/add-to-cart/` - Add to cart variations
- `single-product/meta.php` - Product meta info

**Cart & Checkout:**
- `cart/cart.php` - Cart table
- `checkout/form-checkout.php` - Checkout form
- `checkout/payment.php` - Payment methods

### Product Catalog Service

```php
// inc/Core/Services/ProductCatalogService.php
use Brandy\Core\Services\ProductCatalogService;

// Get product settings
$catalog_settings = ProductCatalogService::get_settings();

// Example: Product image hover effect
$hover_effect = $catalog_settings['product_image_hover_effect'] ?? 'none';
```

### Custom Hooks

```php
// inc/WooCommerce/Hooks.php
add_action('woocommerce_before_shop_loop_item', 'your_custom_function');
add_filter('woocommerce_product_tabs', 'your_tabs_filter');
```

---

## Block Settings

### External Block Settings System

Located in `inc/BlockSettings/`, this system adds custom functionality to WordPress blocks:

**Interface:**
```php
// Implement ExternalBlockSettingsInterface
namespace Brandy\BlockSettings\YourSetting;

use Brandy\Interfaces\ExternalBlockSettingsInterface;

class Caller implements ExternalBlockSettingsInterface {
    public static function get_block_name() {
        return 'core/your-block';
    }

    public static function get_script_path() {
        return 'path/to/script.js';
    }

    public static function get_style_path() {
        return 'path/to/style.css';
    }
}
```

**Registration:**
```php
// inc/BlockSettings/BlockExternalsLoader.php
BlockExternalsLoader::register_external_settings([
    YourSetting\Caller::class,
]);
```

---

## Patterns & Templates

### Block Patterns

PHP-based patterns in `patterns/` directory:

```php
// patterns/example-pattern.php
<?php
/**
 * Title: Example Pattern
 * Slug: brandy/example-pattern
 * Categories: featured, call-to-action
 * Keywords: example, demo
 * Block Types: core/group
 */
?>

<!-- Your block markup here -->
```

### FSE Templates

HTML templates in `templates/`:
- `front-page.html` - Homepage
- `single-product.html` - Product page
- `archive-product.html` - Shop page
- `page-cart.html` - Cart page
- `page-checkout.html` - Checkout page

### Template Parts

Reusable parts in `parts/`:
- `mini-cart.html` - Mini cart drawer
- `pre-footer.html` - Pre-footer section

---

## Deployment

### Build for Production

```bash
# 1. Update version in style.css and readme.txt

# 2. Generate translation files
yarn make-pot

# 3. Build & Create release zip
bash run.sh release
```

### Pre-release Checklist

- [ ] Version numbers updated
- [ ] Changelog updated
- [ ] All assets built and minified
- [ ] PHP CodeSniffer passed
- [ ] JavaScript linting passed
- [ ] Manual testing completed
- [ ] Translation files generated
- [ ] Documentation updated
- [ ] Git tag created
- [ ] Release notes prepared

---

## Development Constants

### Configuration

Edit `functions.php` to change development mode:

```php
// Set to false for production
define('BRANDY_IS_DEVELOPMENT', false);
```

---

## Resources

- **WordPress Developer Resources**: https://developer.wordpress.org/
- **WooCommerce Developer Docs**: https://woocommerce.com/documentation/plugins/woocommerce/
- **React Documentation**: https://react.dev/
- **Vite Documentation**: https://vitejs.dev/
- **TailwindCSS**: https://tailwindcss.com/

---

## Support & Contributing

### Getting Help

- Check the documentation in the theme dashboard
- Review inline code comments
- Refer to WordPress and WooCommerce documentation

### Contributing

When contributing to the theme:

1. Follow the coding standards above
2. Write clear commit messages
3. Test thoroughly before committing
4. Update documentation for new features
5. Run linters before submitting

---

## License

This theme, like WordPress, is licensed under the **GPL v3 or later**.

```
Brandy WordPress Theme
Copyright (C) 2025 YayCommerce

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
```

---

## Changelog

See `changelog.txt` for version history and updates.

---

**Happy Coding! 🚀**

For more information, visit [wpbrandy.com](https://wpbrandy.com/) or [yaycommerce.com](https://yaycommerce.com/)