# 5. INTERFACCIA UNIVERSALE - GUIDA COMPLETA ## 📋 **INDICE CAPITOLO** - [5.1 Architettura Layout](#51-architettura-layout) - [5.2 Sistema Navigazione AJAX](#52-sistema-navigazione-ajax) - [5.3 Helper Menu Personalizzati](#53-helper-menu-personalizzati) - [5.4 Gestione Sidebar Dinamica](#54-gestione-sidebar-dinamica) - [5.5 Dashboard Cards Interattive](#55-dashboard-cards-interattive) - [5.6 Breadcrumb e Messaggi](#56-breadcrumb-e-messaggi) - [5.7 Esempi Pratici](#57-esempi-pratici) - [5.8 Best Practices](#58-best-practices) --- ## 5.1 Architettura Layout ### Layout Base Universale **File**: `resources/views/layouts/universal.blade.php` ```blade {{ $pageTitle ?? 'NetGescon' }} @vite(['resources/css/app.css', 'resources/js/app.js']) @stack('styles')

@include('layouts.partials.header') @if($showSidebar ?? true) @endif

@if($showBreadcrumb ?? true) @include('layouts.partials.breadcrumb') @endif @include('layouts.partials.alerts') {{ $slot }}

@stack('scripts') ``` ### Layout Base Universale V2 (Bootstrap + Sidebar NetGescon) **File**: `resources/views/layouts/app-universal-v2.blade.php` - Evoluzione del layout universale classico con sidebar brandizzata (`components.menu.sidebar-netgescon`) e top navbar gradiente. - Include un contenitore `

` fisso largo 280px che rimane ancorato a sinistra mentre `.main-content` applica `margin-left: 280px` su desktop e torna full-width sotto i 992px. - In modalità mobile (`max-width: 991.98px`) la sidebar viene nascosta tramite `transform: translateX(-100%)` e riappare quando il bottone `#mobile-menu-toggle` aggiunge la classe `.show`; contestualmente il layer `#sidebar-overlay` gestisce il focus dell'utente. - Le viste universali devono rispettare il wrapper `div.container-fluid.p-4` fornito dal layout (es. `resources/views/anagrafica/show.blade.php`) per garantire che gradienti, sticky panel e colonne risultino perfettamente allineati. #### Scheda Anagrafica Demo (allineamento grafico) - **File**: `resources/views/anagrafica/show.blade.php` - La scheda utilizza gli stessi token grafici della Rubrica (`netgescon-card`, `netgescon-btn`, chip e pill) per garantire coerenza visiva tra dashboard e dettagli soggetto. - Le colonne sono organizzate con una griglia `grid grid-cols-1 2xl:grid-cols-4 gap-6` così da replicare l’impostazione “Lista · Dettaglio · Rail azioni” descritta nelle bozze UI. - I tab usano ancora il motore Bootstrap (`data-bs-toggle="pill"`) ma con pulsanti brandizzati (`scheda-tabs`) per mantenere funzionalità accessibile e look&feel identico alle schermate di riferimento. - Ogni nuova sezione demo deve essere documentata accennando a: header hero con chip ruolo, blocchi indicatori uniformi e azioni contestuali sulla rail destra. ### Header Universale **File**: `resources/views/layouts/partials/header.blade.php` ```blade ``` --- ## 5.2 Sistema Navigazione AJAX ### JavaScript Navigazione Dashboard **File**: `resources/js/dashboard-navigation.js` ```javascript class DashboardNavigation { constructor() { this.currentSection = null; this.init(); } init() { // Gestione click cards dashboard $(document).on('click', '.clickable-card', (e) => { const section = $(e.currentTarget).data('section'); this.loadSection(section); }); // Gestione navigazione sidebar $(document).on('click', '.dashboard-nav-link', (e) => { e.preventDefault(); const section = $(e.currentTarget).data('section'); const action = $(e.currentTarget).data('action'); this.loadSection(section, action); }); // Gestione breadcrumb $(document).on('click', '.breadcrumb-back', (e) => { e.preventDefault(); this.showDashboard(); }); // Gestione pulsanti azione $(document).on('click', '.section-action-btn', (e) => { e.preventDefault(); const action = $(e.currentTarget).data('action'); this.handleSectionAction(action); }); // Mobile sidebar toggle $('#sidebarToggle').on('click', () => { $('.sidebar').toggleClass('show'); }); } loadSection(section, action = null) { // Mostra loader this.showLoader(); // Nascondi dashboard principale $('#main-dashboard').addClass('d-none'); $('#section-content').removeClass('d-none'); // Aggiorna sidebar attiva this.updateSidebarActive(section); // Aggiorna breadcrumb this.updateBreadcrumb(section); // Carica contenuto specifico this.loadSectionContent(section, action); } loadSectionContent(section, action) { const sectionHandlers = { 'stabili': () => this.loadStabiliContent(action), 'condomini': () => this.loadCondominiContent(action), 'unita': () => this.loadUnitaContent(action), 'soggetti': () => this.loadSoggettiContent(action), 'contabilita': () => this.loadContabilitaContent(action), 'documenti': () => this.loadDocumentiContent(action), 'tickets': () => this.loadTicketsContent(action) }; if (sectionHandlers[section]) { sectionHandlers[section](); } else { this.showError(`Sezione '${section}' non trovata`); } } showDashboard() { $('#section-content').addClass('d-none'); $('#main-dashboard').removeClass('d-none'); this.updateSidebarActive('dashboard'); this.updateBreadcrumb('dashboard'); } updateSidebarActive(section) { $('.sidebar .nav-link').removeClass('active'); $(`.sidebar .nav-link[data-section="${section}"]`).addClass('active'); } updateBreadcrumb(section) { const breadcrumbMap = { 'dashboard': 'Dashboard', 'stabili': 'Gestione Stabili', 'condomini': 'Anagrafica Condomini', 'unita': 'Unità Immobiliari', 'soggetti': 'Anagrafica Soggetti', 'contabilita': 'Contabilità', 'documenti': 'Gestione Documenti', 'tickets': 'Comunicazioni' }; const breadcrumbHtml = ` `; $('#breadcrumb-container').html(breadcrumbHtml); } showLoader() { const loader = `

