# Admin Integration Quick Start

## What Was Built

Created **7 PHP controllers** that integrate the Vanilla JS admin interface with WordPress:

### Controllers Created
1. `DashboardController.php` - Main dashboard
2. `LanguagesController.php` - Language management
3. `TranslationsController.php` - Translation management
4. `SettingsController.php` - Plugin settings
5. `LicensingController.php` - License activation
6. `MenuController.php` - Admin menu registration
7. `AssetLoader.php` - Centralized asset loading

---

## How It Works

### 1. WordPress Initialization
```
WordPress loads plugin
  → Plugin.php::init()
  → init_admin() (if in admin)
  → MenuController::register()
  → AssetLoader::register()
```

### 2. Menu Registration
```
MenuController adds admin_menu hook
  → Creates "Multilingual" menu
  → Adds 5 submenu pages
  → Routes to appropriate controllers
```

### 3. Page Rendering
```
User clicks menu item
  → WordPress calls render method
  → Controller outputs container div
  → WordPress enqueues scripts/styles
  → JavaScript takes over rendering
```

### 4. Asset Loading
```
admin_enqueue_scripts hook fires
  → AssetLoader checks if plugin page
  → Loads common bundle (runtime.js)
  → Loads admin.css
  → Provides global config (mpzConfig)
  → Controller adds page-specific data
```

---

## JavaScript Integration

Each page gets TWO global objects:

### 1. mpzConfig (All Pages)
```javascript
{
  restUrl: 'https://site.com/wp-json/multilingual-press-zone/v1/',
  restNonce: 'abc123...',
  ajaxUrl: 'https://site.com/wp-admin/admin-ajax.php',
  pluginUrl: 'https://site.com/wp-content/plugins/multilingual-press-zone/',
  version: '1.0.0',
  darkMode: false,
  i18n: {
    save: 'Save',
    cancel: 'Cancel',
    delete: 'Delete',
    // ... 25+ strings
  }
}
```

### 2. Page-Specific Data
- `mpzDashboard` - Dashboard stats and languages
- `mpzLanguages` - Language list and available options
- `mpzTranslations` - Translation data
- `mpzSettings` - Plugin configuration
- `mpzLicensing` - License information

---

## Using in JavaScript

### Example: Dashboard Component
```javascript
// Access global config
const { restUrl, restNonce } = window.mpzConfig;

// Access page data
const { languages, stats } = window.mpzDashboard;

// Make REST API call
fetch(`${restUrl}languages`, {
  headers: {
    'X-WP-Nonce': restNonce
  }
})
  .then(res => res.json())
  .then(data => {
    // Handle response
  });

// Use i18n strings
const saveButton = document.createElement('button');
saveButton.textContent = window.mpzConfig.i18n.save;
```

---

## File Structure

```
includes/
└── Admin/
    ├── AssetLoader.php          ← Loads JS/CSS
    ├── MenuController.php       ← Creates menu
    ├── DashboardController.php  ← Dashboard page
    ├── LanguagesController.php  ← Languages page
    ├── TranslationsController.php ← Translations page
    ├── SettingsController.php   ← Settings page
    └── LicensingController.php  ← Licensing page

admin/
└── dist/
    ├── css/
    │   └── admin.css           ← Compiled styles
    └── js/
        ├── runtime.js          ← Common code
        └── main.js             ← Page bundles
```

---

## Testing

### 1. Check PHP Syntax
```bash
php -l includes/Admin/MenuController.php
```

### 2. Activate Plugin in WordPress
Navigate to: Plugins → Multilingual Press Zone → Activate

### 3. Check Admin Menu
Look for "Multilingual" menu item with translation icon

### 4. Test Each Page
- Click Dashboard - should see `#mpz-dashboard-root` div
- Click Languages - should see `#mpz-languages-root` div
- Click Translations - should see `#mpz-translations-root` div
- Click Settings - should see `#mpz-settings-root` div
- Click Licensing - should see `#mpz-licensing-root` div

### 5. Check Console
Open browser console, verify:
```javascript
console.log(window.mpzConfig);
console.log(window.mpzDashboard); // On dashboard page
console.log(window.mpzLanguages); // On languages page
// etc.
```

---

## Security Features

### Capability Checks
Every controller checks `manage_options` before rendering

### Nonces
- REST API nonces: `wp_create_nonce('wp_rest')`
- Provided via `mpzConfig.restNonce`

### Output Escaping
- Text: `esc_html()`
- Attributes: `esc_attr()`
- URLs: `esc_url()`

---

## Customization

### Add New Admin Page

1. **Create Controller**
```php
// includes/Admin/MyPageController.php
namespace MultilingualPressZone\Admin;

class MyPageController {
    public function render(): void {
        echo '<div id="mpz-mypage-root"></div>';
    }

    public function enqueue_assets(): void {
        wp_localize_script('mpz-mypage', 'mpzMyPage', [
            'data' => 'value'
        ]);
    }
}
```

2. **Register in MenuController**
```php
// In add_menu_pages()
add_submenu_page(
    'multilingual-press-zone',
    __('My Page', 'multilingual-press-zone'),
    __('My Page', 'multilingual-press-zone'),
    'manage_options',
    'mpz-mypage',
    [$this, 'render_mypage']
);
```

3. **Add Render Method**
```php
// In MenuController
public function render_mypage(): void {
    $controller = new MyPageController();
    $controller->render();
}
```

---

## Troubleshooting

### Menu Doesn't Appear
- Check capability: Current user must have `manage_options`
- Verify Plugin.php calls MenuController::register()
- Clear cache and reload

### JavaScript Not Loading
- Check hook name in AssetLoader::is_plugin_page()
- Verify file paths in wp_enqueue_script()
- Check browser console for 404 errors

### Data Not Available
- Verify controller's enqueue_assets() is called
- Check wp_localize_script() call
- Inspect page source for script tag with data

### Nonce Errors
- Ensure REST API is enabled
- Check user is logged in
- Verify nonce generation in controller

---

## Next Steps

1. **REST API Endpoints** - Create API routes for CRUD operations
2. **Form Handling** - Add AJAX handlers for settings/data
3. **User Preferences** - Store dark mode and other preferences
4. **Admin Notices** - Add success/error notifications
5. **Help Context** - Add contextual help tabs

---

## Support

- Main verification doc: `ADMIN-INTEGRATION-VERIFICATION.md`
- WordPress Codex: https://codex.wordpress.org/
- REST API Handbook: https://developer.wordpress.org/rest-api/