# Brandy WordPress Theme - Developer Documentation > **Version:** 1.5.2 > **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. --- ## 🔄 Changelog ### Version 1.5.2 - ✅ Updated: Remove darkmode from niches. - ✅ Fixed: Missing review meta. - ✅ Fixed: Button sizes not working in some niches. - ✅ Fixed: Product Details Blocks not display - ✅ Fixed: Product Details Blocks not display ### Version 1.5.1 - ✅ Fixed: Duplicate class ### Version 1.5.0 - ✅ Added: Dark Mode (alpha) - Only for default template - ✅ Added: Image loading strategy settings. - ✅ Added: Size Chart to product templates. - ✅ Added: Image Gallery Masonry Display setting. - ✅ Added: Product Image hover scale setting. - ✅ Added: Support Compare Products for niches. - ✅ Added: WooCommerce coming soon template. - ✅ Added: 3 Blogs layouts. - ✅ Added: Pill style for Post-terms block. - ✅ Added: Contact Us patterns. - ✅ Updated: Remove product variation description. - ✅ Updated: Layout for WooCommerce review form blocks - ✅ Updated: Load scripts performance. - ✅ Updated: Integrate with WC 10.4. - ✅ Updated: Image sources. - ✅ Updated: Layouts. - ✅ Updated: Site meta description. - ✅ Updated: Sample data import. - ✅ Fixed: Missing button urls. - ✅ Fixed: Minor issues. - ✅ Fixed: Product thumbnail style on Safari. - ✅ Fixed: Cannot import WooCommerce niche sample posts. - ✅ Fixed: Product Gallery blocks scrollable. - ✅ Fixed: Swatches color incorrect in Single page. - ✅ Fixed: Contact Us collapsible. ### Version 1.4.3 - ✅ Added: Auto-generate hover background for Button blocks - ✅ Added: Swatches on demo WooCommerce site - ✅ Added: Size Chart on demo WooCommerce site - ✅ Added: Breadcrumb to templates with Brandy Blocks - ✅ Added: 2 new About us templates - ✅ Added: 5 new Contact us templates - ✅ Updated: Default niche - ✅ Updated: Footer link open at same tab - ✅ Updated: Improve footer builder row settings - ✅ Updated: Gray 8 color - ✅ Updated: Improve SEO, add default tagline - ✅ Updated: WooCommerce blocks UI - ✅ Updated: Delete demo variable products when importing new site - ✅ Updated: UI - ✅ Fixed: Layout Library when changing template - ✅ Fixed: Cannot reset Socials element - ✅ Fixed: Image block width issue - ✅ Fixed: Cart/Wishlist drawer UI when using together ### Version 1.4.2 - ✅ Added: Product Image Zoom when hovering setting - ✅ Added: Newsletter subscription providers: Brevo, Mailchimp - ✅ Added: Extensions page in Brandy Dashboard - ✅ Updated: Newsletter subscribe function - ✅ Updated: Single Product Gallery preview layout - ✅ Updated: Single Product Image UX/UI (zoom, open popup,...) - ✅ Updated: UI - ✅ Updated: WooCommerce countdown button UI - ✅ Fixed: Blank page after changing layout ### Version 1.4.1 - ✅ Added: Product Image Hover Effect (Display slider & Display secondary image) - ✅ Added: Customizer setting to manage Product Image Hover Effect - ✅ Updated: Niche layouts - ✅ Updated: Woo Product Filter UI - ✅ Fixed: Archive product pattern syntax - ✅ Fixed: Box Shadow issue ### Version 1.4.0 - ✅ Added: Product filter block support - ✅ Added: Brandy Layout Library (allow user to change layout of specific template: Blog, Archive Product, Single Product) - ✅ Added: Niche styles/variants (user can select variant of niche to import) - ✅ Added: Taxonomy product template - ✅ Added: Multiple layouts for blog/archive product/single product - ✅ Added: Button sizes - ✅ Updated: Mini cart layout - ✅ Updated: Builder elements - ✅ Removed: Unused templates (pages, posts,…) ### Version 1.3.8 - ✅ Updated: Simplify builder & elements settings - ✅ Updated: Admin layouts - ✅ Updated: Default template layout - ✅ Updated: Preview site ### Version 1.0.0 - ✅ Initial release --- ## 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.3+ (tested up to 6.9) - 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
``` ### 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 ``` --- ## 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 '...'; } protected function get_default_data() { return [ 'visible' => true, 'text' => 'Your Element Text', ]; } public function render($settings, $device = 'desktop') { // Render your element echo '
' . esc_html($settings['text']) . '
'; } } ``` --- ## 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
``` --- ## 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 ``` ### 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/)