`; $('#section-content').html(loader); } showError(message) { const error = `

${message}

`; $('#section-content').html(error); } } // Inizializza quando DOM è pronto $(document).ready(() => { new DashboardNavigation(); }); ``` --- ## 5.3 Helper Menu Personalizzati ### MenuHelper Class Completa **File**: `app/Helpers/MenuHelper.php` ```php ['admin', 'amministratore'], 'condomini' => ['admin', 'amministratore'], 'unita' => ['admin', 'amministratore'], 'soggetti' => ['admin', 'amministratore'], 'contabilita' => ['admin', 'amministratore'], 'documenti' => ['admin', 'amministratore', 'condomino'], 'tickets' => ['admin', 'amministratore', 'condomino'], 'comunicazioni' => ['admin', 'amministratore'], 'backup' => ['admin', 'amministratore'], 'utenti' => ['super-admin'], 'comuni' => ['super-admin'], 'configurazione' => ['super-admin'], 'log' => ['super-admin', 'admin'] ]; /** * Verifica se l'utente può accedere a un menu specifico */ public static function canUserAccessMenu(string $menuKey): bool { $user = Auth::user(); if (!$user) { return false; } // SuperAdmin può accedere a tutto if ($user->hasRole('super-admin')) { return true; } if (!isset(self::$menuPermissions[$menuKey])) { return false; } return $user->hasAnyRole(self::$menuPermissions[$menuKey]); } /** * Costruisce menu sidebar completo per ruolo utente */ public static function buildSidebarMenu(): array { $user = Auth::user(); $userRoles = $user->getRoleNames()->toArray(); $menu = []; // Menu base sempre presente $menu[] = [ 'label' => 'Dashboard', 'icon' => 'fas fa-tachometer-alt', 'route' => 'dashboard', 'active' => request()->routeIs('dashboard'), 'type' => 'route' ]; // Menu per SuperAdmin if ($user->hasRole('super-admin')) { $menu[] = [ 'label' => 'Gestione Utenti', 'icon' => 'fas fa-users', 'route' => 'superadmin.users.index', 'active' => request()->routeIs('superadmin.users.*'), 'type' => 'route' ]; $menu[] = [ 'label' => 'Comuni Italiani', 'icon' => 'fas fa-map', 'route' => 'superadmin.comuni.index', 'active' => request()->routeIs('superadmin.comuni.*'), 'type' => 'route' ]; $menu[] = [ 'label' => 'Configurazione', 'icon' => 'fas fa-cog', 'route' => 'superadmin.config.index', 'active' => request()->routeIs('superadmin.config.*'), 'type' => 'route' ]; $menu[] = [ 'label' => 'Log Sistema', 'icon' => 'fas fa-file-alt', 'route' => 'superadmin.logs.index', 'active' => request()->routeIs('superadmin.logs.*'), 'type' => 'route' ]; } // Menu per Admin/Amministratore if ($user->hasAnyRole(['admin', 'amministratore'])) { // Sezione Anagrafica $menu[] = [ 'label' => 'ANAGRAFICA', 'type' => 'header' ]; if (self::canUserAccessMenu('stabili')) { $menu[] = [ 'label' => 'Gestione Stabili', 'icon' => 'fas fa-building', 'section' => 'stabili', 'type' => 'ajax', 'badge' => $user->stabiliAmministrati()->count() ]; } if (self::canUserAccessMenu('condomini')) { $menu[] = [ 'label' => 'Anagrafica Condomini', 'icon' => 'fas fa-home', 'section' => 'condomini', 'type' => 'ajax' ]; } if (self::canUserAccessMenu('soggetti')) { $menu[] = [ 'label' => 'Anagrafica Soggetti', 'icon' => 'fas fa-users', 'section' => 'soggetti', 'type' => 'ajax' ]; } if (self::canUserAccessMenu('unita')) { $menu[] = [ 'label' => 'Unità Immobiliari', 'icon' => 'fas fa-door-open', 'section' => 'unita', 'type' => 'ajax' ]; } // Sezione Gestionale $menu[] = [ 'label' => 'GESTIONALE', 'type' => 'header' ]; if (self::canUserAccessMenu('contabilita')) { $menu[] = [ 'label' => 'Contabilità', 'icon' => 'fas fa-calculator', 'section' => 'contabilita', 'type' => 'ajax' ]; } if (self::canUserAccessMenu('documenti')) { $menu[] = [ 'label' => 'Gestione Documenti', 'icon' => 'fas fa-file-alt', 'section' => 'documenti', 'type' => 'ajax' ]; } if (self::canUserAccessMenu('tickets')) { $menu[] = [ 'label' => 'Comunicazioni', 'icon' => 'fas fa-envelope', 'section' => 'tickets', 'type' => 'ajax', 'badge' => self::getTicketsApertiCount() ]; } } // Menu per Condomino if ($user->hasRole('condomino')) { $menu[] = [ 'label' => 'Le Mie Proprietà', 'icon' => 'fas fa-home', 'route' => 'condomino.unita.index', 'active' => request()->routeIs('condomino.unita.*'), 'type' => 'route' ]; $menu[] = [ 'label' => 'I Miei Documenti', 'icon' => 'fas fa-file', 'route' => 'condomino.documenti.index', 'active' => request()->routeIs('condomino.documenti.*'), 'type' => 'route' ]; $menu[] = [ 'label' => 'Comunicazioni', 'icon' => 'fas fa-envelope', 'route' => 'condomino.tickets.index', 'active' => request()->routeIs('condomino.tickets.*'), 'type' => 'route' ]; } return $menu; } /** * Genera HTML per menu sidebar */ public static function renderSidebarMenu(): string { $menu = self::buildSidebarMenu(); $html = '

