# Bandsintown WordPress Plugin - Detailed Structure Documentation

## 📁 Plugin Directory: `/wp-content/plugins/bandsintown/`

### 🏗️ **Architecture Overview**
The Bandsintown WordPress plugin follows a modular architecture combining legacy WordPress functionality with modern Gutenberg block editor integration. The structure is designed for maintainability, extensibility, and compatibility across different WordPress versions.

---

## 📂 **Directory Structure with Detailed Comments**

```
/wp-content/plugins/bandsintown/
├── 📁 blocks/                                   # Modern Gutenberg Block Editor Integration
│   │                                           # Developed by: Dirox Team
│   │                                           # Purpose: Provides drag-&-drop widget functionality in WordPress Block Editor
│   │                                           # Technology: React JSX, ES6+ JavaScript, CSS3
│   │
│   ├── 📄 bandsintown-block.js                 # Primary Block Editor JavaScript Module
│   │                                           # - Registers Gutenberg block with WordPress
│   │                                           # - Handles block attributes and controls
│   │                                           # - Manages block preview and editor interface
│   │                                           # - Integrates with widget-panel-config.json for dynamic attributes
│   │                                           # - File Size: ~686 lines of ES6+ JavaScript
│   │                                           # - Dependencies: WordPress block editor APIs (@wordpress/blocks, @wordpress/components)
│   │
│   ├── 📄 bandsintown-block.css                # Block Editor Specific Styling
│   │                                           # - Styles for Gutenberg editor interface
│   │                                           # - Block preview styling in editor
│   │                                           # - Admin panel form controls styling
│   │                                           # - File Size: ~105 lines of CSS3
│   │                                           # - Scope: Editor-only styles (not frontend)
│   │
│   └── 📄 README.md                            # Block Development Documentation
│                                               # - Block registration process
│                                               # - Attribute handling guidelines
│                                               # - Development setup instructions
│                                               # - Component architecture documentation
│
├── 📁 public/                                  # Frontend Assets & Core Logic
│   │                                           # Developed by: Dirox Team
│   │                                           # Purpose: Contains all public-facing functionality and shared utilities
│   │                                           # Architecture: PHP backend + JavaScript frontend + JSON configuration
│   │
│   ├── 📄 common.php                           # Core PHP Helper Functions Library
│   │                                           # - JSON configuration file parser
│   │                                           # - Widget attribute processing and sanitization
│   │                                           # - Default settings management
│   │                                           # - Block render callback functions
│   │                                           # - WordPress hooks and filters integration
│   │                                           # - Data validation and security functions
│   │                                           # - File Size: ~266 lines of PHP 7.4+ code
│   │                                           # - Key Functions:
│   │                                           #   * bandsintown_get_widget_json_data(): Loads widget configuration
│   │                                           #   * bandsintown_render_bandsintown_block(): Main block renderer
│   │                                           #   * bandsintown_get_all_widget_setting_inputs(): Attribute manager
│   │
│   ├── 📄 public.js                            # Frontend JavaScript Functionality
│   │                                           # - Widget initialization and DOM manipulation
│   │                                           # - Event handling for user interactions
│   │                                           # - AJAX communication with Bandsintown API
│   │                                           # - Progressive enhancement for non-JS users
│   │                                           # - Performance optimization (lazy loading, caching)
│   │                                           # - File Size: ~301 lines of vanilla JavaScript
│   │                                           # - Compatibility: ES5+ for broad browser support
│   │                                           # - Dependencies: None (vanilla JavaScript)
│   │
│   ├── 📄 style.css                            # Frontend Widget Styling
│   │                                           # - Complete visual theme for Bandsintown widgets
│   │                                           # - Responsive design (mobile, tablet, desktop)
│   │                                           # - CSS custom properties for theming
│   │                                           # - Cross-browser compatibility styles
│   │                                           # - Dark/light theme support
│   │                                           # - File Size: ~800 lines of CSS3
│   │                                           # - Methodology: BEM naming convention
│   │                                           # - Features:
│   │                                           #   * Responsive grid layouts
│   │                                           #   * Smooth animations and transitions
│   │                                           #   * Accessibility compliance (WCAG 2.1)
│   │                                           #   * Print media styles
│   │
│   └── 📄 widget-panel-config.json             # Widget Configuration Schema
│                                               # - Centralized attribute definitions
│                                               # - UI control specifications (input types, validation rules)
│                                               # - Default values and constraints
│                                               # - Internationalization support
│                                               # - File Size: ~575 lines of structured JSON
│                                               # - Structure:
│                                               #   * Panel definitions with grouped controls
│                                               #   * Attribute metadata (type, default, validation)
│                                               #   * UI component configuration
│                                               #   * API endpoint specifications
│
├── 📁 views/                                   # Legacy Template System
│   │                                           # Status: Deprecated in current version
│   │                                           # Purpose: Originally contained widget display templates
│   │                                           # Migration: Functionality moved to common.php render functions
│   │
│   └── 📄 widget-form.php                      # Legacy Widget Admin Form Template
│                                               # Status: UNUSED in current version (v1.4.0)
│                                               # Historical Purpose: Generated admin widget configuration forms
│                                               # Replacement: Modern Gutenberg block interface in blocks/
│                                               # Retention Reason: Backward compatibility reference
│                                               # File Size: ~150 lines of PHP/HTML
│                                               # Note: May be removed in future major version
│
├── 📄 bandsintown.php                          # WordPress Plugin Bootstrap & Core
│                                               # Role: Primary plugin entry point and orchestrator
│                                               # Responsibilities:
│                                               # - Plugin header and metadata declaration
│                                               # - WordPress hooks registration (init, admin_init, etc.)
│                                               # - Shortcode registration and handling
│                                               # - Admin settings page creation
│                                               # - Gutenberg block registration
│                                               # - Asset enqueueing (CSS/JS)
│                                               # - Plugin activation/deactivation hooks
│                                               # - Database schema management
│                                               # - Security and capability checks
│                                               # File Size: ~360 lines of PHP 7.4+
│                                               # WordPress Standards: Follows WordPress Coding Standards
│                                               # Plugin Header Information:
│                                               #   * Plugin Name: Bandsintown Events
│                                               #   * Version: 1.4.0
│                                               #   * Requires: WordPress 5.8+
│                                               #   * Tested up to: WordPress 6.3
│                                               #   * PHP Version: 7.4+
│
├── 📄 bandsintown.css                          # Legacy Plugin Stylesheet
│                                               # Status: Legacy support file
│                                               # Purpose: Backward compatibility with pre-v3 widgets
│                                               # Content: Basic styling for legacy shortcode implementations
│                                               # File Size: ~50 lines of CSS
│                                               # Usage: Automatically loaded for legacy widget support
│                                               # Migration Path: Will be deprecated in favor of public/style.css
│                                               # Maintenance: Minimal updates, preservation-focused
│
├── 📄 favicon.png                              # Bandsintown Brand Icon
│                                               # Dimensions: 16x16px, 32x32px (multi-resolution)
│                                               # Usage: WordPress admin dashboard plugin icon
│                                               # Format: PNG with transparency
│                                               # Brand Guidelines: Official Bandsintown branding
│                                               # File Size: ~2KB optimized
│
├── 📄 bg_headline_long.gif                     # Legacy Header Background Image
│                                               # Status: Legacy asset from earlier plugin versions
│                                               # Dimensions: 468x60px
│                                               # Usage: Header background for legacy widget layouts
│                                               # Format: Animated GIF
│                                               # Maintenance: Preserved for backward compatibility
│                                               # File Size: ~15KB
│
├── 📄 btn_buytix.gif                           # Legacy "Buy Tickets" Button Image
│                                               # Status: Legacy UI element
│                                               # Purpose: Ticket purchase call-to-action button
│                                               # Dimensions: 120x30px
│                                               # Replacement: Modern CSS buttons in public/style.css
│                                               # Format: GIF with animation
│                                               # File Size: ~3KB
│
└── 📄 readme.txt                               # WordPress.org Plugin Repository Documentation
                                                # Format: WordPress.org standard readme format
                                                # Sections:
                                                # - Plugin description and features
                                                # - Installation instructions
                                                # - Frequently Asked Questions (FAQ)
                                                # - Changelog and version history
                                                # - Upgrade notices and compatibility notes
                                                # - Screenshots and usage examples
                                                # - Support and contribution guidelines
                                                # Audience: WordPress.org plugin directory users
                                                # Maintenance: Updated with each plugin release
                                                # File Size: ~200 lines of structured text
```

