Přejít k obsahu

Migrace na v7

Tento průvodce popisuje změny, které je třeba provést při přechodu z Blockstudio 6 na verzi 7.

Importy modulů ES

Blockstudio 7 zavádí nový prefix npm: pro importy modulů ES, který odpovídá konvenci specifikátoru Denonpm.

Předtím (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";

Poté (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";

Importy CSS

Stejná změna platí i pro importy CSS:

Předtím (v6):

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

Poté (v7):

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

Zpětná kompatibilita

Prefix blockstudio/ zůstává podporován kvůli zpětné kompatibilitě. Váš stávající kód bude dál fungovat beze změn. Doporučujeme však přejít na prefix npm:, aby byl v souladu s širším ekosystémem JavaScript.

Prefix npm: má několik výhod:

  • Soulad s ekosystémem – odpovídá zavedené konvenci Deno
  • Přehlednost – hned je jasné, že importujete z npm
  • Připravenost na budoucnost – prefix blockstudio/ může být v některé budoucí hlavní verzi zastaralý

Názvy hooků

Verze 7 Blockstudio sjednocuje názvy všech hooků PHP: místo camelCase používá snake_case, v souladu se základními konvencemi WordPress.

Změněné názvy hooků

Starý název (v6) Nový název (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

Zpětná kompatibilita

Staré názvy hooků ve stylu camelCase zůstávají podporovány kvůli zpětné kompatibilitě. Váš stávající kód bude dál fungovat beze změn. Kvůli jednotnosti však doporučujeme přejít na nové názvy ve stylu snake_case.

Příklad migrace:

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

Kanonické značky bloků

Verze 7.6 Blockstudio nadále umožňuje používat prefixy projektů a přesné aliasy jako body rozšíření za běhu, ale v příkladech, výstupech katalogu, deklaracích vykreslování a diagnostice používá jako kanonický zápis <bs:namespace-slug>. Kanonické značky obsahují skutečný registrovaný název bloku a nezávisí na filtru konkrétního hostitele.

Pro projekt s brand => ["theme-components"] a 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>

Samostatný migrační příkaz zmapuje existující projekt a přepíše zkrácené zápisy na kanonický tvar. Nejprve vytvoří přehled, při nevyřešených případech se zastaví a mění pouze názvy značek. Příkaz, jeho vstupy a bezpečnostní chování najdete v dokumentaci Migrace značek bloků.

Pojmenování souborů assetů

Verze 7 Blockstudio zavádí tečkovou notaci přípon souborů assetů, která nahrazuje dosavadní zápis s pomlčkou jako doporučenou konvenci.

Změněné názvy souborů

Starý název (v6) Nový název (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

Zpětná kompatibilita

Starý zápis s pomlčkou zůstává podporován kvůli zpětné kompatibilitě. Vaše stávající soubory budou dál fungovat bez přejmenování. U nových bloků však doporučujeme přejít na tečkovou notaci.

Příklad migrace:

Kód
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

Přepínač polí

Vlastnost switch má nyní výchozí hodnotu false místo true. Ve verzi v6 mělo každé pole na levém okraji neviditelný přepínač, který byl ve výchozím stavu zapnutý. Ve verzi v7 je přepínač volitelný a používá viditelnou ikonu oka v popisku pole.

Co se změnilo

  • Výchozí hodnota je nyní false: pole už nemají přepínač, pokud výslovně nenastavíte "switch": true
  • Viditelná ikona oka: místo skryté klikací oblasti vlevo se v oblasti popisku zobrazí tlačítko s ikonou oka
  • Překryv při deaktivaci: když je pole deaktivované, zobrazí se rozmazaný překryv s textem „Toto pole je deaktivované“ místo pouhého snížení neprůhlednosti

Migrace

Pokud jste spoléhali na výchozí chování přepínače ve verzi v6, musíte ho výslovně zapnout:

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

Pokud jste dříve nastavili "switch": false, abyste přepínač deaktivovali, můžete toto nastavení odstranit, protože false je nyní výchozí.

Tailwind CSS

Verze 7 Blockstudio zcela nahrazuje přístup v6 Tailwind. Ve verzi v6 se Tailwind CSS kompilovalo na straně klienta pomocí CDN v editoru a při uložení příspěvku se ukládalo na disk. Ve verzi v7 se Tailwind CSS kompiluje na straně serveru při každém požadavku na frontend pomocí TailwindPHP s automatickým ukládáním do mezipaměti podle souborů.

Úplné podrobnosti o novém systému najdete v dokumentaci Tailwind CSS.

Kompilace na straně serveru při každém požadavku

Když je tailwind.enabled nastaveno na true, každý požadavek na frontend se kompiluje na straně serveru. Postup kompilace:

  1. WordPress vykreslí celou stránku HTML do výstupního bufferu
  2. Kandidáti tříd CSS se extrahují z HTML (rychlým regexem, bez kompilace)
  3. Kandidáti se seřadí a zahashují spolu s konfigurací CSS, čímž vznikne klíč mezipaměti
  4. Při zásahu do mezipaměti se načte soubor CSS z mezipaměti a vloží se
  5. Při minutí mezipaměti TailwindPHP zkompiluje CSS, uloží jej do sdílené runtime mezipaměti Blockstudio v rámci rozsahu tailwind a vloží jej

Zkompilované CSS se vloží jako vložená značka <style id="blockstudio-tailwind"> před </head>. Zahrnuje preflight Tailwind a všechny odpovídající utility třídy.

Skript CDN zůstává v editoru aktivní pouze pro živý náhled. Na frontend se nikdy neposílá.

Změna formátu config

Vlastnost config se změnila z objektu JSON (Tailwind v3) na řetězec CSS (syntaxe Tailwind v4 CSS jako první).

Předtím (v6):

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

Poté (v7):

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

Odebrané nastavení customClasses

Nastavení pole customClasses bylo odebráno. V přístupu Tailwind v4, který upřednostňuje CSS, se vlastní utility třídy definují přímo v řetězci config pomocí @layer utilities.

Předtím (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" }
    ]
  }
}

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

Nebo pomocí filtru pro víceřádkové konfigurace:

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

Byl odebrán také filtr blockstudio/settings/tailwind/custom_classes. Chcete-li přidat vlastní pravidla CSS, použijte místo něj filtr blockstudio/tailwind/css.

Odebraný endpoint REST

Endpoint POST /blockstudio/v1/editor/tailwind/save byl odebrán. Zkompilované CSS se už neukládá z editoru. Pokud jste měli vlastní kód, který tento endpoint volal, můžete ho bezpečně odstranit.

Ukládání do mezipaměti

Blockstudio používá strategii ukládání do mezipaměti založenou na kandidátech. Namísto hashování celého HTML stránky (což by při každém požadavku zneplatnilo mezipaměť kvůli jednorázovým tokenům a časovým razítkům) se hashují pouze kandidáti tříd CSS. To znamená:

  • Stránky se stejnými třídami CSS sdílejí stejný soubor v mezipaměti
  • Dynamický obsah (jednorázové tokeny, panely administrace, časová razítka) nezpůsobí neplatnost mezipaměti
  • Mezipaměť se zneplatní pouze při změně množiny tříd CSS nebo konfigurace

Soubory mezipaměti se ukládají do nakonfigurovaného kořenového adresáře runtime Blockstudio v sites/{network-blog}/{runtime-identity}/tailwind/. Opětovnou kompilaci vynutíte zavoláním Blockstudio\Runtime_Cache::purge('tailwind').

Změny filtrů

Starý název (v6) Nový název (v7)
blockstudio/tailwind/on_demand/css blockstudio/tailwind/css
blockstudio/tailwind/assets/dir Odebráno
blockstudio/settings/tailwind/custom_classes Odebráno

Odebrané soubory a načítání

Ve verzi v6 se Tailwind CSS načítalo jako externí šablony stylů (blockstudio-tailwind, blockstudio-tailwind-preflight). Ve verzi v7 se všechen CSS vkládá přímo pomocí výstupního bufferu. Na frontendu se pro Tailwind nevkládají žádné značky link ani šablony stylů.

Knihovna bloků

Vestavěná knihovna „Blockstudio Elements“ byla odebrána. Nastavení library ve verzi blockstudio.json ani filtr blockstudio/settings/library již nemají žádný účinek.

Pokud jste používali bloky z knihovny (Galerie, Posuvník, Porovnání obrázků, Kód, Ikona), zkopírujte složky bloků z adresáře includes/library/blockstudio-element/ instalace v6 do adresáře blockstudio své šablony a aktualizujte jejich soubory block.json novými názvy a kategoriemi.