'; foreach ($menu as $item) { $html .= self::renderMenuItem($item); } $html .= ''; return $html; } /** * Renderizza singolo elemento menu */ private static function renderMenuItem(array $item): string { if ($item['type'] === 'header') { return '

' . $item['label'] . '

'; } $activeClass = ($item['active'] ?? false) ? 'active' : ''; $badge = isset($item['badge']) ? '' . $item['badge'] . '' : ''; if ($item['type'] === 'route') { $href = route($item['route']); $attributes = ''; } else { $href = '#' . $item['section']; $attributes = 'data-section="' . $item['section'] . '"'; } return '

' . $item['label'] . ' ' . $badge . '

'; } /** * Conta tickets aperti per badge */ private static function getTicketsApertiCount(): int { $user = Auth::user(); if ($user->hasRole('condomino')) { // Conta tickets del condomino return \App\Models\Ticket::where('user_id', $user->id) ->where('stato', 'aperto') ->count(); } if ($user->hasAnyRole(['admin', 'amministratore'])) { // Conta tickets degli stabili amministrati $stabiliIds = $user->stabiliAmministrati()->pluck('id'); return \App\Models\Ticket::whereIn('stabile_id', $stabiliIds) ->where('stato', 'aperto') ->count(); } return 0; } } ``` --- ## 5.4 Gestione Sidebar Dinamica ### Sidebar Blade Template **File**: `resources/views/layouts/partials/sidebar.blade.php` ```blade

{!! App\Helpers\MenuHelper::renderSidebarMenu() !!}

``` --- ## 5.5 Dashboard Cards Interattive ### Dashboard Cards Template **File**: `resources/views/admin/dashboard-cards.blade.php` ```blade

@if(App\Helpers\MenuHelper::canUserAccessMenu('stabili'))

Gestione Stabili

Amministra anagrafica e dati degli stabili

Stabili

Attivi {{ $stats['stabili_attivi'] ?? 0 }}

Clicca per gestire

@endif @if(App\Helpers\MenuHelper::canUserAccessMenu('condomini'))

Anagrafica Condomini

Gestisce proprietari e inquilini

Condomini

Proprietari {{ $stats['proprietari_count'] ?? 0 }}

Clicca per gestire

@endif @if(App\Helpers\MenuHelper::canUserAccessMenu('contabilita'))

Contabilità

