Tema nucleo-canvas

01Panoramica

nucleo-canvas è un tema classico minimo. Fornisce l'involucro HTML della pagina: header.php, index.php, footer.php e un CSS di base.

Con il plugin attivo, il tema stampa i layout Nucleo delle aree: header, footer, single, archivio, ricerca, 404, popup e fasce prima e dopo il contenuto.

Senza plugin, o senza un layout per l'area, il tema stampa un markup di base. Il contenuto delle pagine Nucleo resta leggibile perché il post salva l'HTML compilato.

Il tema non registra menu né sidebar e non ha un file theme.json su disco. I colori e i font arrivano dalle variabili CSS --nc-* pubblicate dal plugin, e i token pubblicati arrivano anche all'editor a blocchi: vedi Token nell'editor.

Il tema si aggiorna dal server https://updates.nucleowp.dev senza licenza. L'updater si carica solo in admin, in cron e da WP-CLI.

Il plugin legge dal tema solo base.css, per l'anteprima dell'editor e per catalog-get {topic: theme}.

02Installazione e requisiti

Intestazione del tema

Cosa fa: dichiara nome, versione, requisiti, host degli aggiornamenti e dominio di traduzione.

Come si usa: si installa come tema WordPress dallo zip nucleo-canvas-<versione>.zip, prodotto da nucleo/bin/build.

Parametri: campi di style.css:

Permessi: installazione e attivazione richiedono le capability WordPress dei temi (install_themes, switch_themes).

Edizione: Free.

Limiti noti:

• Requires Nucleo è un'intestazione propria: WordPress non la applica. nucleo/bin/version la allinea a ogni rilascio insieme a Version. L'updater locale non la legge: usa requires_nucleo della risposta del server.
• Lo slug del tema deve essere nucleo-canvas. L'updater e catalog-get {topic: theme} riconoscono il tema solo con questo slug.
• La build produce due zip: nucleo-canvas-<v>.zip con l'updater e nucleo-canvas-wporg-<v>.zip per WordPress.org, senza inc/updates.php, Update URI e Requires Nucleo.

Supporti del tema

Cosa fa: carica le traduzioni e registra i supporti del tema su after_setup_theme.

Come si usa: automatico all'attivazione.

Parametri: supporti registrati:

Permessi: nessuno.

Edizione: Free.

Limiti noti: il tema non registra sidebar né un file theme.json. La palette arriva dai token pubblicati dal plugin. Il menu primary compare solo senza un layout Nucleo dell'area header: con il plugin la navigazione passa da nc/menu.

03Template

Header

Cosa fa: stampa <head> con wp_head(), apre <body> con body_class() e wp_body_open(). Aggiunge il link "Vai al contenuto" verso #main. Poi stampa il layout dell'area header.

Come si usa: automatico, con get_header().

Parametri: nessuno.

Permessi: nessuno.

Edizione: Free.

Limiti noti: senza layout header, il tema stampa <header class="site-header"> con un link alla home e il nome del sito. Se l'area è disattivata, cioè documento con layout none o scelta "Nessuno" della pagina per l'header, il tema non stampa nulla.

Contenuto

Cosa fa: avvolge il contenuto e sceglie cosa stampare secondo la richiesta.

Come si usa: automatico. index.php vale per tutte le richieste. Con WooCommerce attivo, prodotto, negozio e archivi di prodotto passano da woocommerce.php: con un layout Nucleo dell'area product, single, product-archive o archive usa index.php, altrimenti stampa woocommerce_content() dentro <main id="main">.

Parametri: ordine delle scelte:

Il contenitore è <div id="main"> quando la pagina ha già un <main>: la radice del documento ha settings.tag main, oppure un layout dell'area lo contiene. Negli altri casi è <main id="main">, anche per un documento Nucleo con radice section.

Permessi: nessuno.

Edizione: Free.

Limiti noti:

• Il plugin applica before-content e after-content solo a contenuti singoli e archivi. Su ricerca e 404 le chiamate del tema non stampano nulla.
• Sulla ricerca il ripiego all'area archive non stampa mai nulla. Il plugin applica archive solo ai tipi term_archive, post_type_archive, author_archive e blog, non a search. Senza un layout search il tema usa il loop.

Footer

Cosa fa: stampa il layout dell'area footer, poi il layout dell'area popup, poi wp_footer().

Come si usa: automatico, con get_footer().

Parametri: nessuno.

Permessi: nessuno.

Edizione: Free.

Limiti noti: senza layout footer, il tema stampa <footer class="site-footer"> con ©, l'anno corrente e il nome del sito. Se l'area è disattivata dal documento o dalla pagina, il tema non stampa nulla.

04Funzionamento con e senza plugin

Riconoscimento dei documenti Nucleo

Cosa fa: nucleo_canvas_is_document() dice se la richiesta corrente è un documento Nucleo singolo. Con il plugin attivo usa il riconoscimento del plugin. Senza plugin usa nucleo_canvas_has_document_meta(), che controlla il meta _nucleo_doc del post.

Come si usa: funzioni PHP globali. nucleo_canvas_is_document(): bool, nucleo_canvas_has_document_meta(int $postId): bool.

Parametri:

Permessi: nessuno.

Edizione: Free.

Limiti noti: fuori da is_singular() la funzione restituisce sempre false.

Stampa delle aree

Cosa fa: nucleo_canvas_area(string $area): bool stampa l'HTML del layout Nucleo dell'area per la richiesta corrente. Restituisce false se non stampa nulla: il tema usa allora il markup di base.

