WordPress Integration

Integrate MIDDAG React UI into a WordPress admin plugin using Inertia.js and the host adapter system.

Prerequisites

• WordPress 6.x+ with admin access
• PHP 8.2+ with Composer autoloading
• Inertia.js WordPress adapter -- community package or custom integration
• Node.js 20+ and npm for the frontend build

Install

Navigate to your plugin's UI directory and install the package:

cd /path/to/wp-content/plugins/your-plugin/ui
npm install @middag-io/react

Vite Config

Configure Vite to output a manifest for WordPress asset enqueuing:

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
    plugins: [react()],
    build: {
        outDir: '../assets/dist',
        manifest: true,
    },
});

Asset enqueuing

Use the Vite manifest (manifest.json) to resolve hashed filenames when calling wp_enqueue_script() and wp_enqueue_style() in PHP.

Entry Point

Create your app entry point with the WordPress i18n resolver:

// main.tsx
import { ContractPage, registerDefaults } from '@middag-io/react';
import { I18nProvider } from '@middag-io/react';
import '@middag-io/react/style.css';

registerDefaults();

// WordPress i18n resolver
const wpResolver = async (key: string) => {
    return wp.i18n.__(key, 'your-plugin-textdomain');
};

export function WordPressPage({ contract, help }) {
    return (
        <I18nProvider asyncResolver={wpResolver}>
            <ContractPage contract={contract} help={help} />
        </I18nProvider>
    );
}

wp.i18n

WordPress ships wp.i18n globally when you enqueue the wp-i18n script dependency. The resolver wraps __() for MIDDAG's async interface.

WP Admin Chrome

WordPress admin has a fixed chrome that MIDDAG renders within:

• Admin bar -- 32px fixed top bar with site links, user menu, and notifications
• Admin sidebar -- 160px wide (collapses to 36px on narrow screens or when toggled)
• Content area -- MIDDAG renders here, to the right of the WP sidebar and below the admin bar

CSS custom properties are set automatically by the host adapter:

--host-header-height: 32px;   /* WP admin bar */
--host-sidebar-width: 160px;  /* WP sidebar (expanded) */
--host-sidebar-width: 36px;   /* WP sidebar (collapsed) */

The WP admin bar and sidebar are permanent

The WordPress admin bar and sidebar are always visible in the admin area. Design your MIDDAG pages within their frame -- never attempt to hide or override them.

PHP Controller

Register a WordPress admin page and render the contract via Inertia:

// your-plugin.php
add_menu_page(
    'MIDDAG',
    'MIDDAG',
    'manage_options',
    'middag',
    function() {
        $contract = [
            'version' => '1',
            'shell'   => 'product',
            'page'    => [
                'key'   => 'dashboard',
                'title' => __('Dashboard', 'your-plugin'),
            ],
            'layout' => [
                'template' => 'stack',
                'regions'  => [
                    'content' => [
                        // Your blocks here
                    ],
                ],
            ],
        ];

        // Render via Inertia
        wp_middag_render('Dashboard', [
            'contract' => $contract,
        ]);
    }
);

wp_middag_render

The wp_middag_render() helper handles Inertia response setup, shared props injection, and asset enqueuing. It mirrors what $this->inertia() does in the Moodle framework.

Host Theme Detection

MIDDAG automatically detects the WordPress admin color scheme and adapts:

• Dark mode detection -- reads body.admin-color-* classes to determine the active color scheme
• Known schemes -- admin-color-default, admin-color-light, admin-color-modern, etc. are mapped to light/dark mode
• Manual override -- users can toggle appearance mode via the sidebar footer toggle, overriding auto-detection
• CSS variables -- MIDDAG's design tokens adapt to the host theme via data-theme attribute on the root element

Appearance toggle

The sidebar footer includes an appearance toggle (sun/moon icon) that lets users switch between light and dark mode regardless of the WordPress admin scheme.