Aller au contenu

Migrer vers v7

Ce guide présente les modifications à apporter pour passer de Blockstudio 6 à la version 7.

Imports de modules ES

Blockstudio 7 introduit un nouveau préfixe npm: pour les imports de modules ES, conformément à la convention de spécificateur npm de Deno.

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

Après (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";

Imports CSS

La même modification s’applique aux imports CSS :

Avant (v6) :

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

Après (v7) :

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

Compatibilité ascendante

Le préfixe blockstudio/ reste pris en charge pour assurer la compatibilité ascendante. Votre code existant continuera de fonctionner sans modification. Nous vous recommandons toutefois de passer au préfixe npm: pour rester cohérent avec l’écosystème JavaScript au sens large.

Le préfixe npm: présente plusieurs avantages :

  • Cohérence avec l’écosystème : respecte la convention établie de Deno
  • Clarté : indique immédiatement que vous importez depuis npm
  • Pérennité : le préfixe blockstudio/ pourrait être abandonné dans une future version majeure

Noms des hooks

Blockstudio 7 uniformise les noms de tous les hooks PHP : ils utilisent désormais snake_case au lieu de camelCase, conformément aux conventions du cœur de WordPress.

Noms de hooks modifiés

Ancien nom (v6) Nouveau nom (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é ascendante

Les anciens noms de hooks en camelCase restent pris en charge pour assurer la compatibilité ascendante. Votre code existant continuera de fonctionner sans modification. Nous vous recommandons toutefois de passer aux nouveaux noms en snake_case pour rester cohérent.

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

Balises canoniques des blocs

Blockstudio 7.6 conserve les préfixes de projet et les alias exacts comme points d’extension à l’exécution, mais utilise <bs:namespace-slug> comme forme canonique dans les exemples, la sortie du catalogue, les déclarations de rendu et les diagnostics. Les balises canoniques portent le véritable nom de bloc enregistré et ne dépendent pas d’un filtre propre à l’hôte.

Pour un projet avec brand => ["theme-components"] et 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>

Une commande de migration autonome inventorie un projet existant et remplace les abréviations par la forme canonique. Elle commence par produire un rapport, s’interrompt en cas de situations non résolues et ne modifie que les noms de balises. Consultez Migration des balises de bloc pour connaître la commande, ses entrées et son fonctionnement sécuritaire.

Nommage des fichiers de ressources

Blockstudio 7 introduit la notation avec un point pour les suffixes des fichiers de ressources, qui remplace l’ancienne notation avec un tiret comme convention recommandée.

Noms de fichiers modifiés

Ancien nom (v6) Nouveau nom (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é ascendante

L’ancienne notation avec un tiret reste prise en charge pour assurer la compatibilité ascendante. Vos fichiers existants continueront de fonctionner sans renommage. Nous vous recommandons toutefois d’adopter la notation avec un point pour les nouveaux blocs.

Exemple de 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

Bascule des champs

La propriété switch vaut désormais false par défaut au lieu de true. Dans v6, chaque champ avait un bouton bascule invisible sur le bord gauche, activé par défaut. Dans v7, la bascule est facultative et représentée par une icône d’œil visible dans le libellé du champ.

Modifications apportées

  • Désactivée par défaut (false) : les champs n’ont plus de bascule, sauf si vous définissez explicitement "switch": true
  • Icône d’œil visible : au lieu d’une zone de clic masquée sur le côté gauche, un bouton avec une icône d’œil apparaît dans la zone du libellé
  • Superposition de désactivation : lorsqu’un champ est désactivé, un voile flou affiche le texte « Ce champ est désactivé » au lieu de simplement réduire son opacité

Migration

Si vous vous reposiez sur le comportement par défaut de la bascule dans v6, vous devez l’activer explicitement :

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

Si vous aviez défini "switch": false pour désactiver la bascule, vous pouvez le supprimer puisque false est désormais la valeur par défaut.

Tailwind CSS

Blockstudio 7 remplace entièrement l’approche v6 Tailwind. Dans v6, Tailwind CSS était compilé côté client via CDN dans l’éditeur, puis enregistré sur le disque à la sauvegarde de l’article. Dans v7, Tailwind CSS est compilé côté serveur à chaque requête frontend via TailwindPHP, avec une mise en cache automatique basée sur les fichiers.

Consultez la documentation de Tailwind CSS pour tous les détails sur le nouveau système.

Compilation côté serveur toujours active

Lorsque tailwind.enabled est true, chaque requête frontend est compilée côté serveur. Voici le déroulement de la compilation :

  1. WordPress génère la page complète HTML dans un tampon de sortie
  2. Les candidats de classe CSS sont extraits de HTML (expression régulière rapide, sans compilation)
  3. Les candidats sont triés et hachés avec la configuration CSS pour créer une clé de cache
  4. En cas de succès du cache : le fichier CSS mis en cache est lu et injecté
  5. En cas d’échec du cache : TailwindPHP compile CSS, l’écrit dans le cache d’exécution partagé de Blockstudio, dans l’espace de noms tailwind, puis l’injecte

Le CSS compilé est injecté dans une balise <style id="blockstudio-tailwind"> en ligne avant </head>. Cela inclut le préflight de Tailwind et toutes les classes utilitaires correspondantes.

Le script CDN reste actif dans l’éditeur uniquement pour l’aperçu en direct. Il n’est jamais servi sur le frontend.

Nouveau format de config

La propriété config est passée d’un objet JSON (Tailwind v3) à une chaîne CSS (syntaxe Tailwind v4 CSS d’abord).

Avant (v6) :

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

Après (v7) :

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

Paramètre customClasses supprimé

Le paramètre tableau customClasses a été supprimé. Avec l’approche de Tailwind v4 qui privilégie CSS, les classes utilitaires personnalisées sont définies directement dans la chaîne config à l’aide de @layer utilities.

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

Après (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; } }"
  }
}

