# Frontend Components Implementation

## Overview

This document covers the implementation of P1-52 to P1-54: Frontend components for the Multilingual Press Zone plugin.

---

## Components

### P1-52: Language Switcher Widget

**File:** `includes/Frontend/LanguageSwitcher.php`

A WordPress widget that provides language switching functionality with three display modes.

#### Features

- **WordPress Widget:** Extends `WP_Widget` for easy integration
- **Three Display Modes:**
  - **Dropdown:** Select-based language switcher
  - **Flags:** Visual flag-based switcher with Circle Flags CDN
  - **List:** Vertical list with optional flags
- **Configuration Options:**
  - Widget title
  - Display mode selection
  - Toggle flag display
  - Show current language only (flags mode)
- **Accessibility:** Full keyboard navigation and ARIA support
- **Flag Support:** Uses Circle Flags CDN for SVG flag icons
- **Flag Emojis:** Regional indicator symbols for dropdown mode

#### Usage

```php
// Programmatic usage
$widget = new \MultilingualPressZone\Frontend\LanguageSwitcher();

// Widget is auto-registered via widgets_init hook
// Available in Appearance > Widgets
```

#### Shortcode Support

The widget can be displayed via shortcode:

```
[mpz_language_switcher display_mode="dropdown" show_flags="1"]
```

---

### P1-53: URL Manager

**File:** `includes/Frontend/URLManager.php`

Manages multilingual URLs with three different URL structure modes.

#### URL Modes

1. **Subdirectory Mode** (Default)
   - Format: `https://example.com/es/about/`
   - Default language has no prefix
   - SEO-friendly
   - Best for most sites

2. **Subdomain Mode**
   - Format: `https://es.example.com/about/`
   - Each language gets own subdomain
   - Good for large multilingual sites
   - Requires DNS configuration

3. **Parameter Mode**
   - Format: `https://example.com/about/?lang=es`
   - Query parameter based
   - Easiest to implement
   - Not as SEO-friendly

#### Key Methods

```php
// Get current language from URL
$current = $url_manager->getCurrentLanguage();

// Get translated URL
$translated_url = $url_manager->getTranslatedURL($original_url, 'es');

// Remove language markers
$clean_url = $url_manager->removeLanguageFromURL($url);

// Get/set URL mode
$mode = $url_manager->getURLMode();
$url_manager->setURLMode('subdirectory');

// Get language-specific home URL
$home_url = $url_manager->getHomeURL('es');
```

#### Language Detection Priority

1. URL structure (subdirectory/subdomain/parameter)
2. Current language setting in LanguageManager
3. Default language fallback

---

### P1-54: Content Filter

**File:** `includes/Frontend/ContentFilter.php`

Automatically filters WordPress content by language.

#### Features

- **Post Filtering:** Filters main query via `pre_get_posts`
- **Page Filtering:** Filters pages via `get_pages`
- **Menu Filtering:** Filters menu items via `wp_get_nav_menu_items`
- **Permalink Filtering:** Adds language to permalinks
- **Home URL Filtering:** Language-aware home URLs
- **Archive Filtering:** Language-filtered archives

#### Filters Applied

```php
// Post query filtering
add_action('pre_get_posts', [$this, 'filterPosts'], 10);

// Page filtering
add_filter('get_pages', [$this, 'filterPages'], 10, 2);

// Menu filtering
add_filter('wp_get_nav_menu_items', [$this, 'filterMenuItems'], 10, 3);

// Permalink filtering
add_filter('post_link', [$this, 'filterPermalink'], 10, 2);
add_filter('page_link', [$this, 'filterPermalink'], 10, 2);
add_filter('post_type_link', [$this, 'filterPermalink'], 10, 2);

// Home URL filtering
add_filter('home_url', [$this, 'filterHomeURL'], 10, 4);

// Archive filtering
add_filter('getarchives_where', [$this, 'filterArchivesWhere'], 10, 2);
```

