Vai al contenuto

Canvas

La canvas offre una panoramica ingrandita verso l’esterno, simile a Figma, di tutte le pagine gestite da Blockstudio. Ogni pagina viene visualizzata come una tavola da disegno iframe dal vivo, in un’unica riga orizzontale. Spostatevi con il trackpad e ingrandite o riducete con il pinch o Ctrl+scroll.

Attivazione

La canvas è disponibile come pagina di amministrazione nascosta. Andate a:

Codice
/wp-admin/admin.php?page=blockstudio-canvas

La pagina è accessibile solo quando dev.canvas.enabled è true e l’utente corrente dispone della capability edit_posts.

Impostazioni

Abilitate la canvas e configuratene il comportamento in blockstudio.json del tema:

JSON
{
  "dev": {
    "canvas": {
      "enabled": true,
      "adminBar": false
    }
  }
}
Proprietà Tipo Predefinito Descrizione
enabled boolean false Abilita la funzione canvas.
adminBar boolean true Mostra la barra di amministrazione WordPress negli iframe delle tavole. Impostate false per un’anteprima più pulita.

Entrambe le impostazioni sono disponibili anche come filtri:

PHP
add_filter('blockstudio/settings/dev/canvas/enabled', '__return_true');
add_filter('blockstudio/settings/dev/canvas/admin_bar', '__return_false');

Viste

Passate da una vista all’altra usando il menu a discesa nell’angolo in alto a destra.

  • Pagine: tutte le pagine gestite da Blockstudio come tavole a tutta larghezza in un’unica riga.
  • Blocchi: tutti i blocchi Blockstudio registrati in una griglia, ciascuno visualizzato con i valori predefiniti degli attributi.

Inventario pubblico e API dei documenti

Canvas espone un contratto PHP neutrale rispetto ai consumer e con versione, per gli strumenti che necessitano degli stessi contenuti registrati senza ricreare la logica di rilevamento o rendering di Blockstudio:

PHP
use Blockstudio\Canvas;

$all = Canvas::inventory();

$changed = Canvas::inventory([
  'blocks' => ['theme/hero'],
  'pages' => ['about'],
]);

$documents = Canvas::documents([
  'patterns' => ['theme/featured'],
  'templates' => ['front-page'],
]);

La versione corrente è disponibile come Canvas::SCHEMA_VERSION. I risultati dell’inventario contengono:

  • inventory: pages, blocks, patterns, templates, parts normalizzati ed esempi della famiglia ui pubblica
  • order: l’ordine stabile di visualizzazione tra tipi diversi
  • sources: percorsi sorgente selezionati esatti con provenienza per ogni record; source di un record di pagina è la sua identità sorgente stabile, mentre path è il percorso fisico del modello di rendering
  • warnings e errors: problemi strutturati anziché output generato
  • deleted: identificatori richiesti che non esistono più
  • selection: la selezione normalizzata e l’indicazione se è stata mirata

Canvas::documents() aggiunge un documento di rendering completo per ogni record selezionato. Ogni documento contiene il corpo, HTML assemblato, i nomi dei blocchi con dipendenze risolte e gli esatti CSS, JavaScript, moduli, bootstrap dell’interattività, globali UI inclusi e output Tailwind. I documenti delle pagine usano un wrapper semantico di contenuti <main>; i chiamanti possono sovrascriverlo o disabilitarlo tramite le opzioni condivise del documento Render. Ogni pagina selezionata viene renderizzata nel proprio contesto WordPress del frontend ripristinato, così le condizioni delle query, i filtri delle classi del body, gli shortcode, i layout, i reindirizzamenti e le callback di wp_enqueue_scripts agiscono sulla pagina stessa invece che sulla richiesta di amministrazione o REST che ha richiesto il risultato Canvas. Le classi del body fornite dal chiamante vengono unite a quelle contestuali della pagina e i registri di enqueue del frontend sono isolati tra i documenti. Canvas risolve queste callback del ciclo di vita tramite i nomi pubblici delle funzioni WordPress, preservando così lo stesso contesto quando Blockstudio viene caricato tramite Composer o un namespace applicativo ricollocato.

Semantica della selezione esatta

La selezione è rigorosa:

  • Se non sono presenti chiavi di tipo riconosciute, vengono caricati tutti i tipi.
  • true, null o "*" carica tutti i record di quel tipo.
  • Una stringa o un elenco carica solo gli ID, i nomi, gli slug, i percorsi o i percorsi sorgente esatti.
  • Una stringa/elenco vuoto o false non carica alcun record di quel tipo.
  • Una volta presente una chiave di tipo, gli altri tipi omessi non vengono rilevati, sincronizzati, renderizzati o compilati.

In questo modo le richieste limitate agli elementi modificati sono sicure anche per i progetti di grandi dimensioni. I blocchi e le pagine esistenti vengono risolti tramite i registri canonici. Quando una richiesta del frontend ha caricato solo la proiezione persistita della pagina, Canvas esegue un rilevamento di sola lettura delle sorgenti e unisce gli ID dei post e i permalink corrispondenti senza sincronizzare il contenuto. La stessa unione delle identità si applica quando una sorgente di rilevamento logica popola prima il registro basato sulle sorgenti, così il rendering contestuale della pagina usa ancora il post WordPress gestito corrispondente. La nuova topologia della sessione dal vivo viene rilevata solo attorno alla directory modificata, mentre le sorgenti selezionate dei pattern e dei template di Site Editor vengono compilate solo dopo la selezione.

L’endpoint di aggiornamento REST segue la stessa regola per i parametri di query esistenti blocks e pages. Ad esempio, ?blocks=theme/hero restituisce quel blocco e nessuna pagina; usate entrambi i parametri per una risposta mista. Chiamare l’endpoint senza nessuno dei due parametri mantiene la risposta legacy completa.

Modalità dal vivo

La modalità dal vivo usa Server-Sent Events (SSE) per rilevare le modifiche ai file e aggiornare la canvas in tempo reale. Quando modificate un template di blocco, un template di pagina o un foglio di stile, le tavole da disegno interessate si aggiornano automaticamente entro circa un secondo.

Attivate o disattivate la modalità dal vivo dal menu a discesa. Quando è attiva, compare un indicatore verde pulsante. L’impostazione viene mantenuta tra le sessioni tramite localStorage.

La modalità dal vivo monitora le modifiche ai file .php, .json, .css, .scss, .js, .twig e .html nelle directory dei blocchi e delle pagine. Le modifiche note aggiornano solo il blocco o la pagina registrati. Un blocco o una pagina nuovi vengono rilevati con un unico passaggio sulla relativa directory, così è possibile creare contenuti durante una sessione dal vivo aperta senza esaminare di nuovo sorgenti non pertinenti.

Modalità focus

Fate clic sull’etichetta di una tavola da disegno per attivare la modalità focus. La tavola selezionata occupa l’intera larghezza della finestra e può scorrere verticalmente. Premete Escape o fate clic sul pulsante di chiusura per tornare alla panoramica.

Comandi

Azione Input
Spostamento Scorrimento / trascinamento con due dita sul trackpad
Zoom Ctrl+scorrimento o pinch
Adatta alla vista Menu a discesa
Zoom al 100% Menu a discesa
Focus sulla tavola da disegno Fai clic sull’etichetta della tavola
Esci dal focus Escape / pulsante di chiusura

Sicurezza

Lo script canvas e i dati della pagina vengono caricati solo quando tutte le condizioni sono soddisfatte:

  • L’impostazione dev.canvas.enabled è true.
  • L’utente corrente dispone della capability edit_posts.

I visitatori pubblici non vedono mai lo script canvas né i metadati della pagina.