Migrer vers v7
Ce guide présente les modifications à apporter pour passer de Blockstudio 6 à la version 7.
Imports de modules ES
Nouveau préfixe npm: (recommandé)
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) :
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) :
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) :
import "blockstudio/swiper@11.0.0/swiper.min.css";
Après (v7) :
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 :
// 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"] :
<!-- 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 :
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 :
{
"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 :
- WordPress génère la page complète HTML dans un tampon de sortie
- Les candidats de classe CSS sont extraits de HTML (expression régulière rapide, sans compilation)
- Les candidats sont triés et hachés avec la configuration CSS pour créer une clé de cache
- En cas de succès du cache : le fichier CSS mis en cache est lu et injecté
- 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) :
{
"tailwind": {
"config": {
"theme": {
"extend": {
"colors": {
"primary": "pink"
}
}
}
}
}
}
Après (v7) :
{
"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) :
{
"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) :
{
"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 :
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.