#### Configuration

```php
// Enable filtering for custom post types
add_filter('mpz_filterable_post_types', function($types) {
    $types[] = 'custom_post_type';
    return $types;
});

// Enable fallback to default language
add_filter('mpz_enable_fallback', '__return_true');

// Filter secondary queries
add_filter('mpz_filter_secondary_queries', '__return_true');
```

#### Programmatic Control

```php
// Disable filtering temporarily
$content_filter->unregister();

// Re-enable filtering
$content_filter->register();
```

---

## CSS Styling

**File:** `assets/css/language-switcher.css`

Comprehensive styles for all display modes.

### Features

- **Dropdown Styles:** Custom select styling with arrow indicator
- **Flag Styles:** Circular flag icons with hover effects
- **List Styles:** Vertical list with hover states
- **Dark Mode:** `prefers-color-scheme: dark` support
- **Responsive:** Mobile-optimized breakpoints
- **Accessibility:**
  - `prefers-reduced-motion` support
  - `prefers-contrast: high` support
  - Focus visible outlines
  - Keyboard navigation support

### Theme Customization

Themes can override styles by creating:

```
wp-content/themes/your-theme/mpz-language-switcher.css
```

This file will be automatically loaded after the default styles.

---

## Integration

### Plugin.php Integration

The frontend components are automatically initialized in `includes/Core/Plugin.php`:

```php
private function init_frontend(): void {
    // Register frontend assets
    $asset_loader = new \MultilingualPressZone\Frontend\AssetLoader();
    $asset_loader->register();

    // Register language switcher widget
    add_action('widgets_init', function() {
        \MultilingualPressZone\Frontend\LanguageSwitcher::register();
    });

    // Initialize content filter
    $content_filter = new \MultilingualPressZone\Frontend\ContentFilter(
        $this->language_manager,
        $this->content_manager
    );
    $content_filter->register();
}
```

### Global Access

The plugin instance is globally accessible:

```php
global $mpz_plugin;
$language_manager = $mpz_plugin->get_language_manager();
```

---

## Testing

### Manual Testing

1. **Widget Registration**
   - Go to Appearance > Widgets
   - Verify "Language Switcher" widget is available
   - Drag to sidebar
   - Configure options

2. **Display Modes**
   - Test dropdown mode with flags
   - Test flags mode (show all/current only)
   - Test list mode with/without flags

3. **URL Modes**
   - Test subdirectory mode: `/es/page/`
   - Test subdomain mode: `es.example.com/page/`
   - Test parameter mode: `/page/?lang=es`

4. **Content Filtering**
   - Create posts in different languages
   - Verify only current language posts show
   - Test menu filtering
   - Test permalink filtering

### Automated Testing

Run verification script:

```bash
php tmp/verify-frontend-files.php
```

Expected output: All checks should pass ✓

---

## File Structure

```
multilingual-press-zone/
├── includes/
│   └── Frontend/
│       ├── LanguageSwitcher.php    # WordPress widget (P1-52)
│       ├── URLManager.php           # URL handling (P1-53)
│       ├── ContentFilter.php        # Query filtering (P1-54)
│       └── AssetLoader.php          # Asset enqueuing
├── assets/
│   └── css/
│       └── language-switcher.css    # Frontend styles
└── tmp/
    └── verify-frontend-files.php    # Verification script
```

---

## API Reference

### LanguageSwitcher

```php
class LanguageSwitcher extends \WP_Widget {
    public function widget($args, $instance): void
    public function form($instance): void
    public function update($new_instance, $old_instance): array
    public static function register(): void
}
```

### URLManager

```php
class URLManager {
    public function __construct(LanguageManager $language_manager)
    public function getCurrentLanguage(): ?Language
    public function getTranslatedURL(string $url, string $language_code): string
    public function removeLanguageFromURL(string $url): string
    public function getURLMode(): string
    public function setURLMode(string $mode): void
    public function getHomeURL(string $language_code): string
}
```

