Compilatore, runtime, layout e sezioni

01Panoramica

Nucleo compila ogni documento quando lo salvi, non quando il visitatore apre la pagina. Nucleo esegue una pipeline: normalizza, espande le sezioni, risolve i link, valida, controlla la qualità, compila e scrive. Il compilatore produce HTML statico con marcatori di slot, CSS di istanza, elenco degli slot e degli script. L'HTML va in post_content, il CSS in un file sotto uploads/nucleo/css/, il resto nel meta _nucleo_rt. Il runtime del frontend legge solo questi dati e gli artefatti in wp-content/uploads/nucleo/store/. Non carica il compilatore né il registro dei blocchi. I layout sono documenti kind layout o popup nel tipo nucleo_layout. Le condizioni diventano una mappa che il runtime consulta per area. Le sezioni riutilizzabili sono documenti kind section nel tipo nucleo_section, inseriti con il blocco nc/section-ref. Quando cambia una sezione, un menu, un link o un'opzione del sito, Nucleo accoda la ricompilazione delle pagine che ne dipendono.

Lo schema del documento e i blocchi sono descritti nel capitolo Schema del documento e blocchi.

02Compilazione al salvataggio

Pipeline di salvataggio

Cosa fa: porta un documento dal JSON ricevuto al post scritto. Nucleo esegue questi passi in ordine.

Come si usa: non ha un'interfaccia propria. La chiamano le ability di scrittura (nucleo/doc-create, nucleo/doc-patch, nucleo/doc-publish, nucleo/doc-rollback, nucleo/doc-texts-set, nucleo/doc-translate (Pro), nucleo/layout-conditions-set), l'import del sito e il controllo delle meta lette dai binding. Vedi il capitolo Abilities di scrittura.

Parametri:

Permessi: nessun controllo nel salvataggio. Il controllo spetta all'ability o al comando che lo chiama.

Edizione: Free

Limiti noti:

• Codici di errore restituiti: invalid_document, quality_blocking, conflict, not_found, patch_failed, write_failed, exists (solo start).
• Il controllo bloccante della qualità vale con publish. Vale anche per ogni salvataggio di un post già pubblicato.
• Il documento salvato conserva i nc/section-ref e i link simbolici. L'espansione serve solo a validare e compilare.
• Le regole seo.h1.missing, a11y.landmark.missing e seo.content.thin non valgono per layout, sezioni e popup. Per le sezioni non valgono neanche content.button.inert e form.action.consequential.
• Un riconoscimento decade quando il nodo cambia. Nucleo salva un'impronta del nodo, senza figli, insieme al riconoscimento.
• Alla creazione con bind il documento si compila due volte. I binding statici leggono il post, che prima non esiste.
• Le regole di budget confrontano la pagina composta con valori predefiniti: CSS 76800 byte, JS 102400 byte, DOM 1500 nodi stimati. Il filtro nucleo/quality/<css|js|dom>_budget li cambia per il sito.
• Un contenuto nuovo non ancora salvato: la qualità usa i layout del suo tipo, ma non ha peso CSS. I budget si applicano dal primo salvataggio.

Aggancio a un contenuto esistente

Cosa fa: crea il primo documento Nucleo di un post esistente. Tipo, titolo e stato restano quelli del post. Se il documento ha root.children vuoto, Nucleo converte paragrafi, titoli e voci di elenco del testo WordPress in blocchi nc/text. Salva il testo originale nel meta _nucleo_wp_content.

Come si usa: nucleo/doc-create con postId. Accetta solo kind page.

Parametri: postId, document, dryRun, acknowledge.

Permessi: quelli di nucleo/doc-create. Vedi il capitolo Abilities di scrittura.

Edizione: Free

Limiti noti:

• Al massimo 200 blocchi nc/text. Restano grassetto, corsivo e link.
• Immagini e altri elementi si perdono nel documento.
• Errore exists se il post ha già un documento.

Compilatore

Cosa fa: trasforma un documento valido ed espanso in un risultato di compilazione. Contiene:

