Ga naar de inhoud

Migreren naar v7

Deze handleiding beschrijft welke wijzigingen u moet aanbrengen bij het upgraden van Blockstudio 6 naar 7.

ES-module-imports

Blockstudio 7 introduceert het nieuwe voorvoegsel npm: voor ES-module-imports, volgens de conventie van Denonpm-specifier.

Voor (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";

Na (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";

CSS-imports

Dezelfde wijziging geldt voor CSS-imports:

Voor (v6):

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

Na (v7):

JavaScript
import "npm:swiper@11.0.0/swiper.min.css";

Achterwaartse compatibiliteit

Het voorvoegsel blockstudio/ wordt nog ondersteund voor achterwaartse compatibiliteit. Uw bestaande code blijft zonder wijzigingen werken. Toch raden we aan om over te stappen op het voorvoegsel npm:, zodat uw code aansluit op het bredere JavaScript-ecosysteem.

Het voorvoegsel npm: biedt verschillende voordelen:

  • Aansluiting op het ecosysteem – Volgt de gevestigde conventie van Deno
  • Duidelijkheid – Maakt meteen duidelijk dat u importeert uit npm
  • Voorbereid op de toekomst – Het voorvoegsel blockstudio/ kan in een toekomstige hoofdversie verouderd raken

Hooknamen

Blockstudio 7 standaardiseert alle PHP-hooknamen door snake_case te gebruiken in plaats van camelCase, in lijn met de conventies van WordPress core.

Gewijzigde hooknamen

Oude naam (v6) Nieuwe naam (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

Achterwaartse compatibiliteit

De oude camelCase-hooknamen worden nog ondersteund voor achterwaartse compatibiliteit. Uw bestaande code blijft zonder wijzigingen werken. Toch raden we aan om voor de consistentie over te stappen op de nieuwe snake_case-namen.

Migratievoorbeeld:

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'];
});

Canonieke blocktags

Blockstudio 7.6 blijft projectvoorvoegsels en exacte aliassen als uitbreidingspunten tijdens runtime ondersteunen, maar gebruikt <bs:namespace-slug> als canonieke schrijfwijze in voorbeelden, catalogusuitvoer, renderdeclaraties en diagnostische meldingen. Canonieke tags bevatten de echte geregistreerde blocknaam en zijn niet afhankelijk van een hostspecifiek filter.

Voor een project met brand => ["theme-components"] en 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>

Een zelfstandige migratieopdracht inventariseert een bestaand project en herschrijft verkorte schrijfwijzen naar de canonieke vorm. De opdracht stelt eerst een rapport op, stopt bij onopgeloste gevallen en wijzigt alleen tagnamen. Zie Migratie van blocktags voor de opdracht, de invoer en de veiligheidsmaatregelen.

Namen van assetbestanden

Blockstudio 7 introduceert puntnotatie voor achtervoegsels van assetbestanden, als aanbevolen conventie ter vervanging van de oude streepjesnotatie.

Gewijzigde bestandsnamen

Oude naam (v6) Nieuwe naam (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

Achterwaartse compatibiliteit

De oude streepjesnotatie wordt nog ondersteund voor achterwaartse compatibiliteit. Uw bestaande bestanden blijven werken zonder ze te hernoemen. Toch raden we aan om voor nieuwe blocks de puntnotatie te gebruiken.

Migratievoorbeeld:

Code
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

Veldschakelaar

De eigenschap switch is nu standaard ingesteld op false in plaats van true. In v6 had elk veld links een onzichtbare schakelaar die standaard was ingeschakeld. In v7 is de schakelaar optioneel en wordt een zichtbaar oogpictogram in het veldlabel gebruikt.

Wat is er veranderd?

  • Standaard uitgeschakeld: false: velden hebben niet langer een schakelaar, tenzij u "switch": true expliciet instelt
  • Zichtbaar oogpictogram: in plaats van een verborgen klikzone aan de linkerkant verschijnt er een knop met een oogpictogram in het labelgebied
  • Overlay voor uitgeschakelde velden: wanneer een veld is uitgeschakeld, wordt er een vervaagde overlay met de tekst "Dit veld is uitgeschakeld" weergegeven in plaats van alleen de dekking te verlagen

Migratie

Als u vertrouwde op het standaardgedrag van de schakelaar in v6, moet u deze expliciet inschakelen:

JSON
{
  "id": "title",
  "type": "text",
  "label": "Title",
  "switch": true
}

Als u eerder "switch": false hebt ingesteld om de schakelaar uit te schakelen, kunt u deze instelling verwijderen omdat false nu de standaard is.

Tailwind CSS

Blockstudio 7 vervangt de aanpak met v6 Tailwind volledig. In v6 werd Tailwind CSS aan de clientzijde gecompileerd via de CDN in de editor en na het opslaan van het bericht op schijf opgeslagen. In v7 wordt Tailwind CSS bij elk frontendverzoek aan de serverzijde gecompileerd via TailwindPHP, met automatische caching op basis van bestanden.

Zie de documentatie over Tailwind CSS voor alle details over het nieuwe systeem.

Altijd compileren aan de serverzijde

Wanneer tailwind.enabled is ingesteld op true, wordt elk frontendverzoek aan de serverzijde gecompileerd. Het compilatieproces:

  1. WordPress rendert de volledige pagina HTML in een uitvoerbuffer
  2. Kandidaten voor CSS-klassen worden uit de HTML gehaald (snelle regex, geen compilatie)
  3. Kandidaten worden gesorteerd en gehasht met de configuratie CSS om een cachesleutel te maken
  4. Bij een cachetreffer: het gecachete bestand CSS wordt gelezen en ingevoegd
  5. Bij een cachemisser: TailwindPHP compileert de CSS, schrijft deze naar de gedeelde runtimecache van Blockstudio binnen de scope tailwind en voegt deze in

De gecompileerde CSS wordt ingevoegd als inline-tag <style id="blockstudio-tailwind"> vóór </head>. Dit omvat de preflight van Tailwind en alle overeenkomende utilityklassen.

Het script CDN blijft alleen actief in de editor voor livevoorbeelden. Het wordt nooit op de frontend aangeboden.

Gewijzigd formaat van config

De eigenschap config is gewijzigd van een object van het type JSON (Tailwind v3) naar een tekenreeks van het type CSS (syntaxis met Tailwind v4 CSS eerst).

Voor (v6):

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

Na (v7):

JSON
{
  "tailwind": {
    "config": "@theme { --color-primary: pink; }"
  }
}

Instelling customClasses verwijderd

De array-instelling customClasses is verwijderd. Met de CSS-first-aanpak van Tailwind v4 definieer je eigen utilityklassen rechtstreeks in de tekenreeks config met @layer utilities.

Voor (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" }
    ]
  }
}