Movimenti e bilanci condominiali

Movimenti

Saldo €{{ number_format($stats['saldo_totale'] ?? 0, 2) }}

Clicca per gestire

@endif @if(App\Helpers\MenuHelper::canUserAccessMenu('documenti'))

Gestione Documenti

Archivia e organizza documenti

Documenti

Questo mese {{ $stats['documenti_mese'] ?? 0 }}

Clicca per gestire

@endif @if(App\Helpers\MenuHelper::canUserAccessMenu('tickets'))

Comunicazioni

Ticket e richieste condomini

Aperti

Totali {{ $stats['tickets_totali'] ?? 0 }}

Clicca per gestire

@endif

``` --- ## 5.6 Breadcrumb e Messaggi ### Breadcrumb Template **File**: `resources/views/layouts/partials/breadcrumb.blade.php` ```blade ``` ### Alert Messaggi Template **File**: `resources/views/layouts/partials/alerts.blade.php` ```blade @if(session('success'))

@endif @if(session('error'))

@endif @if(session('warning'))

@endif @if(session('info'))

@endif @if($errors->any())

Errori di validazione:

{{ $error }}

@endif ``` --- ## 5.7 Esempi Pratici ### Come Aggiungere Nuova Sezione Menu **Passo 1**: Aggiungere permesso in `MenuHelper.php` ```php private static $menuPermissions = [ // ...existing permissions... 'nuova_sezione' => ['admin', 'amministratore'], ]; ``` **Passo 2**: Aggiungere voce menu in `buildSidebarMenu()` ```php if (self::canUserAccessMenu('nuova_sezione')) { $menu[] = [ 'label' => 'Nuova Sezione', 'icon' => 'fas fa-star', 'section' => 'nuova_sezione', 'type' => 'ajax' ]; } ``` **Passo 3**: Aggiungere handler JavaScript in `dashboard-navigation.js` ```javascript const sectionHandlers = { // ...existing handlers... 'nuova_sezione': () => this.loadNuovaSezionePage(action), }; loadNuovaSezionePage(action) { let content = `

Nuova Sezione

Contenuto della nuova sezione

`; $('#section-content').html(content); } ``` ### Come Aggiungere Nuova Card Dashboard **Passo 1**: Aggiungere in `dashboard-cards.blade.php` ```blade @if(App\Helpers\MenuHelper::canUserAccessMenu('nuova_sezione'))

Nuova Sezione

Descrizione della nuova sezione

Elementi

Clicca per gestire

@endif ``` --- ## 5.8 Best Practices ### Convenzioni Naming - **Sezioni**: snake_case (es: `gestione_stabili`) - **Icone**: Font Awesome 6 (es: `fas fa-building`) - **Colori**: Bootstrap classes (es: `text-primary`) - **Route**: kebab-case (es: `admin.stabili.index`) ### Performance - **Caricamento lazy**: Solo il contenuto necessario - **Cache menu**: MenuHelper usa cache per permessi - **Minify assets**: Vite ottimizza JS/CSS - **AJAX progressive**: Carica solo sezioni attive ### Responsive Design - **Mobile-first**: Bootstrap 5 grid system - **Sidebar collapsible**: Hidden su mobile - **Touch-friendly**: Buttons e cards ottimizzati - **Breakpoints**: sm, md, lg, xl, xxl ### Sicurezza - **CSRF protection**: Token in tutti i form - **Route protection**: Middleware per ogni sezione - **Permission checking**: Helper per ogni menu - **Input validation**: Laravel Form Requests ### Debugging - **Console logs**: JavaScript errors - **Laravel debugbar**: Query monitoring - **Error pages**: Custom 403/404/500 - **Log channels**: Separate logs per sezione --- **📝 COMPLETATO: Capitolo 5 - Interfaccia Universale** Questo capitolo fornisce una guida completa per: - ✅ Implementare layout universale - ✅ Gestire navigazione AJAX - ✅ Creare helper menu personalizzati - ✅ Configurare sidebar dinamica - ✅ Implementare dashboard interattive - ✅ Aggiungere nuove sezioni/menu - ✅ Seguire best practices **🔄 Prossimi capitoli da completare:** - 6. Sistema Multi-Ruolo - 7. API e Integrazioni - 8. Frontend e UX - 9. Gestione Stabili e Condomini - 10. Sistema Contabile - ... (tutti gli altri capitoli)

Gestione Stabili

{{ $stats['stabili_count'] ?? 0 }}

Anagrafica Condomini

{{ $stats['condomini_count'] ?? 0 }}

Contabilità

{{ $stats['movimenti_count'] ?? 0 }}

Gestione Documenti

{{ $stats['documenti_count'] ?? 0 }}

Comunicazioni

{{ $stats['tickets_aperti'] ?? 0 }}