Zum Inhalt springen

Migration auf v7

Dieser Leitfaden beschreibt die Änderungen, die du beim Upgrade von Blockstudio 6 auf 7 vornehmen musst.

ES-Modulimporte

Blockstudio 7 führt für ES-Modulimporte das neue Präfix npm: ein und folgt damit Denos etablierter Konvention für npm-Spezifizierer.

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

Nachher (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-Importe

Dieselbe Änderung gilt für CSS-Importe:

Vorher (v6):

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

Nachher (v7):

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

Abwärtskompatibilität

Das Präfix blockstudio/ wird aus Gründen der Abwärtskompatibilität weiterhin unterstützt. Dein vorhandener Code funktioniert unverändert weiter. Wir empfehlen jedoch die Migration auf das Präfix npm:, damit es dem übrigen JavaScript-Ökosystem entspricht.

Das Präfix npm: bietet mehrere Vorteile:

  • Anpassung ans Ökosystem – Entspricht Denos etablierter Konvention
  • Übersichtlichkeit – Du erkennst sofort, dass du aus npm importierst
  • Zukunftssicherheit – Das Präfix blockstudio/ könnte in einer künftigen Hauptversion wegfallen

Hook-Namen

Blockstudio 7 vereinheitlicht alle PHP-Hook-Namen auf snake_case statt camelCase und folgt damit den Konventionen des WordPress-Kerns.

Geänderte Hook-Namen

Alter Name (v6) Neuer Name (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

Abwärtskompatibilität

Die alten camelCase-Hook-Namen werden aus Gründen der Abwärtskompatibilität weiterhin unterstützt. Dein vorhandener Code funktioniert unverändert weiter. Wir empfehlen jedoch, aus Gründen der Einheitlichkeit auf die neuen snake_case-Namen umzusteigen.

Beispiel für eine Migration:

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

Kanonische Block-Tags

Blockstudio 7.6 behält Projektpräfixe und exakte Aliase als Erweiterungspunkte zur Laufzeit bei, verwendet in Beispielen, Katalogausgaben, Render-Deklarationen und Diagnosemeldungen jedoch <bs:namespace-slug> als kanonische Schreibweise. Kanonische Tags tragen den tatsächlich registrierten Blocknamen und sind nicht von einem host-spezifischen Filter abhängig.

Für ein Projekt mit brand => ["theme-components"] und 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>

Ein eigenständiger Migrationsbefehl erfasst ein bestehendes Projekt und schreibt Kurzformen in die kanonische Schreibweise um. Er erstellt zuerst einen Bericht, bricht bei ungelösten Fällen ab und ändert ausschließlich Tagnamen. Unter Block-Tag-Migration findest du den Befehl, seine Eingaben und sein Sicherheitsverhalten.

Benennung von Asset-Dateien

Blockstudio 7 führt die Punktnotation für Asset-Dateiendungen ein und ersetzt die bisherige Bindestrichnotation als empfohlene Konvention.

Geänderte Dateinamen

Alter Name (v6) Neuer Name (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

Abwärtskompatibilität

Die alte Bindestrichnotation wird aus Gründen der Abwärtskompatibilität weiterhin unterstützt. Deine vorhandenen Dateien funktionieren ohne Umbenennung weiter. Für neue Blöcke empfehlen wir jedoch die Punktnotation.

Beispiel für eine Migration:

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

Feldschalter

Die Eigenschaft switch ist jetzt standardmäßig auf false statt auf true gesetzt. In v6 hatte jedes Feld standardmäßig einen unsichtbaren Schalter an der linken Kante. In v7 ist der Schalter optional und wird durch ein sichtbares Augensymbol in der Feldbeschriftung dargestellt.

Was sich geändert hat

  • Standard ist jetzt false: Felder haben nur noch dann einen Schalter, wenn du "switch": true ausdrücklich festlegst
  • Sichtbares Augensymbol: Statt eines verborgenen Klickbereichs links erscheint eine Schaltfläche mit Augensymbol im Beschriftungsbereich
  • Deaktivierungsüberlagerung: Ist ein Feld deaktiviert, wird eine unscharfe Überlagerung mit dem Text „Dieses Feld ist deaktiviert“ angezeigt, statt nur die Deckkraft zu verringern

Migration

Wenn du dich in v6 auf das standardmäßige Schalterverhalten verlassen hast, musst du ihn ausdrücklich aktivieren:

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

Wenn du "switch": false zuvor auf „deaktiviert“ gesetzt hast, kannst du es entfernen, da false jetzt der Standard ist.

Tailwind CSS

Blockstudio 7 ersetzt den Tailwind-Ansatz aus v6 vollständig. In v6 wurde Tailwind CSS clientseitig über CDN im Editor kompiliert und beim Speichern des Beitrags auf der Festplatte abgelegt. In v7 wird Tailwind CSS bei jeder Frontend-Anfrage serverseitig über TailwindPHP kompiliert und automatisch dateibasiert zwischengespeichert.

Ausführliche Informationen zum neuen System findest du in der Tailwind CSSDokumentation.

Immer aktive serverseitige Kompilierung

Wenn tailwind.enabled auf true gesetzt ist, wird jede Frontend-Anfrage serverseitig kompiliert. Der Ablauf:

  1. WordPress rendert die vollständige Seite HTML in einen Ausgabepuffer
  2. Kandidaten für CSS-Klassen werden aus HTML extrahiert (schneller regulärer Ausdruck, keine Kompilierung)
  3. Die Kandidaten werden sortiert und mit der Konfiguration CSS gehasht, um einen Cache-Schlüssel zu erstellen
  4. Bei einem Cache-Treffer wird die zwischengespeicherte Datei CSS gelesen und eingefügt
  5. Bei einem Cache-Fehlschlag kompiliert TailwindPHP CSS, schreibt es in den gemeinsamen Laufzeit-Cache von Blockstudio im Bereich tailwind und fügt es ein

Das kompilierte CSS wird als Inline-Tag <style id="blockstudio-tailwind"> vor </head> eingefügt. Dazu gehören Tailwinds Preflight und alle passenden Utility-Klassen.

Das Skript CDN bleibt im Editor ausschließlich für die Live-Vorschau aktiv. Im Frontend wird es nie ausgeliefert.

Das Format von config hat sich geändert

Die Eigenschaft config wurde von einem JSON-Objekt (Tailwind v3) zu einer CSS-Zeichenfolge (CSS-first-Syntax von Tailwind v4) geändert.

Vorher (v6):

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

Nachher (v7):

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

Einstellung customClasses entfernt

Die Array-Einstellung customClasses wurde entfernt. Durch den CSS-first-Ansatz von Tailwind v4 werden benutzerdefinierte Utility-Klassen direkt in der Zeichenfolge config mit @layer utilities definiert.

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

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

Oder über den Filter für mehrzeilige Konfigurationen:

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

Auch der Filter blockstudio/settings/tailwind/custom_classes wurde entfernt. Verwende stattdessen den Filter blockstudio/tailwind/css, um benutzerdefinierte CSS-Regeln hinzuzufügen.

Endpunkt REST entfernt

Der Endpunkt POST /blockstudio/v1/editor/tailwind/save wurde entfernt. Kompiliertes CSS wird nicht mehr aus dem Editor gespeichert. Wenn dein benutzerdefinierter Code diesen Endpunkt aufgerufen hat, kannst du ihn gefahrlos entfernen.

Zwischenspeicherung

Blockstudio verwendet eine kandidatenbasierte Zwischenspeicherung. Statt die gesamte Seite HTML zu hashen (wodurch der Cache wegen Nonces und Zeitstempeln bei jeder Anfrage ungültig würde), werden nur die Klassenkandidaten CSS gehasht. Das bedeutet:

  • Zwei Seiten mit denselben Klassen CSS verwenden dieselbe zwischengespeicherte Datei
  • Dynamische Inhalte (Nonces, Admin-Leisten, Zeitstempel) machen den Cache nicht ungültig
  • Der Cache wird nur ungültig, wenn sich die Menge der Klassen CSS oder die Konfiguration ändert

Cache-Dateien verwenden das konfigurierte Laufzeit-Stammverzeichnis Blockstudio unter sites/{network-blog}/{runtime-identity}/tailwind/. Rufe Blockstudio\Runtime_Cache::purge('tailwind') auf, um die Kompilierung zu erzwingen.

Änderungen an Filtern

Alter Name (v6) Neuer Name (v7)
blockstudio/tailwind/on_demand/css blockstudio/tailwind/css
blockstudio/tailwind/assets/dir Entfernt
blockstudio/settings/tailwind/custom_classes Entfernt

Entfernte Dateien und Einbindungen

In v6 wurde Tailwind CSS als externe Stylesheets (blockstudio-tailwind, blockstudio-tailwind-preflight) eingebunden. In v7 wird sämtliches CSS inline über einen Ausgabepuffer eingefügt. Im Frontend gibt es keine Link-Tags oder eingebundenen Stylesheets für Tailwind.

Block-Bibliothek

Die integrierte Bibliothek „Blockstudio Elements“ wurde entfernt. Die Einstellung library in blockstudio.json und der Filter blockstudio/settings/library haben keine Wirkung mehr.

Wenn du die Bibliotheksblöcke (Gallery, Slider, Image Comparison, Code, Icon) verwendet hast, kopiere die Blockordner aus dem Verzeichnis includes/library/blockstudio-element/ deiner v6-Installation in das Blockstudio-Verzeichnis deines Themes und aktualisiere ihre Dateien block.json mit neuen Namen und Kategorien.