### ContentFilter

```php
class ContentFilter {
    public function __construct(LanguageManager $language_manager, ContentManager $content_manager)
    public function register(): void
    public function unregister(): void
    public function filterPosts(\WP_Query $query): void
    public function filterPages(array $pages, array $args): array
    public function filterMenuItems(array $items, $menu, array $args): array
    public function filterPermalink(string $permalink, $post): string
    public function filterHomeURL(string $url, string $path, $orig_scheme, $blog_id): string
    public function getFallbackContent(int $post_id, string $language_code): ?int
}
```

---

## WordPress Integration

### Widget Areas

The Language Switcher widget can be added to any widget area:

- Sidebars
- Footer areas
- Header widget zones
- Custom widget areas

### Menu Integration

For menu integration, use the widget or custom menu items with language-specific URLs.

### Theme Integration

Themes can integrate the language switcher directly:

```php
// Display in theme template
if (function_exists('the_widget')) {
    the_widget('MultilingualPressZone\Frontend\LanguageSwitcher', [
        'title' => 'Languages',
        'display_mode' => 'flags',
        'show_flags' => true,
    ]);
}
```

---

## Security

All components follow WordPress security best practices:

- **Output Escaping:** All output uses `esc_html()`, `esc_attr()`, `esc_url()`
- **Input Sanitization:** All input uses `sanitize_text_field()`, etc.
- **Nonce Verification:** Widget form uses WordPress nonce system
- **SQL Injection Prevention:** Uses `$wpdb->prepare()` for queries
- **XSS Prevention:** No unescaped user input
- **CSRF Protection:** WordPress admin security

---

## Performance

### Caching

- Language queries use 4-layer cache (static, object, transient, database)
- URL generation is lightweight
- CSS is minified and cached by browser

### Optimization

- Lazy loading for flag images
- Conditional script loading
- No inline CSS (all in external file)
- Minimal DOM queries

---

## Browser Support

- Modern browsers (Chrome, Firefox, Safari, Edge)
- IE11+ for basic functionality
- Progressive enhancement for older browsers
- Graceful degradation with JavaScript disabled (noscript support)

---

## Accessibility

- WCAG 2.1 Level AA compliant
- Keyboard navigation support
- Screen reader friendly
- Focus visible indicators
- ARIA labels and attributes
- Semantic HTML structure

---

## Troubleshooting

### Widget Not Showing

1. Check plugin is activated
2. Verify widget is registered: `print_r($wp_widget_factory->widgets)`
3. Check theme has widget areas
4. Clear WordPress cache

### URLs Not Working

1. Verify URL mode setting
2. Flush rewrite rules: Settings > Permalinks > Save
3. Check language is active
4. Test with different URL modes

### Content Not Filtering

1. Verify content has language meta key (`_mpz_language`)
2. Check current language is detected
3. Test with admin queries disabled
4. Enable debugging to see query modifications

---

## Future Enhancements

- AJAX language switching (no page reload)
- Language switcher in admin bar
- More display mode options
- Custom flag upload support
- RTL language support enhancements
- Translation memory integration

---

## Changelog

### Version 1.0.0

- ✓ P1-52: Language Switcher Widget implemented
- ✓ P1-53: URL Manager with 3 modes implemented
- ✓ P1-54: Content Filter implemented
- ✓ Frontend CSS with dark mode support
- ✓ Accessibility features
- ✓ Responsive design
- ✓ Widget registration
- ✓ Integration in Plugin.php

---

## Credits

- **Flag Icons:** [Circle Flags](https://github.com/HatScripts/circle-flags) by HatScripts (MIT License)
- **Flag Emojis:** Unicode Regional Indicator Symbols

---

## Support

For issues or questions:

1. Check documentation
2. Review verification script output
3. Check WordPress debug.log
4. Contact Press.Zone support