• html: HTML statico con i marcatori di slot.
• css: CSS di istanza dei nodi.
• blockTypes: tipi di blocco usati, in ordine di documento.
• slots: elenco degli slot dinamici.
• assets: stili e script dei blocchi usati, con la strategia di caricamento.
• lcpNodeId: il primo nodo che reclama la priorità LCP.
• deps: dipendenze dei nodi, dal deps dei manifest e dai binding statici.

Come si usa: interno al salvataggio. Con markIds vero, come nell'anteprima, ogni nodo riceve data-nc-id sul primo tag. L'anteprima usa la route REST POST nucleo/v1/preview (capability edit_posts) e l'ability nucleo/doc-preview.

Parametri: documento, sorgente dei binding (facoltativa), markIds (bool, default false).

Permessi: nessuno.

Edizione: Free

Limiti noti:

• Documento senza root: eccezione Document has no root.
• Tipo di blocco non registrato: eccezione Block type not registered.
• Un nodo con il vecchio campo ref produce una stringa vuota.
• Per layout, sezioni e popup le classi per nodo hanno un prefisso di 4 caratteri, ricavato dal documento. Così due documenti nella stessa pagina non condividono .nc-n1.
• Un link con riferimento non risolto diventa href="#" aria-disabled="true".
• Le schede dei blocchi nc/query e nc/collection non reclamano mai la priorità LCP.

Slot dinamici

Cosa fa: segna nell'HTML le parti che il runtime calcola a ogni richiesta. Il marcatore è <!--nc:s N-->fallback<!--/nc:s-->. N è l'indice nell'elenco slots di _nucleo_rt. Il fallback è l'HTML visibile se lo slot non si riempie.

Come si usa: i blocchi che calcolano una parte a ogni richiesta la registrano come slot. Il compilatore crea da solo due slot di involucro:

• nc/visibility per un nodo con visibility.when non vuoto. Fallback vuoto.
• nc/bind per un nodo con binding dinamici. I valori diventano token __NCB<n>__ da sostituire a runtime.

Parametri: Nessuno

Permessi: nessuno.

Edizione: Free

Limiti noti: il valore dinamico di un binding si escapa come URL se la chiave finisce con src, url, href o poster. Si escapa come HTML per content.html, e come testo negli altri casi.

Riferimenti nei link

Cosa fa: sostituisce i riferimenti interni con l'URL prima della validazione. Agisce sulle chiavi href di content e settings a ogni profondità, e sugli href dei tag <a> in content.html. Il documento salvato conserva il simbolo.

Come si usa: scrivi nel campo link uno di questi valori, con #ancora facoltativa:

Parametri: Nessuno

Permessi: nessuno.

Edizione: Free

Limiti noti:

• Prefissi riservati, che non sono riferimenti: http, https, mailto, tel, sms, ftp, file, data, javascript, vbscript, section, menu, media, author, term (come tipo di post).
• Solo contenuti pubblicati di tipi visibili e termini di tassonomie visibili.
• Un riferimento risolto una volta segue il contenuto per ID anche dopo un cambio di slug (meta _nucleo_links).
• Riferimento senza bersaglio: avviso di qualità content.link.missing. Un percorso interno scritto come /chi-siamo/ produce l'informazione content.link.path con il riferimento suggerito.

Sanificazione del testo ricco

Cosa fa: pulisce l'HTML inline dei blocchi testuali. Tiene strong, em, b, i, br, p, ul, ol, li, span (solo class) e a (href, target, rel). Toglie script e style con il contenuto. Gli altri tag spariscono e il loro testo resta.

Come si usa: i blocchi che mostrano testo ricco applicano questa pulizia al loro HTML.

Parametri: Nessuno

Permessi: nessuno.

Edizione: Free