---

## 🔧 **Technical Architecture Details**

### **Frontend Architecture**
```
User Interface Layer (Browser)
    ↓
JavaScript Integration (public.js)
    ↓
WordPress Block Editor (blocks/)
    ↓
PHP Rendering Engine (common.php)
    ↓
Bandsintown Widget API v3 (External)
```

### **Configuration Flow**
```
widget-panel-config.json
    ↓
common.php (Processing)
    ↓
bandsintown-block.js (UI Controls)
    ↓
bandsintown.php (Registration)
    ↓
WordPress Core (Integration)
```

### **Asset Loading Strategy**
1. **Admin Context**: `bandsintown-block.css` + `bandsintown-block.js`
2. **Frontend Context**: `style.css` + `public.js`
3. **Legacy Support**: `bandsintown.css` (conditional)
4. **External Dependencies**: Bandsintown Widget v3 API

---

## 📊 **File Metrics & Dependencies**

| File | Type | Size | Primary Function | Dependencies |
|------|------|------|------------------|--------------|
| `bandsintown.php` | PHP | 360 lines | Plugin Bootstrap | WordPress Core APIs |
| `blocks/bandsintown-block.js` | JavaScript | 686 lines | Gutenberg Integration | @wordpress/blocks, @wordpress/components |
| `public/common.php` | PHP | 266 lines | Core Logic | JSON extension, WordPress APIs |
| `public/style.css` | CSS | 800 lines | Frontend Styling | CSS3, Custom Properties |
| `public/public.js` | JavaScript | 301 lines | Frontend Behavior | Vanilla JS (no dependencies) |
| `widget-panel-config.json` | JSON | 575 lines | Configuration Schema | JSON specification |

---

## 🚀 **Development Guidelines**

### **Adding New Features**
1. **Configuration**: Update `widget-panel-config.json` with new attributes
2. **Processing**: Add handling logic in `common.php`
3. **UI Controls**: Extend `bandsintown-block.js` for editor interface
4. **Styling**: Add styles to `public/style.css`
5. **Registration**: Update `bandsintown.php` if needed

### **Maintenance Priorities**
- **High Priority**: `public/` directory (active development)
- **Medium Priority**: `blocks/` directory (feature enhancements)
- **Low Priority**: `views/` directory (legacy support)
- **Preservation**: Legacy assets (compatibility)

### **Performance Considerations**
- **Lazy Loading**: External widget scripts loaded on-demand
- **Caching**: JSON configuration cached per request
- **Minification**: Production builds should minify CSS/JS assets
- **CDN**: Static assets served via Bandsintown CDN