Come si usa: funzione PHP globale. Esempio: if (!nucleo_canvas_area('header')) { /* markup di base */ }.

Parametri:

Permessi: nessuno.

Edizione: Free.

Limiti noti:

• Senza il plugin restituisce sempre false.
• La scelta del layout per area e condizioni è del plugin: vedi Compilatore e runtime.
• Le aree product e product-archive sono chiamate dal tema nel template del contenuto: vedi la tabella di Contenuto.

Ripiego senza plugin

Cosa fa: senza plugin il tema funziona da solo. Header e footer usano il markup di base. Le pagine Nucleo mostrano il contenuto salvato, che è l'HTML compilato con il suo <h1> e il suo <main>. Le pagine classiche mostrano il titolo del tema.

Come si usa: automatico quando il plugin è disattivato.

Parametri: nessuno.

Permessi: nessuno.

Edizione: Free.

Limiti noti: senza plugin non ci sono layout, token pubblicati né popup. base.css usa i valori di ripiego.

05Stili e design token

CSS di base

Cosa fa: carica base.css su tutte le pagine del frontend, con handle nucleo-canvas-base. Il file imposta box-sizing, tipografia, link, focus visibile, immagini fluide e la classe .screen-reader-text. Dà larghezza e padding solo al markup del tema (main#main>article, .site-header, .site-footer).

Come si usa: automatico, su wp_enqueue_scripts.

Parametri: variabili CSS lette, con il valore di ripiego:

Permessi: nessuno.

Edizione: Free.

Limiti noti:

• La versione dello stile segue Version del tema: a ogni rilascio cambia l'indirizzo del file, quindi il browser non riusa la versione precedente.
• Le variabili hanno valore solo quando il plugin pubblica i token. Vedi Design token.

Token nell'editor

Cosa fa: il tema non ha un theme.json su disco. Quando il plugin pubblica i token, ne salva il theme.json e il tema lo unisce ai dati di WordPress con il filtro wp_theme_json_data_theme: palette e font dei token arrivano così all'editor a blocchi. Senza plugin, o senza token pubblicati, il filtro non cambia nulla. L'anteprima dell'editor di Nucleo carica base.css del tema attivo e il CSS dei token pubblicati dal plugin.

Come si usa: automatico. Nell'editor a blocchi per palette e font; nell'anteprima dell'editor Nucleo (POST /nucleo/v1/preview) per il CSS.

Parametri: nessuno.

Permessi: quelli dell'editor di Nucleo per l'anteprima. Vedi Backend.

Edizione: Free.

Limiti noti: l'anteprima carica base.css di qualunque tema attivo che ne abbia uno, non solo di nucleo-canvas. Senza il plugin il filtro non agisce.

Descrizione del tema per gli agenti

Cosa fa: catalog-get {topic: theme} restituisce le regole dell'involucro della pagina e, in data.css, il contenuto di base.css.

Come si usa: ability nucleo/catalog-get con {"topic": "theme"}. Vedi Abilities di lettura.

Parametri: nessuno oltre a topic.

Permessi: current_user_can('edit_posts'). Scope OAuth nucleo:read.

Edizione: Free.

Limiti noti: data.css è vuoto se il tema attivo non ha slug nucleo-canvas o se base.css non è leggibile.

06Aggiornamenti

Updater del tema

Cosa fa: risponde al filtro update_themes_updates.nucleowp.dev di WordPress. Chiede al server se esiste una versione nuova e la propone nella schermata degli aggiornamenti.

Come si usa: automatico. WordPress applica il filtro durante il controllo degli aggiornamenti dei temi. Il tema carica inc/updates.php solo se is_admin(), wp_doing_cron() o WP-CLI.

Parametri: richiesta POST <base>/theme/check, con Content-Type: application/json e timeout 10 secondi:

Campi letti dalla risposta: version, package, requires, requires_php, requires_nucleo.

Permessi: nessuno da parte del tema. L'installazione dell'aggiornamento segue le capability WordPress (update_themes).

Edizione: Free. La richiesta non contiene una chiave di licenza.

Limiti noti:

• Agisce solo per lo slug nucleo-canvas.
• Ignora la risposta se lo stato HTTP non è 200, se version non ha la forma X.Y.Z o se package non inizia con https://.
• Con il plugin installato, ignora una versione il cui requires_nucleo supera NUCLEO_VERSION. Senza plugin non applica vincoli.
• Il frontend non contatta il server.
• Il nome del filtro dipende dall'host di Update URI: cambiare l'host richiede una versione del tema che lo dichiari.

Filtro nucleo_canvas/updates_api

Cosa fa: cambia l'indirizzo base del server degli aggiornamenti.

Come si usa: add_filter('nucleo_canvas/updates_api', fn () => 'https://esempio.test');

Parametri:

Permessi: nessuno.

Edizione: Free.

Limiti noti: il filtro cambia solo l'indirizzo della richiesta. Il nome del filtro WordPress resta legato all'host della costante. Il filtro va aggiunto prima del controllo, in un contesto dove l'updater è caricato.

07Traduzioni

Dominio nucleo-canvas

Cosa fa: carica le traduzioni da languages/ su after_setup_theme.

Come si usa: automatico secondo la lingua del sito.

Parametri: lingue incluse:

Permessi: nessuno.

Edizione: Free.

Limiti noti: il tema non include un file .pot.

08Riepilogo dei nomi pubblici