Migrazione a v7
Questa guida descrive le modifiche da apportare per passare da Blockstudio 6 a 7.
Import ES Module
Nuovo prefisso npm: (consigliato)
Blockstudio 7 introduce un nuovo prefisso npm: per le importazioni dei moduli ES, in linea con la convenzione degli specificatori Denonpm.
Prima (v6):
import { h, render } from "blockstudio/preact@10.15.1";
import htm from "blockstudio/htm@3.1.1";
import confetti from "blockstudio/canvas-confetti@1.6.0";
Dopo (v7):
import { h, render } from "npm:preact@10.15.1";
import htm from "npm:htm@3.1.1";
import confetti from "npm:canvas-confetti@1.6.0";
Import CSS
La stessa modifica si applica agli import CSS:
Prima (v6):
import "blockstudio/swiper@11.0.0/swiper.min.css";
Dopo (v7):
import "npm:swiper@11.0.0/swiper.min.css";
Compatibilità con le versioni precedenti
Il prefisso blockstudio/ è ancora supportato per garantire la compatibilità con le versioni precedenti. Il codice esistente continuerà a funzionare senza modifiche. Tuttavia, consigliamo di passare al prefisso npm: per uniformarsi all’ecosistema JavaScript più ampio.
Il prefisso npm: offre diversi vantaggi:
- Allineamento con l’ecosistema – Rispecchia la convenzione consolidata di Deno
- Chiarezza – Rende subito evidente che si importa da npm
- Compatibilità futura – Il prefisso
blockstudio/potrebbe essere deprecato in una futura versione principale
Nomi degli hook
Blockstudio 7 uniforma tutti i nomi degli hook PHP usando snake_case al posto di camelCase, in linea con le convenzioni del core di WordPress.
Nomi degli hook modificati
| Nome precedente (v6) | Nuovo nome (v7) |
|---|---|
blockstudio/blocks/components/useblockprops/render |
blockstudio/blocks/components/use_block_props/render |
blockstudio/blocks/components/innerblocks/render |
blockstudio/blocks/components/inner_blocks/render |
blockstudio/blocks/components/innerblocks/frontend/wrap |
blockstudio/blocks/components/inner_blocks/frontend/wrap |
blockstudio/blocks/components/richtext/render |
blockstudio/blocks/components/rich_text/render |
blockstudio/assets/process/scss/importPaths |
blockstudio/assets/process/scss/import_paths |
blockstudio/settings/assets/process/scssFiles |
blockstudio/settings/assets/process/scss_files |
blockstudio/settings/editor/formatOnSave |
blockstudio/settings/editor/format_on_save |
blockstudio/settings/blockEditor/disableLoading |
blockstudio/settings/block_editor/disable_loading |
blockstudio/settings/blockEditor/cssClasses |
blockstudio/settings/block_editor/css_classes |
blockstudio/settings/blockEditor/cssVariables |
blockstudio/settings/block_editor/css_variables |
blockstudio/settings/ai/enableContextGeneration |
blockstudio/settings/ai/enable_context_generation |
Compatibilità con le versioni precedenti
I vecchi nomi degli hook in camelCase sono ancora supportati per garantire la compatibilità con le versioni precedenti. Il codice esistente continuerà a funzionare senza modifiche. Tuttavia, consigliamo di passare ai nuovi nomi in snake_case per uniformità.
Esempio di migrazione:
// Before (v6)
add_filter('blockstudio/settings/blockEditor/cssClasses', function() {
return ['my-stylesheet'];
});
// After (v7)
add_filter('blockstudio/settings/block_editor/css_classes', function() {
return ['my-stylesheet'];
});
Tag canonici dei blocchi
Blockstudio 7.6 mantiene i prefissi di progetto e gli alias esatti come punti di estensione a runtime, ma usa <bs:namespace-slug> come grafia canonica negli esempi, nell’output del catalogo, nelle dichiarazioni di rendering e nei diagnostici. I tag canonici riportano il vero nome del blocco registrato e non dipendono da un filtro specifico dell’host.
Per un progetto con brand => ["theme-components"] e ui => ["bsui"]:
<!-- Legacy project shorthand -->
<brand-card>
<ui-input />
</brand-card>
<!-- Canonical output -->
<bs:theme-components-card>
<bs:bsui-input />
</bs:theme-components-card>
Un comando di migrazione autonomo analizza un progetto esistente e riscrive le forme abbreviate nella grafia canonica. Genera prima un report, si interrompe in presenza di casi irrisolti e modifica solo i nomi dei tag. Consultate Migrazione dei tag dei blocchi per conoscere il comando, i relativi input e le misure di sicurezza.
Nomi dei file degli asset
Blockstudio 7 introduce la notazione con il punto per i suffissi dei file degli asset, sostituendo la vecchia notazione con il trattino come convenzione consigliata.
Nomi dei file modificati
| Nome precedente (v6) | Nuovo nome (v7) |
|---|---|
*-inline.(s)css |
*.inline.(s)css |
*-inline.js |
*.inline.js |
*-editor.(s)css |
*.editor.(s)css |
*-editor.js |
*.editor.js |
*-scoped.(s)css |
*.scoped.(s)css |
*-view.js |
*.view.js |
Compatibilità con le versioni precedenti
La vecchia notazione con il trattino è ancora supportata per garantire la compatibilità con le versioni precedenti. I file esistenti continueranno a funzionare senza rinominarli. Tuttavia, consigliamo di usare la notazione con il punto per i nuovi blocchi.
Esempio di migrazione:
my-block/
├── block.json
├── index.php
├── style.css
├── style-inline.css → style.inline.css
├── style-scoped.css → style.scoped.css
├── style-editor.css → style.editor.css
├── script.js
├── script-inline.js → script.inline.js
├── script-editor.js → script.editor.js
└── script-view.js → script.view.js
Interruttore del campo
La proprietà switch ora è impostata su false per impostazione predefinita, anziché su true. In v6, ogni campo aveva un interruttore invisibile sul bordo sinistro, attivo per impostazione predefinita. In v7, l’interruttore è facoltativo e usa un’icona a forma di occhio visibile nell’etichetta del campo.
Modifiche apportate
- Il valore predefinito ora è
false: i campi non hanno più un interruttore, a meno che non impostiate esplicitamente"switch": true - Icona a forma di occhio visibile: al posto di un’area cliccabile nascosta sul lato sinistro, nell’area dell’etichetta compare un pulsante con l’icona di un occhio
- Sovrapposizione per i campi disabilitati: quando un campo è disabilitato, viene mostrata una sovrapposizione sfocata con il testo «Questo campo è disabilitato», invece di ridurne semplicemente l’opacità
Migrazione
Se facevate affidamento sul comportamento predefinito dell’interruttore in v6, dovete attivarlo esplicitamente:
{
"id": "title",
"type": "text",
"label": "Title",
"switch": true
}
Se in precedenza avevate impostato "switch": false per disattivare l’interruttore, potete rimuoverlo perché ora false è il valore predefinito.
Tailwind CSS
Blockstudio 7 sostituisce completamente l’approccio v6 Tailwind. In v6, Tailwind CSS veniva compilato lato client tramite CDN nell’editor e salvato su disco al salvataggio del post. In v7, Tailwind CSS viene compilato lato server a ogni richiesta frontend tramite TailwindPHP, con memorizzazione automatica nella cache basata sui file.
Consultate la documentazione di Tailwind CSS per tutti i dettagli sul nuovo sistema.
Compilazione sempre attiva lato server
Quando tailwind.enabled è true, ogni richiesta frontend viene compilata lato server. Il flusso di compilazione:
- WordPress esegue il rendering dell’intera pagina HTML in un buffer di output
- I candidati delle classi CSS vengono estratti da HTML (regex veloce, senza compilazione)
- I candidati vengono ordinati e sottoposti a hash con la configurazione CSS per creare una chiave cache
- In caso di cache hit: il file CSS memorizzato nella cache viene letto e inserito
- In caso di cache miss: TailwindPHP compila CSS, lo scrive nella cache runtime condivisa di Blockstudio nell’ambito
tailwinde lo inserisce
Il CSS compilato viene inserito come tag <style id="blockstudio-tailwind"> inline prima di </head>. Include il preflight di Tailwind e tutte le classi utility corrispondenti.
Lo script CDN rimane attivo nell’editor solo per l’anteprima in tempo reale. Non viene mai fornito nel frontend.
Modifica del formato config
La proprietà config è passata da un oggetto JSON (Tailwind v3) a una stringa CSS (sintassi Tailwind v4 CSS-first).
Prima (v6):
{
"tailwind": {
"config": {
"theme": {
"extend": {
"colors": {
"primary": "pink"
}
}
}
}
}
}
Dopo (v7):
{
"tailwind": {
"config": "@theme { --color-primary: pink; }"
}
}
Impostazione customClasses rimossa
L’impostazione array customClasses è stata rimossa. Con l’approccio CSS-first di Tailwind v4, le classi utility personalizzate vengono definite direttamente nella stringa config usando @layer utilities.
Prima (v6):
{
"tailwind": {
"customClasses": [
{ "className": "btn", "value": "px-4 py-2 rounded-lg font-medium" },
{ "className": "card", "value": "bg-white rounded-xl shadow-lg p-6" }
]
}
}
Dopo (v7):
{
"tailwind": {
"config": "@layer utilities { .btn { @apply px-4 py-2 rounded-lg font-medium; } .card { @apply bg-white rounded-xl shadow-lg p-6; } }"
}
}
Oppure tramite il filtro per configurazioni su più righe:
add_filter('blockstudio/settings/tailwind/config', function () {
return <<<CSS
@layer utilities {
.btn { @apply px-4 py-2 rounded-lg font-medium; }
.card { @apply bg-white rounded-xl shadow-lg p-6; }
}
CSS;
});
Anche il filtro blockstudio/settings/tailwind/custom_classes è stato rimosso. Per aggiungere regole CSS personalizzate, usate invece il filtro blockstudio/tailwind/css.
Endpoint REST rimosso
L’endpoint POST /blockstudio/v1/editor/tailwind/save è stato rimosso. Il codice CSS compilato non viene più salvato dall’editor. Se il vostro codice personalizzato chiamava questo endpoint, potete rimuoverlo senza problemi.
Memorizzazione nella cache
Blockstudio usa una strategia di memorizzazione nella cache basata sui candidati. Anziché calcolare l’hash dell’intera pagina HTML (operazione che invaliderebbe la cache a ogni richiesta a causa di nonce e timestamp), calcola l’hash solo dei candidati delle classi CSS. Questo significa che:
- Due pagine con le stesse classi CSS condividono lo stesso file memorizzato nella cache
- I contenuti dinamici (nonce, barre di amministrazione, timestamp) non invalidano la cache
- La cache viene invalidata solo quando cambia l’insieme delle classi CSS o la configurazione
I file della cache usano la root runtime Blockstudio configurata in
sites/{network-blog}/{runtime-identity}/tailwind/. Chiamate
Blockstudio\Runtime_Cache::purge('tailwind') per forzare la ricompilazione.
Modifiche ai filtri
| Nome precedente (v6) | Nuovo nome (v7) |
|---|---|
blockstudio/tailwind/on_demand/css |
blockstudio/tailwind/css |
blockstudio/tailwind/assets/dir |
Rimosso |
blockstudio/settings/tailwind/custom_classes |
Rimosso |
File e caricamenti rimossi
In v6, Tailwind CSS veniva caricato come fogli di stile esterni (blockstudio-tailwind, blockstudio-tailwind-preflight). In v7, tutto CSS viene inserito inline tramite un buffer di output. Nel frontend non ci sono tag link né fogli di stile caricati per Tailwind.
Libreria dei blocchi
La libreria integrata «Elementi Blockstudio» è stata rimossa. L’impostazione library in blockstudio.json e il filtro blockstudio/settings/library non hanno più alcun effetto.
Se usavate i blocchi della libreria (Gallery, Slider, Image Comparison, Code, Icon), copiate le cartelle dei blocchi dalla directory includes/library/blockstudio-element/ dell’installazione v6 nella directory blockstudio del tema e aggiornate i relativi file block.json con i nuovi nomi e le nuove categorie.