Limiti noti: href ammessi: http:, https:, mailto:, tel:, / (non //) e #. Con target="_blank" aggiunge rel="noopener".

03Ricompilazione e invalidazione

Ricompilazione di un documento

Cosa fa: ricompila il documento salvato senza creare una nuova revisione né una voce di storico. Espande di nuovo le sezioni, così la pagina usa la versione corrente.

Come si usa: lo usano nucleo/cache-rebuild, la coda di ricompilazione e il controllo delle meta lette da un binding.

Parametri: ID del post.

Permessi: nessuno nel servizio. nucleo/cache-rebuild richiede manage_options e lo scope nucleo:admin.

Edizione: Free

Limiti noti:

• Documento non più valido dopo il cambio di una sezione: la pagina tiene HTML e CSS precedenti. Gli errori vanno nel meta _nucleo_stale.
• Problemi bloccanti su un post pubblicato: la pagina tiene la versione precedente. I problemi vanno nel meta _nucleo_stale_quality.
• Una ricompilazione riuscita cancella entrambi i meta.

Coda di ricompilazione

Cosa fa: tiene gli ID dei documenti da ricompilare nell'opzione nucleo_rebuild_queue e li elabora a lotti con WP-Cron (hook nucleo_rebuild).

Come si usa: automatica. Nucleo accoda ogni post con il meta _nucleo_doc. Dopo un aggiornamento del plugin, alla prima richiesta di amministrazione, REST o WP-CLI, Nucleo vede che la versione installata (nucleo_installed_version) è cambiata e accoda tutti i documenti. Così l'HTML salvato, compreso l'URL di store.js con la versione, segue i renderer della nuova versione.

Parametri: Nessuno

Permessi: nessuno.

Edizione: Free

Limiti noti:

• Per esecuzione: al massimo 20 documenti o 20 secondi. Se restano documenti, Nucleo pianifica un altro evento.
• Il callback di nucleo_rebuild si registra solo nelle richieste WP-Cron.
• Una ricompilazione che parte durante un'altra ricompilazione accoda soltanto.
• Nucleo toglie dalla coda un documento appena scritto.
• Un documento resta in coda finché la ricompilazione non dà un esito. Se fallisce, riprova dopo 30 secondi per tentativo, fino a 3 tentativi. Poi esce dalla coda e resta un record con tentativi, codice e messaggio dell'errore. nucleo/status lo espone in failed.
• La coda registra per ogni documento la generazione dell'ultimo accodamento. Un documento accodato di nuovo durante la sua ricompilazione resta in coda per un altro giro.
• Le scritture della coda passano da un lock MySQL; un solo processo per volta elabora la coda.
• Dopo un aggiornamento del plugin, un documento con problemi bloccanti tiene l'HTML precedente e resta in stato stale (vedi Ricompilazione di un documento).

Eventi di invalidazione

Cosa fa: accoda la ricompilazione dei documenti che dipendono da un oggetto cambiato. Le dipendenze sono nel meta _nucleo_dep di ogni documento, una riga per dipendenza.

Come si usa: automatico in admin, REST e WP-CLI. Le richieste del frontend non registrano questi hook.

Parametri: Nessuno

Permessi: nessuno.

Edizione: Free

Limiti noti:

• La ricerca dei dipendenti legge a pagine di 500 documenti, senza un limite totale.
• Al cambio di lingua Nucleo adegua date_format e time_format solo se valgono ancora il formato predefinito della lingua precedente.
• Le modifiche ai token non ricompilano le pagine: Nucleo ripubblica l'artefatto tokens e, se il CSS dei token è cambiato, svuota tutta la cache di pagina.

Ricompilazione di tutti i documenti

Cosa fa: accoda ogni documento in questi casi:

• aggiornamento del plugin a una versione diversa;
• cambio dei file dei blocchi (nuovo bundle CSS);
• cambio della struttura dei permalink, della lingua o dei formati di data e ora;
• ricostruzione dello store degli artefatti.

Come si usa: automatica. A mano: nucleo/cache-rebuild senza postIds, oppure wp nucleo ability run cache-rebuild (vedi Comandi WP-CLI).

Parametri: vedi l'ability.

Permessi: manage_options, scope nucleo:admin.

Edizione: Free

Limiti noti: l'ability ricompila subito al massimo 20 documenti e accoda il resto. Accetta al massimo 200 postIds.

Svuotamento della cache di pagina

Cosa fa: dopo ogni scrittura svuota la cache dei plugin di caching presenti. Per un layout svuota tutta la cache. Per gli altri documenti svuota solo l'URL del post. Con LiteSpeed Cache svuota anche le pagine con il tag nucleo-post-<id>, inviato nell'header X-LiteSpeed-Tag del documento.

Come si usa: automatico. Plugin supportati quando presenti: LiteSpeed Cache, WP Rocket, W3 Total Cache, WP Super Cache, SiteGround Optimizer, WP Fastest Cache, Breeze, Kinsta.

Parametri: Nessuno

Permessi: nessuno.

Edizione: Free

Limiti noti: con Breeze lo svuotamento di un solo post svuota tutta la cache. Altri sistemi di cache si collegano con nucleo/purge_url e nucleo/purge_all.

Bundle CSS dei blocchi

Cosa fa: concatena e minimizza il CSS di tutti i blocchi registrati, in ordine alfabetico, in uploads/nucleo/css/blocks.<hash8>.css. Una firma di percorsi e date di modifica dei manifest evita di rileggere i file a ogni salvataggio.

Come si usa: automatico alla compilazione e nell'editor.

Parametri: Nessuno

Permessi: nessuno.

Edizione: Free

Limiti noti: quando il bundle cambia, Nucleo tiene il bundle precedente, cancella i più vecchi e accoda tutti i documenti. Cartella uploads non scrivibile o CSS di un blocco illeggibile: eccezione.

Pubblicazione dei token

Cosa fa: scrive l'artefatto tokens con le regole @font-face dei font locali, le variabili CSS dei token, la versione (hash) e l'URL del font da precaricare. Nello stack dei font aggiunge un font di ripiego metrico dopo la prima famiglia. L'opzione salvata non cambia.

Come si usa: automatico dopo nucleo/tokens-set, l'import del sito e l'import dei font. Vedi il capitolo Design token.

Parametri: Nessuno

Permessi: quelli dell'ability chiamante.

Edizione: Free

Limiti noti: gruppi di token non validi: errore invalid_tokens.

04Dati prodotti e dove vivono

Meta del post

Cosa fa: conserva sorgente, stato e runtime di ogni documento.

Come si usa: lettura con nucleo/doc-get per il documento. Gli altri meta sono interni.

Parametri: Nessuno

Permessi: nessuno.

Edizione: Free

Limiti noti: meta.seo.noindex vero scrive anche il meta noindex letto dalla sitemap.

File e artefatti

Cosa fa: separa i dati serviti al browser da quelli letti dal runtime PHP.

Lo store degli artefatti scrive file PHP <chiave>.<hash8>.php in wp-content/uploads/nucleo/store/<blog>-<generazione>/, sotto la cartella di wp_upload_dir(). Se la cartella non è scrivibile usa le opzioni del database. Fino alla 0.4.0 lo store stava in wp-content/cache/nucleo/: all'aggiornamento Nucleo sposta la generazione del sito nella cartella nuova.

Come si usa: interno.

Parametri: Nessuno

Permessi: nessuno.

Edizione: Free

Limiti noti: un file CSS vuoto resta su disco ma il runtime non lo accoda. Ogni scrittura cancella i file p-<id>.*.css precedenti.

05Runtime del frontend

Avvio del runtime

Cosa fa: registra solo due callback nelle richieste del sito pubblico: wp (priorità 1) e the_content (priorità 9). In wp:

1. carica l'anteprima CSS solo se c'è il parametro nucleo_css;
2. si ferma in modalità di emergenza;
3. prepara le aree dei layout;
4. aggancia le regole asset a wp_enqueue_scripts con priorità 9999;
5. su un contenuto singolo con _nucleo_rt: registra meta SEO e JSON-LD, toglie wpautop e wptexturize, accoda token, stili e script.

Come si usa: automatico. Il tema verifica se la pagina è un documento Nucleo, per non stampare titolo e main propri.

Parametri: Nessuno

Permessi: nessuno.

Edizione: Free

Limiti noti:

• Il font principale si precarica con l'header HTTP Link, solo se gli header non sono già partiti.
• Il runtime non ricompila un documento con _nucleo_rt mancante: serve il post_content così com'è.
• Gli script eager si accodano con defer nel footer. Handle di stili e script: nucleo-<md5 dell'URL, 8 caratteri>.

Riempimento degli slot

Cosa fa: in the_content sostituisce i marcatori di slot del post richiesto con l'HTML generato per la richiesta. Usa strpos, senza espressioni regolari. Poi segna la voce di menu corrente.

Come si usa: automatico. Blocchi di slot riconosciuti: nc/post-title, nc/post-content, nc/post-image, nc/post-meta, nc/breadcrumbs, nc/search, nc/pagination, nc/archive-title, nc/archive-description, nc/visibility, nc/bind, nc/form, nc/collection, nc/native-form, nc/repeater, nc/query, i blocchi woo/* e i nomi storici post.title e post.date. Con un layout single sopra una pagina Nucleo, nc/post-content riempie anche gli slot della pagina: moduli, collezioni e campi collegati.

Parametri: Nessuno

Permessi: nessuno.

Edizione: Free

Limiti noti:

• Slot con blocco sconosciuto o indice assente: resta il fallback.
• Marcatore di chiusura mancante: Nucleo toglie solo il marcatore di apertura.
• Solo nc/visibility e nc/bind si riempiono di nuovo dopo il rendering, fino a 8 livelli di annidamento.
• Il filtro agisce solo sul post della query principale.

Visibilità per visitatore

Cosa fa: valuta visibility.when a ogni richiesta. Mostra il nodo solo se tutte le condizioni valgono.

Come si usa: nel documento. Vedi il capitolo Schema del documento e blocchi.

Parametri: vedi la tabella.

Permessi: nessuno.

Edizione: Free

Limiti noti: condizione sconosciuta: falsa. Cache di pagina e crawler vedono il fallback vuoto.

Caricamento degli script dei blocchi

Cosa fa: carica gli script dei blocchi con la strategia del manifest. eager va in un tag <script defer>. Le strategie visible, interaction e idle passano dal loader degli script, tramite window.ncLazy. Ogni URL riceve ?ver= con la versione del plugin, come gli script accodati da WordPress: dopo un aggiornamento il browser non usa la copia in cache. Se l'URL ha già un parametro ver, Nucleo non aggiunge ?ver=: un parametro con nome diverso, come server, non conta. Per gli script con interaction o idle vale anche il paragrafo sotto la tabella.

Gli script dei manifest con strategia interaction o idle escono come tag type="text/plain" con data-nc-src e data-nc-load. Il loader li attiva tutti insieme, nell'ordine del documento: interaction al primo pointerdown, keydown, scroll o touchstart sulla finestra; idle con requestIdleCallback e timeout di 2 s, oppure dopo 2 s. Le righe della tabella descrivono le voci registrate in window.ncLazy.

Come si usa: automatico. Strategie dei blocchi inclusi: nc/collection, nc/slider e nc/toc usano visible; nc/menu e nc/tabs usano idle; nc/native-form e nc/video usano interaction.

Parametri: Nessuno

Permessi: nessuno.

Edizione: Free

Limiti noti: visible e interaction osservano tutte le istanze del blocco nella pagina; lo script si carica una volta, al primo segnale. Senza IntersectionObserver lo script visible parte subito. Ogni src si carica una sola volta, anche se pagina e layout lo elencano entrambi.

Voce di menu corrente

Cosa fa: aggiunge aria-current="page" e la classe is-current al link della voce corrente dei menu nc/menu, e is-ancestor alle voci antenate. Serve perché l'HTML compilato è uguale per tutte le pagine.

Come si usa: automatico su contenuto e aree. Prima confronta l'oggetto richiesto (post:<id> o term:<id>). Se nessuna voce combacia, confronta l'URL.

Parametri: Nessuno

Permessi: nessuno.

Edizione: Free

Limiti noti: nel confronto per URL ignora la barra finale e i parametri utm_*. Un link # non è mai corrente.

Modalità di emergenza

Cosa fa: disattiva tutto il runtime: niente asset, layout e slot di Nucleo. wpautop e wptexturize restano attivi.

Come si usa: definisci la costante NUCLEO_SAFE_MODE a true in wp-config.php, oppure imposta l'opzione nucleo_safe_mode a un valore vero.

Parametri: Nessuno

Permessi: accesso a wp-config.php o al database.

Edizione: Free

Limiti noti: l'opzione si legge da alloptions.

Elenchi e schede

Cosa fa: disegna le schede di nc/query e nc/collection per ogni elemento. Il ciclo di rendering tiene la pila degli elementi correnti: post, termine o riga di dati. nc/collection aggiorna filtri e pagine con la route REST GET nucleo/v1/collection/<doc>/<node>.

Come si usa: vedi il capitolo Moduli, dati dinamici, componenti, bindings e media.

Parametri: query string dei filtri; append=1 per accodare i risultati.

Permessi: route pubblica (__return_true). Serve solo documenti pubblicati senza password.

Edizione: Free

Limiti noti:

• 60 richieste al minuto per IP, poi errore 429.
• Risposta con Cache-Control: public, max-age=60.
• Pagine di risultati in transient per 12 ore (5 minuti per una sorgente component senza ttl), invalidate da nucleo_content_version.
• Una ricerca testuale attiva non usa la cache.

Regole asset e CSS ottimizzato

Cosa fa: in wp_enqueue_scripts a priorità 9999 applica le regole asset, le varianti CSS ridotte e il CSS critico. Gli amministratori (manage_options) vedono le anteprime con ?nucleo_css=original|candidate|critical|published.

Come si usa: vedi il capitolo Ottimizzatore e asset.

Parametri: vedi il capitolo collegato.

Permessi: anteprima nucleo_css: manage_options.

Edizione: vedi il capitolo collegato.

Limiti noti: vedi il capitolo collegato.

06Hook pubblici

nucleo/document_saved

Cosa fa: azione emessa dopo ogni scrittura riuscita di un documento, anche dopo una ricompilazione.

Come si usa:

add_action('nucleo/document_saved', function (int $postId): void { ... });

Parametri:

Permessi: nessuno.

Edizione: Free

Limiti noti: Nucleo stesso la usa per pubblicare i layout e per ricompilare le pagine di una sezione. Durante il callback il flag di scrittura interno vale true.

nucleo/purge_url

Cosa fa: azione emessa dopo lo svuotamento della cache di un documento non layout. Serve a collegare un sistema di cache non supportato.

Come si usa:

add_action('nucleo/purge_url', function (string $url): void { ... });

Parametri:

Permessi: nessuno.

Edizione: Free

Limiti noti: nessuno rilevato.

nucleo/purge_all

Cosa fa: azione emessa dopo lo svuotamento completo della cache, cioè dopo il salvataggio di un layout.

Come si usa:

add_action('nucleo/purge_all', function (): void { ... });

Parametri: Nessuno

Permessi: nessuno.

Edizione: Free

Limiti noti: nessuno rilevato.

nucleo/current_language

Cosa fa: filtro che sostituisce la lingua corrente usata per scegliere i layout con condizione language.

Come si usa:

add_filter('nucleo/current_language', fn (?string $lang): ?string => 'it');

Parametri:

Permessi: nessuno.

Edizione: Pro. Il filtro esiste solo nel pacchetto Pro.

Limiti noti: vedi il capitolo Integrazioni.

07Layout

Documenti di layout e aree

Cosa fa: un layout è un documento kind layout (o popup) nel tipo di post nucleo_layout. meta.area dice dove va. meta.conditions dice su quali richieste vale. Il runtime usa solo i layout pubblicati.

Come si usa: crea il layout con nucleo/doc-create e postType nucleo_layout. Il tema stampa ogni area con nucleo_canvas_area('<area>'). Vedi il capitolo Tema.

Parametri: meta.area (string), meta.conditions (oggetto).

Permessi: il tipo nucleo_layout richiede edit_theme_options per creare, modificare ed eliminare.

Edizione: Free

Limiti noti:

• Lo schema non valida meta.area. Un'area fuori elenco si salva, ma il runtime non la stampa.
• Layout senza meta.area: escluso dalla mappa.
• Archivi per data e altre richieste non riconosciute (kind other) ricevono solo header, footer e popup.
• I layout ricevono token e asset anche sulle pagine non costruite con Nucleo.

Condizioni di layout

Cosa fa: meta.conditions ha la forma {"include": [...], "exclude": [...], "priority": 0}. Ogni condizione è {"type": "<tipo>", ...chiavi del tipo}.

Come si usa: nel documento del layout, oppure con nucleo/layout-conditions-set, che sostituisce include, exclude e priority. Nei file del sito (layouts/*.json) gli ID si scrivono come simboli (page:<percorso>, term:<tassonomia>/<slug>, author:<login>). Vedi il capitolo Import, export e sincronizzazione.

Parametri:

Permessi: nucleo/layout-conditions-set: edit_post sul layout, scope nucleo:design.

Edizione: Free.

Limiti noti:

• Errori di formato con codice layout_condition: tipo sconosciuto, chiave sconosciuta, chiave mancante, valore del tipo sbagliato. Ogni errore porta l'esempio del formato atteso.
• ID: interi ≥ 1. Una stringa numerica ("12") diventa intero.
• Il salvataggio blocca solo condizioni nuove o cambiate. Un layout salvato prima con condizioni non valide si modifica e si ricompila ancora.
• Un layout con sole condizioni language non vale per nessuna richiesta.
• Senza contesto di lingua (Free, o nessun plugin multilingua) un layout limitato a una lingua vale per tutte.
• parent cerca discendenti con get_pages() sul tipo page.

Mappa dei layout

Cosa fa: trasforma le condizioni di tutti i layout pubblicati nell'artefatto layouts.

• map: area → chiave → voci [id, priorità, lingue], ordinate per priorità decrescente, poi ID decrescente.
• exclude: area → chiave → ID esclusi.
• conflicts: chiavi con due o più layout alla priorità massima, che possono valere nella stessa lingua.

Scrive anche l'artefatto layout-<id> con HTML, runtime e impostazioni popup di ogni layout pubblicato.

Come si usa: automatica quando un layout pubblicato si salva o si ricompila, quando smette di essere pubblicato e quando si cancella. I conflitti si leggono con nucleo/layout-list.

Parametri: Nessuno

Permessi: nessuno.

Edizione: Free

Limiti noti: le condizioni parent e children diventano chiavi esplicite al momento della ricostruzione. Una pagina figlia o un termine figlio creati dopo entrano nella mappa solo alla ricostruzione successiva. Per forzarla: salva di nuovo il layout, oppure usa nucleo/cache-rebuild.

Scelta del layout per la richiesta

Cosa fa: per ogni area costruisce le chiavi della richiesta dalla più specifica alla più generale. Restituisce il primo layout trovato che non è escluso e che parla la lingua della richiesta.

Come si usa: automatica a ogni richiesta. Per un URL, nucleo/layout-explain restituisce per ogni area {layout, matched}, e excluded con il layout scartato e la chiave che lo ha escluso.

Parametri: Nessuno

Permessi: nucleo/layout-explain: edit_theme_options, scope nucleo:read.

Edizione: Free

Limiti noti:

• La specificità della chiave conta prima della priorità. Un layout post:<id> con priorità 0 vince su un layout site con priorità 100.
• Per un contenuto in più termini vince il primo termine che ha un layout, nell'ordine delle tassonomie e dei termini restituiti da WordPress.
• La risoluzione non esegue query proprie: usa i termini già in cache della query principale.

Popup

Cosa fa: un layout nell'area popup diventa un <dialog class="nc-popup"> con pulsante di chiusura. Il primo titolo del contenuto etichetta il dialog. Senza titolo il dialog usa il titolo del layout. Lo script del popup gestisce apertura e frequenza.

Come si usa: documento kind popup con meta.area popup nel tipo nucleo_layout.

Parametri:

Permessi: come i layout.

Edizione: Pro.

Limiti noti: nel pacchetto Free un popup pubblicato non si stampa, ma il runtime accoda comunque i suoi stili e script.

08Sezioni riutilizzabili

Blocco nc/section-ref

Cosa fa: inserisce una sezione riutilizzabile (documento kind section, tipo nucleo_section) per slug. Al salvataggio e a ogni ricompilazione Nucleo sostituisce il nodo con il root della sezione e applica i parametri.

Come si usa:

{ "id": "cta1", "type": "nc/section-ref",
  "settings": { "section": "cta-contatti", "params": { "titolo": "Parliamone" } } }

Elenco delle sezioni e dei loro parametri: nucleo/section-list.

Parametri:

Permessi: il tipo nucleo_section richiede edit_theme_options per creare, modificare ed eliminare. Le sezioni in bozza, in attesa, private o programmate si espandono solo per chi ha edit_theme_options, e senza utente (WP-Cron, WP-CLI). Gli altri utenti espandono solo sezioni pubblicate.

Edizione: Free

Limiti noti:

• Profondità massima di sezioni annidate: 4.
• Un ciclo (A dentro B dentro A) è un errore sul nodo nc/section-ref esterno.
• Sezione mancante o nel cestino: il blocco non stampa nulla e il report ha l'avviso content.section.missing.
• visibility del nodo nc/section-ref passa al root espanso.
• Gli ID dei nodi espansi cambiano per ogni istanza: prime 4 lettere dell'ID del nodo ref più 8 caratteri di hash.
• Il blocco accetta visibility ma nessuna chiave di stile.
• Una sezione nuova riceve lo slug alla creazione anche in bozza.

Parametri di sezione

Cosa fa: la sezione dichiara in params i valori che ogni nc/section-ref può passare. Ogni dichiarazione ha type, e facoltativi label, required, default.

Come si usa: nella sezione i valori si usano in tre modi.

• bind con "source": "param": {"content.text": {"source": "param", "field": "titolo"}}. Chiavi ammesse: content.*, settings.*, style.*, visible. field accetta un sotto-campo (immagine.alt). Un'immagine senza sotto-campo dà la src.
• bind.repeat su un figlio: una copia del nodo per ogni voce di un parametro list. Nella copia la voce vale come parametro item.
• $param.<nome> in un valore di style, anche dentro un valore composto (1px solid $param.colore). Solo parametri color.

Parametri: nome del parametro: ^[a-z][a-z0-9_]{0,31}$.

Permessi: come le sezioni.

Edizione: Free

Limiti noti:

• Ordine dei valori: valore passato, poi default, poi null.
• Parametro required senza valore né default: errore nella pagina che usa la sezione. Nel documento della sezione da solo non è un errore.
• visible toglie il nodo se il valore è false. Per text, html, link, image lo toglie anche se il valore è vuoto o assente.
• Senza valore né fallback il bind lascia il valore scritto nel nodo, che fa da segnaposto.
• $param non risolto: la proprietà di stile resta fuori.
• Errori: parametro non dichiarato, tipo sbagliato, repeat su un parametro non list, repeat o visible sul root della sezione, bind param fuori da una sezione.

Posizione degli errori nelle sezioni

Cosa fa: riporta gli errori di validazione e qualità dei nodi espansi sul nodo nc/section-ref del documento. Così l'agente corregge il documento che ha scritto.

Come si usa: automatica.

Parametri: Nessuno

Permessi: nessuno.

Edizione: Free

Limiti noti:

• Valore arrivato da un parametro: il percorso diventa .../settings/params/<nome>.
• Altri errori: il percorso diventa .../settings/section e il messaggio inizia con inside section: .
• Un errore di stile perde il suggerimento con gli ID interni.
• Nel report di qualità il messaggio termina con (inside a reusable section).
• Errori uguali sullo stesso percorso compaiono una volta.

Aggiornamento delle pagine che usano una sezione

Cosa fa: quando una sezione si salva, cambia slug o va nel cestino, Nucleo ricompila i documenti che la usano. Li trova con le dipendenze section:<id> e section-slug:<slug>. La seconda trova anche i documenti che citavano la sezione quando ancora mancava.

Come si usa: automatico.

Parametri: Nessuno

Permessi: nessuno.

Edizione: Free

Limiti noti: i primi 10 documenti si ricompilano nella stessa richiesta. Gli altri vanno nella coda di WP-Cron. Se la sezione rende un documento non valido o bloccante, la pagina pubblicata tiene la versione precedente.

Riferimento storico ref

Cosa fa: un nodo con il campo ref "section:<id>" diventa il root del documento indicato durante la normalizzazione. Gli ID interni ricevono il prefisso g<id>.

Come si usa: formato precedente a nc/section-ref. Per i documenti nuovi usa nc/section-ref.

Parametri: ref (string, section:<id>).

Permessi: nessuno.

Edizione: Free

Limiti noti: il documento referenziato non segue altri ref. Dentro una sezione riusabile ref è un errore. Dentro una sezione espansa il nodo sparisce senza errore.