# Master Front Rules > Skill: Regole del layout del front (Master Laravel Enesi) - Skill: `danilo-enesi/master-front-rules` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add danilo-enesi/master-front-rules` - Raw SKILL.md: https://api.skillmd.com/api/skills/danilo-enesi/master-front-rules/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: Danilo-enesi (https://skillmd.com/u/danilo-enesi) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/danilo-enesi/master-front-rules --- # Skill: Regole del layout del front (Master Laravel Enesi) Quattro regole mentali, in ordine di importanza. Il resto della skill le spiega. 1. **Il layout non contiene asset propri**: include `base.head` (solo ``) e `base.scripts` (solo fine ``). Nelle viste di pagina/partial/componente non esiste JS o CSS inline. 2. **I meta non si scrivono a mano**: `Meta::render()` li stampa tutti, i valori si impostano dal controller con `Meta::set()`. 3. **Ogni risorsa di terze parti nasce bloccata**: `Dom::renderCookieBanner()` + attributi `data-epp-*`. Includere uno script esterno "normalmente" è un bug di compliance, non una scorciatoia. 4. **Un dato che serve a più Blade si carica una volta sola, in un posto solo.** Due meccanismi, entrambi convenzione del progetto: **view composer** per i dati di alcune viste, **`Front::loadSharedContent()` + `Dom::config()`** per i dati globali del front (§4). Mai query dentro le Blade, mai lo stesso array ricalcolato in ogni controller. ## Materiale di supporto * `references/epp-cookie-banner.md` — catalogo completo del cookie banner EPP: attributi di blocco, pulsanti `data-epp`, API JS, categorie PID, eccezioni. * `references/layout-esempio-commentato.md` — walkthrough di un layout reale e funzionante (head, scripts, meta, composer, embed bloccati) con le trappole che ogni scelta evita, più una checklist di confronto per entrare in un progetto esistente. --- ## 0. Prima di toccare qualcosa: verifica le API sul progetto L'ecosistema è versionato per progetto (`private/vendor/enesisrl/laravel-master-core`) e **non tutti i metodi esistono in tutte le versioni**. Prima di usare un helper che non hai visto in questo repo, controlla: ``` private/vendor/enesisrl/laravel-master-core/src/Foundation/Meta.php private/vendor/enesisrl/laravel-master-core/src/Foundation/Dom.php private/vendor/enesisrl/laravel-master-core/src/Foundation/Front.php ``` Metodi che **esistono** e vanno usati (verificati su 8 progetti Master): `Meta::render()`, `Meta::set()`, `Meta::append()`, `Meta::get()`, `Meta::format()`, `Meta::googleFonts()`, `Dom::renderCookieBanner()`, `Dom::config()`, `Dom::format_address()`, `Dom::phone_number_format()`, `Front::route()`/`routeLang()`/`globalRoute()`, `Front::currentRouteName()`, `Front::running()`, `Front::groupRoutes()`, `Front::loadSharedContent()` (stub da implementare, §4.2), `Version::get()`. Non inventare helper "simmetrici" che sembrano esistere ma non esistono: per gli script di terze parti si usano gli attributi `data-epp-*` (§3.2), per i Google Fonts `Meta::googleFonts()` (§2), e non c'è nessun `Meta::script()`. **Punto di estensione corretto**: le facade `Meta`, `Dom`, `Front`, `Version`, `Admin`, `Tool` sono bindate come singleton su `Master\Foundation\*`, cioè su **`private/master/Foundation/*.php`** — codice di progetto, non vendor, di norma sottoclassi vuote pronte a essere estese. Il vendor non si modifica mai: le modifiche condivise vanno nel repo `laravel-master-dev` e rientrano via Composer. --- ## 1. Anatomia del layout e separazione head / footer ``` private/front/Main/Views/base/ ├── layout.blade.php scheletro + Meta::render() + cookie banner + window.front ├── head.blade.php TUTTO ciò che va in : preconnect, favicon, font, CSS ├── scripts.blade.php TUTTO ciò che va prima di : librerie JS + bundle ├── header.blade.php ┐ ├── offcanvas.blade.php ├─ markup, dati iniettati da un view composer (§4.1) └── footer.blade.php ┘ ``` ```blade {!! Meta::render() !!} {{-- 1. meta/title/og/canonical/robots --}} {!! Dom::renderCookieBanner() !!} {{-- 2. SDK EPP: PRIMA di ogni risorsa bloccata --}} @include('base.head') {{-- 3. CSS/asset di head del progetto --}} @stack('head') {{-- 4. head aggiuntivo di pagine e componenti --}} @include('base.offcanvas') @include('base.header')

