Vai al contenuto

Migrazione a v7

Questa guida descrive le modifiche da apportare per passare da Blockstudio 6 a 7.

Import ES Module

Blockstudio 7 introduce un nuovo prefisso npm: per le importazioni dei moduli ES, in linea con la convenzione degli specificatori Denonpm.

Prima (v6):

JavaScript
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):

JavaScript
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):

JavaScript
import "blockstudio/swiper@11.0.0/swiper.min.css";

Dopo (v7):

JavaScript
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:

PHP
// 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"]:

HTML
<!-- 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:

Codice
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:

JSON
{
  "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:

  1. WordPress esegue il rendering dell’intera pagina HTML in un buffer di output
  2. I candidati delle classi CSS vengono estratti da HTML (regex veloce, senza compilazione)
  3. I candidati vengono ordinati e sottoposti a hash con la configurazione CSS per creare una chiave cache
  4. In caso di cache hit: il file CSS memorizzato nella cache viene letto e inserito
  5. In caso di cache miss: TailwindPHP compila CSS, lo scrive nella cache runtime condivisa di Blockstudio nell’ambito tailwind e 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):

JSON
{
  "tailwind": {
    "config": {
      "theme": {
        "extend": {
          "colors": {
            "primary": "pink"
          }
        }
      }
    }
  }
}

Dopo (v7):

JSON
{
  "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):

JSON
{
  "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):

JSON
{
  "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:

PHP
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.