Ou via le filtre pour les configurations multilignes :

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

Le filtre blockstudio/settings/tailwind/custom_classes a également été supprimé. Utilisez plutôt le filtre blockstudio/tailwind/css pour ajouter des règles CSS personnalisées.

Point de terminaison REST supprimé

Le point de terminaison POST /blockstudio/v1/editor/tailwind/save a été supprimé. Le CSS compilé n’est plus enregistré depuis l’éditeur. Si votre code personnalisé appelle ce point de terminaison, vous pouvez le supprimer sans risque.

Mise en cache

Blockstudio utilise une stratégie de mise en cache basée sur les candidats. Au lieu de hacher l’ensemble du HTML de la page (ce qui invaliderait le cache à chaque requête à cause des nonces et des horodatages), seuls les candidats de classe CSS sont hachés. Ainsi :

  • Deux pages ayant les mêmes classes CSS partagent le même fichier en cache
  • Le contenu dynamique (nonces, barres d’administration, horodatages) n’invalide pas le cache
  • Le cache est invalidé uniquement si l’ensemble des classes CSS ou la configuration change

Les fichiers de cache utilisent la racine d’exécution Blockstudio configurée sous sites/{network-blog}/{runtime-identity}/tailwind/. Appelez Blockstudio\Runtime_Cache::purge('tailwind') pour forcer une recompilation.

Modifications des filtres

Ancien nom (v6) Nouveau nom (v7)
blockstudio/tailwind/on_demand/css blockstudio/tailwind/css
blockstudio/tailwind/assets/dir Supprimé
blockstudio/settings/tailwind/custom_classes Supprimé

Fichiers supprimés et chargements

Dans v6, Tailwind CSS était chargé sous forme de feuilles de style externes (blockstudio-tailwind, blockstudio-tailwind-preflight). Dans v7, tout le CSS est injecté en ligne via un tampon de sortie. Aucune balise de lien ni feuille de style n’est chargée pour Tailwind sur le frontend.

Bibliothèque de blocs

La bibliothèque intégrée « éléments Blockstudio » a été supprimée. Le paramètre library dans blockstudio.json et le filtre blockstudio/settings/library n’ont plus aucun effet.

Si vous utilisiez les blocs de la bibliothèque (Galerie, Curseur, Comparaison d’images, Code, Icône), copiez les dossiers des blocs depuis le répertoire includes/library/blockstudio-element/ de votre installation v6 vers le répertoire blockstudio de votre thème, puis mettez à jour leurs fichiers block.json avec les nouveaux noms et catégories.