@yield('content')

@include('base.footer') {{-- unica config globale per il JS --}} @include('base.scripts') {{-- librerie + bundle --}} @stack('scripts') {{-- JS aggiuntivo di pagine e componenti --}} ``` **Due stack, `head` e `scripts` — mai `@yield`/`@section`.** `@stack('head')` in `` (CSS, preload, meta extra, JSON-LD), `@stack('scripts')` prima di ``. Motivo: `@yield`/`@section` accetta **un solo** contributo, quindi due viste o componenti che usano lo stesso hook si annullano a vicenda (vince l'ultimo) e un Blade component non può contribuire affatto. `@push`/`@stack` **accumula** e funziona da pagine, partial e component; `@pushOnce` evita il doppio inserimento quando lo stesso componente compare più volte nella pagina. **Ordine non negoziabile**: `@stack('head')` **dopo** `@include('base.head')` (la pagina può sovrascrivere il CSS globale); `@stack('scripts')` **dopo** `@include('base.scripts')` (jQuery/Bootstrap/slick sono già disponibili quando gira il JS di pagina). **Classi sul ``** — convenzione, sono il gancio CSS/JS per non scrivere codice condizionale nelle viste: | Classe | Da | Serve a | | ----------------------- | ----------------------------------------- | --------------------------------------------- | | `lang-it`, `lang-en`, … | `Websites::currentLanguage('iso_code2')` | ritocchi tipografici e di layout per lingua | | `route-contatti`, … | `Front::currentRouteName()` | stile e attivazione JS per pagina | | `theme-…` | `Websites::current('theme.assets')` | varianti di tema nei progetti multi-sito | ```css body.lang-de .nav-link { letter-spacing: 0; } /* parole lunghe */ body.route-contatti .map { display: block; } ``` Il nome della rotta arriva già senza prefisso dominio/lingua, quindi `route-*` è stabile fra le lingue: la stessa regola CSS vale per `/it/contatti` e `/en/contacts`. ### Cosa va dove | Serve… | Va in… | | ------------------------------------- | ---------------------------------------------------------- | | CSS a tutto il sito | `base/head.blade.php` | | JS a tutto il sito | `base/scripts.blade.php` (fine body, **non** in head) | | CSS/JS di **una** pagina o componente | `@push('head')` / `@push('scripts')` | | Valore da passare al JS | `window.front` nel layout, o `data-*` sul markup | | Comportamento riusabile | file in `template/assets/js/` incluso nel bundle Mix | ```blade {{-- Views/pages/contatti.blade.php --}} @push('head') @endpush @push('scripts') @endpush ``` In un Blade component che può comparire più volte nella stessa pagina, usa `@pushOnce` con una chiave, così l'asset entra una volta sola: ```blade {{-- Views/components/blocks/photogallery.blade.php --}} @pushOnce('head', 'lightbox') @endPushOnce ``` Se un progetto usa ancora `@yield('head')`, va migrato a `@stack('head')`: nella transizione si possono tenere entrambi (`@stack('head')` subito dopo `@yield('head')`) finché tutte le `@section('head')` non sono diventate `@push('head')`. **Perché**: l'ordine di caricamento resta in un punto solo; il codice condiviso finisce nel bundle minificato invece di essere duplicato per pagina; quando cambia una libreria si tocca un file, non venti viste. ### Asset: `Version::get()` e split debug/produzione Asset locali **sempre** dentro `\Master\Facades\Version::get()` (cache busting), e split ambiente già convenzionale in `head`/`scripts`: ```blade @if(config('app.debug')) @else @endif ``` I `.min.*` li produce laravel-mix (`npx mix --production` da `private/`, config in `webpack.mix.js`): **non si editano a mano**. Se hai aggiunto un file JS/CSS nuovo, verifica che sia concatenato in `webpack.mix.js`, altrimenti in produzione non esiste. Per portare un HTML del prototipo in Blade estraendo correttamente stili e script → vedi la skill `template-to-blade`. --- ## 2. `Meta::render()` — meta tag centralizzati `Meta::render()` in `` stampa **tutta** la mappa: `charset`, `viewport`, `title`, `description`, `canonical`, `robots`, blocco OpenGraph, blocco Twitter, App Links. **Nessuno di quei tag si scrive a mano in una vista.** I valori si impostano **nel controller**, prima del `return view(...)`: ```php Meta::set('title', $post->meta_title ?: $post->description); Meta::set('description', $post->meta_description ?: $post->summary); Meta::set('canonical', $post->url); Meta::set('og:image', $post->cover?->getFullUrl()); ``` Comportamenti del core da NON reimplementare: * **Fallback a catena**: `og:title`/`twitter:title` ← `title`; `og:description`/`twitter:description` ← `description`; `twitter:image` ← `og:image`; `canonical`/`og:url` ← `request()->fullUrl()`; `og:locale` ← lingua del sito; `og:type`/`twitter:card` ← `website`. Basta impostare `title` + `description` (+ `og:image` dove c'è una cover). * `title`/`description` passano da `format()`: strip tag, newline rimosse, **troncamento a 160 caratteri**. Non troncare a mano. * `robots` → `noindex, nofollow` **automatico** in ambiente `development`. * `og:image`/`twitter:image`/`og:video` sono di tipo **array**: `set()` ripetuto **aggiunge** un tag; `null` resetta. * URL relativi (`/storage/...`) completati con schema+host e **validati**: se non validi, il tag non viene emesso (utile da sapere quando un `og:image` "sparisce"). * `set()` accetta **solo** le chiavi mappate: una chiave sconosciuta ritorna `false` **in silenzio**. Per un meta nuovo (es. `theme-color`) si estende la mappa in `Master\Foundation\Meta`, non si stampa il tag nella vista. * `Meta::googleFonts($url)` genera il `` dei Google Fonts **già bloccato** per il consenso (`data-epp-href` + categoria `10003`). Usarlo sempre: mai un `` diretto a `fonts.googleapis.com`. Regola operativa: **ogni action di controller che rende una pagina imposta `title` e `description`.** Se il dato viene dal CMS, usa il campo meta del model con fallback sul testo (`$model->meta_title ?: $model->description`). --- ## 3. `Dom::renderCookieBanner()` e il blocco preventivo ### 3.1 Il banner ```blade {!! Dom::renderCookieBanner() !!} ``` Emette lo script dell'SDK EPP (`https://privacy.ene.si/api/js?uid=…&ln=…&key=…`) e ritorna `null` se il sito non è configurato. Legge dal modulo **Websites**: | Campo | Ruolo | | ----------------- | ---------------------------------------------- | | `epp_policy_id` | UID progetto — **se vuoto il banner non esce** | | `ene_api_key` | KEY cliente (opzionale) | | lingua corrente | `ln` in `iso_code3` (ita, eng, spa, …) | Posizione: **subito dopo `Meta::render()`, prima di qualunque risorsa bloccata**. È l'SDK che sblocca gli elementi: se arriva dopo, lo sblocco è tardivo. L'SDK inietta da sé il proprio CSS (non includere `privacy.ene.si/api/css`) e imposta da sé il **Google Consent Mode v2** se non trova già un comando `consent` nel `dataLayer`. Primo controllo quando "il banner non si vede": `epp_policy_id` valorizzato sul Website corrente. ### 3.2 Bloccare le risorse che richiedono consenso | Cosa | Come si blocca | | ---------------------------- | ----------------------------------------------------------- | | Script esterno | `data-epp-onconsent` + `src` → `data-epp-src` | | Script inline | `data-epp-onconsent` + `type="text/plain"` | | `` (font, CSS 3rd) | `href` → `data-epp-href` | | `