Na (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; } }"
  }
}

Of via het filter voor configuraties met meerdere regels:

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;
});

Het filter blockstudio/settings/tailwind/custom_classes is ook verwijderd. Gebruik in plaats daarvan het filter blockstudio/tailwind/css om aangepaste CSS-regels toe te voegen.

Endpoint REST verwijderd

Het endpoint POST /blockstudio/v1/editor/tailwind/save is verwijderd. Gecompileerde CSS wordt niet langer vanuit de editor opgeslagen. Als u aangepaste code had die dit endpoint aanroept, kunt u die veilig verwijderen.

Caching

Blockstudio gebruikt een cachingstrategie op basis van kandidaten. In plaats van de volledige pagina HTML te hashen (waardoor de cache bij elk verzoek ongeldig zou worden door nonces en tijdstempels), worden alleen de CSS-klaskandidaten gehasht. Dit betekent:

  • Twee pagina’s met dezelfde CSS-klassen delen hetzelfde gecachete bestand
  • Dynamische inhoud (nonces, beheerbalken, tijdstempels) maakt de cache niet ongeldig
  • De cache wordt alleen ongeldig wanneer de set CSS-klassen of de configuratie verandert

Cachebestanden gebruiken de geconfigureerde runtime-root Blockstudio onder sites/{network-blog}/{runtime-identity}/tailwind/. Roep Blockstudio\Runtime_Cache::purge('tailwind') aan om opnieuw compileren af te dwingen.

Filterwijzigingen

Oude naam (v6) Nieuwe naam (v7)
blockstudio/tailwind/on_demand/css blockstudio/tailwind/css
blockstudio/tailwind/assets/dir Verwijderd
blockstudio/settings/tailwind/custom_classes Verwijderd

Verwijderde bestanden en enqueues

In v6 werd Tailwind CSS geladen als externe stylesheets (blockstudio-tailwind, blockstudio-tailwind-preflight). In v7 wordt alle CSS inline ingevoegd via een uitvoerbuffer. Er zijn geen linktags of geladen stylesheets voor Tailwind op de frontend.

Blockbibliotheek

De ingebouwde bibliotheek “Blockstudio Elements” is verwijderd. De instelling library in blockstudio.json en het filter blockstudio/settings/library hebben geen effect meer.

Als u bibliotheekblocks gebruikte (Gallery, Slider, Image Comparison, Code, Icon), kopieert u de blockmappen uit de installatiemap includes/library/blockstudio-element/ van uw installatie van v6 naar de map blockstudio van uw thema en werkt u hun bestanden block.json bij met nieuwe namen en categorieën.