Créer une bibliothèque de blocs
Une bibliothèque de blocs est un ensemble de blocs de section autonomes qui s’assemblent pour former des pages complètes. Chaque bloc possède son propre schéma, modèle et style. Blockstudio fournit le cadre : traitement Tailwind CSS, enregistrement des attributs et synchronisation des pages. À vous de fournir les blocs.
Ce guide explique comment créer une bibliothèque à partir de zéro, en suivant la même architecture que celle utilisée dans des centaines de thèmes en production. À la fin, vous aurez un thème fonctionnel avec une section héro, une grille de fonctionnalités et une page d’accueil composée.
Structure des dossiers
Tous les thèmes Blockstudio suivent la même structure :
my-theme/
├── style.css # WordPress header + Tailwind v4 config
├── blockstudio.json # Blockstudio settings
├── functions.php # Section helper + Tailwind filter
├── index.php # Main WordPress template
├── blockstudio/
│ ├── fields/
│ │ └── section/
│ │ └── field.json # Shared section controls
│ └── sections/
│ ├── hero/
│ │ ├── block.json
│ │ └── index.php
│ └── features/
│ ├── block.json
│ └── index.php
└── pages/
└── home/
├── page.json
└── index.php
Les blocs se trouvent dans blockstudio/sections/. Chaque bloc est un dossier contenant un schéma block.json et un modèle index.php. Les pages se trouvent dans pages/ et assemblent les blocs avec la syntaxe <block>.
Fichiers de base
blockstudio.json
Ce fichier configure le traitement de votre thème par Blockstudio. La configuration est identique pour tous les thèmes :
{
"assets": {
"enqueue": true,
"reset": {
"enabled": true,
"fullWidth": ["page"]
},
"minify": { "css": true, "js": true },
"process": { "scss": false, "scssFiles": true }
},
"tailwind": {
"enabled": true,
"config": ""
},
"dev": {
"canvas": { "enabled": true }
},
"$schema": "https://blockstudio.dev/schema/blockstudio"
}
reset supprime les styles par défaut des blocs WordPress. fullWidth permet aux types de publication page de s’étendre sur toute la largeur. canvas active le mode canevas de l’éditeur pour simplifier l’expérience de modification.
Le champ tailwind.config est volontairement vide. Avec Tailwind v4, toute la configuration se trouve dans style.css selon une approche privilégiant CSS.
index.php
Le modèle principal WordPress. Il s’agit de WordPress standard, sans spécificité Blockstudio :
<!DOCTYPE html>
<html <?php language_attributes(); ?>>
<head>
<meta charset="<?php bloginfo( 'charset' ); ?>">
<meta name="viewport" content="width=device-width, initial-scale=1">
<?php wp_head(); ?>
</head>
<body <?php body_class(); ?>>
<?php wp_body_open(); ?>
<main>
<?php
if ( have_posts() ) {
while ( have_posts() ) {
the_post();
the_content();
}
}
?>
</main>
<?php wp_footer(); ?>
</body>
</html>
Ajoutez un header.php et un footer.php si vous avez besoin d’une navigation. Pour l’instant, un modèle minimal suffit pour afficher les blocs.
Jetons de design
La personnalisation du thème se fait dans style.css avec la directive @theme de Tailwind v4. C’est le cœur de votre système de design.
/*
Theme Name: My Theme
Theme URI: https://example.com
Description: A clean theme built with Blockstudio.
Version: 1.0.0
Requires at least: 6.0
Requires PHP: 8.2
Author: Your Name
Text Domain: my-theme
*/
@theme {
--font-sans: 'Inter', ui-sans-serif, system-ui, sans-serif;
--color-bg: #050505;
--color-elevated: #111111;
--color-subtle: rgb(255 255 255 / 0.06);
--color-muted: #888888;
--color-accent: #6366f1;
--color-accent-hover: #4f46e5;
}
Chaque thème a besoin au minimum de :
| Jeton | Rôle |
|---|---|
--font-sans ou --font-serif |
Police principale |
--color-bg |
Arrière-plan de page |
--color-elevated |
Arrière-plan des cartes/surfaces |
--color-subtle |
Bordures, séparateurs |
--color-muted |
Texte secondaire |
--color-accent |
Couleur principale de la marque |
Ces jetons génèrent automatiquement des classes utilitaires Tailwind. --color-accent devient bg-accent, text-accent, border-accent, et ainsi de suite.
Pour un thème clair, inversez les valeurs :
@theme {
--font-serif: 'Zilla Slab', serif;
--font-sans: 'DM Sans', sans-serif;
--color-bg: #f5f0e8;
--color-elevated: #ece6da;
--color-heading: #2c1810;
--color-body: #6b5c4f;
--color-muted: #9a8b7d;
--color-accent: #2d5016;
--color-subtle: #d9d1c4;
}
Styles de base et utilitaires
Sous le bloc @theme, ajoutez les styles du corps, les valeurs par défaut de la couche de base et les utilitaires personnalisés.
Les styles du corps doivent se trouver hors de @layer pour que l’éditeur WordPress les prenne en compte :
body {
@apply bg-bg font-sans text-white antialiased;
}
Couche de base pour les valeurs par défaut des éléments :
@layer base {
section {
@apply relative overflow-hidden;
}
h1, h2, h3 {
text-wrap: balance;
}
p {
text-wrap: pretty;
}
}
Utilitaires personnalisés pour les modèles réutilisables. Chaque thème définit un utilitaire container pour garantir un espacement cohérent des sections, ainsi que, généralement, des utilitaires card, badge et de bouton :
@utility container-px {
@apply mx-auto max-w-5xl px-6;
}
@utility container {
@apply container-px py-24 sm:py-32;
}
@utility container-no-pb {
@apply pb-0 sm:pb-0;
}
@utility card {
@apply rounded-2xl border border-subtle bg-elevated/80 p-8 transition-all duration-300;
&:hover {
border-color: rgb(255 255 255 / 0.1);
}
}
@utility badge {
@apply inline-flex items-center gap-2 rounded-full border border-subtle bg-white/5 px-3.5 py-1.5 text-sm text-muted;
}
@utility btn-primary {
@apply inline-flex items-center gap-2 rounded-full bg-accent px-6 py-3 text-sm font-medium text-white transition-colors;
&:hover {
@apply bg-accent-hover;
}
}
@utility btn-secondary {
@apply inline-flex items-center gap-2 rounded-full border border-subtle px-6 py-3 text-sm font-medium text-white transition-all;
&:hover {
border-color: rgb(255 255 255 / 0.15);
background: rgb(255 255 255 / 0.04);
}
}
Les pseudo-sélecteurs doivent se trouver dans le bloc @utility, avec l’imbrication CSS (&:hover). Ne les mettez jamais dans le nom de l’utilitaire. @utility btn-primary:hover {} n’est pas valide et sera rejeté par Tailwind.
@source en ligne
Blockstudio analyse automatiquement les modèles de vos blocs pour détecter les classes Tailwind. En revanche, les classes utilisées hors des modèles de blocs (dans functions.php, header.php, index.php) ne sont pas détectées. Déclarez-les avec @source inline :
@source inline("bg-bg bg-accent-tint container container-px container-no-pb");
Cela indique à Tailwind d’inclure ces classes dans le résultat, même si elles ne figurent que dans des fichiers PHP qui ne sont pas analysés.
Modèle de section
Le modèle de section est la convention la plus importante d’une bibliothèque de blocs Blockstudio. Il fournit à chaque bloc un espacement cohérent, l’alternance des arrière-plans et le contrôle du remplissage grâce à deux mécanismes partagés : un champ personnalisé et un utilitaire PHP.
Champ de section
Créez une définition de champ partagée à laquelle chaque bloc peut faire référence :
{
"$schema": "https://blockstudio.dev/schema/field",
"name": "section",
"title": "Section",
"attributes": [
{
"type": "group",
"attributes": [
{
"id": "removeBottomPadding",
"type": "toggle",
"label": "Remove bottom padding"
},
{
"id": "accentBg",
"type": "toggle",
"label": "Accent background"
}
]
}
]
}
Ce champ apparaît dans l’inspecteur de chaque bloc, sous un onglet « Section ». Les clients disposent de deux commandes : activer ou désactiver un arrière-plan d’accentuation, et supprimer le remplissage inférieur (pratique pour empiler des sections sans espace).
Utilitaire de section
Dans functions.php, créez un utilitaire qui convertit ces attributs en classes CSS :
<?php
/**
* My Theme functions.
*
* @package My_Theme
*/
/**
* Returns section and container class strings based on block attributes.
*
* @param array $a Block attributes.
* @param string $extra_section Additional classes for the section element.
* @param string $extra_container Additional classes for the container element.
* @return array Array of [ section_classes, container_classes ].
*/
function mytheme_section_classes( array $a, string $extra_section = '', string $extra_container = '' ): array {
$section = ! empty( $a['accentBg'] ) ? 'bg-accent-tint' : 'bg-bg';
$container = 'container';
if ( ! empty( $a['removeBottomPadding'] ) ) {
$container .= ' container-no-pb';
}
if ( $extra_section ) {
$section .= ' ' . $extra_section;
}
if ( $extra_container ) {
$container .= ' ' . $extra_container;
}
return array( $section, $container );
}
Le modèle de chaque bloc appelle cet utilitaire dès la première ligne. Il renvoie deux chaînes de classes : l’une pour l’élément <section> externe, l’autre pour le conteneur <div> interne.
Filtre de configuration Tailwind
Dans functions.php également, ajoutez le filtre qui transmet votre style.css au processeur Tailwind de Blockstudio :
add_filter(
'blockstudio/settings/tailwind/config',
function () {
$style = get_stylesheet_directory() . '/style.css';
if ( file_exists( $style ) ) {
// phpcs:ignore WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents -- Reading local theme file.
return file_get_contents( $style );
}
return '';
}
);
Cela indique à Blockstudio d’utiliser votre style.css comme source de configuration v4 Tailwind. Sans ce filtre, vos jetons @theme et définitions @utility ne seraient pas disponibles dans les modèles de blocs.
Votre premier bloc : Hero
Une section Hero illustre le modèle complet d’un bloc. Commencez par le schéma :
{
"$schema": "https://blockstudio.dev/schema/block",
"name": "my-theme/hero",
"title": "Hero",
"category": "my-theme",
"icon": "star-filled",
"description": "Full-width hero section with heading, description, and buttons.",
"blockstudio": {
"attributes": [
{
"type": "tabs",
"tabs": [
{
"title": "Content",
"attributes": [
{
"type": "group",
"attributes": [
{
"id": "heading",
"type": "text",
"label": "Heading",
"default": "Build beautiful websites without the complexity"
},
{
"id": "description",
"type": "textarea",
"label": "Description",
"default": "A powerful framework that lets you create stunning designs using the WordPress editor."
}
]
},
{
"type": "group",
"attributes": [
{
"id": "primaryButton",
"type": "link",
"label": "Primary Button",
"default": {
"title": "Get Started",
"url": "#"
}
},
{
"id": "secondaryButton",
"type": "link",
"label": "Secondary Button",
"default": {
"title": "Learn More",
"url": "#"
}
}
]
}
]
},
{
"title": "Section",
"attributes": [
{ "type": "custom/section" }
]
}
]
}
]
}
}
Principaux éléments à remarquer :
Le conteneur tabs crée un inspecteur à deux onglets : « Content » pour les champs du bloc et « Section » pour les commandes de section partagées. Tous les blocs utilisent cette structure.
Les champs sont organisés dans des conteneurs group. Les groupes séparent visuellement les champs associés dans l’inspecteur. Le premier groupe contient les champs de texte, le second les champs de lien.
Les valeurs par défaut fournissent un contenu pertinent afin que le bloc ait l’air complet dès son insertion. C’est essentiel pour composer une page, où les blocs sont ajoutés sans intervention de l’utilisateur.
Passons maintenant au modèle :
<?php list( $section_classes, $container_classes ) = mytheme_section_classes( $a, '', 'text-center' ); ?>
<section useBlockProps class="<?php echo esc_attr( $section_classes ); ?>">
<div class="<?php echo esc_attr( $container_classes ); ?>">
<h1 class="text-5xl font-medium tracking-tight sm:text-6xl lg:text-7xl">
<?php echo esc_html( $a['heading'] ); ?>
</h1>
<?php if ( ! empty( $a['description'] ) ) : ?>
<p class="mt-6 text-lg leading-relaxed text-muted max-w-xl mx-auto">
<?php echo esc_html( $a['description'] ); ?>
</p>
<?php endif; ?>
<div class="mt-10 flex items-center justify-center gap-x-4">
<?php if ( ! empty( $a['primaryButton']['url'] ) ) : ?>
<a href="<?php echo esc_url( $a['primaryButton']['url'] ); ?>" class="btn-primary">
<?php echo esc_html( $a['primaryButton']['title'] ); ?>
</a>
<?php endif; ?>
<?php if ( ! empty( $a['secondaryButton']['url'] ) ) : ?>
<a href="<?php echo esc_url( $a['secondaryButton']['url'] ); ?>" class="btn-secondary">
<?php echo esc_html( $a['secondaryButton']['title'] ); ?>
</a>
<?php endif; ?>
</div>
</div>
</section>
Le modèle suit une structure cohérente :
- Appelez l’utilitaire de section pour obtenir les classes CSS
- Élément
<section>externe avecuseBlockPropset les classes de section - Élément
<div>interne avec les classes de conteneur - Contenu rendu à partir de
$a(raccourci des attributs) - Rendu conditionnel des champs facultatifs
- Échappement correct :
esc_html()pour le texte,esc_url()pour les URL etesc_attr()pour les attributs
Ajouter des répéteurs : grille de fonctionnalités
Les répéteurs permettent aux clients d’ajouter, de supprimer et de réorganiser des éléments. Une grille de fonctionnalités en est l’exemple classique :
{
"$schema": "https://blockstudio.dev/schema/block",
"name": "my-theme/features",
"title": "Features",
"category": "my-theme",
"icon": "grid-view",
"description": "Feature grid with titles and descriptions.",
"blockstudio": {
"attributes": [
{
"type": "tabs",
"tabs": [
{
"title": "Content",
"attributes": [
{
"type": "group",
"attributes": [
{
"id": "heading",
"type": "text",
"label": "Heading",
"default": "Everything you need"
},
{
"id": "description",
"type": "textarea",
"label": "Description",
"default": "Our toolkit gives you the building blocks to go from idea to production."
}
]
},
{
"type": "group",
"attributes": [
{
"id": "features",
"type": "repeater",
"label": "Features",
"textMinimized": {
"id": "title",
"fallback": "Feature"
},
"default": [
{
"title": "Lightning Fast",
"description": "Optimized for performance with minimal overhead."
},
{
"title": "Fully Responsive",
"description": "Every component adapts across all screen sizes."
},
{
"title": "Easy to Customize",
"description": "Adjust every detail to match your brand."
}
],
"attributes": [
{
"id": "title",
"type": "text",
"label": "Title"
},
{
"id": "description",
"type": "textarea",
"label": "Description"
}
]
}
]
}
]
},
{
"title": "Section",
"attributes": [
{ "type": "custom/section" }
]
}
]
}
]
}
}
La propriété textMinimized détermine le texte affiché lorsque la ligne d’un répéteur est réduite. Elle lit la valeur du champ title et affiche « Feature » si celui-ci est vide. Cela facilite l’utilisation de l’inspecteur lorsque la liste contient de nombreux éléments.
Le tableau default fournit les éléments initiaux, qui apparaissent à la première insertion du bloc. Fournissez toujours des valeurs par défaut réalistes afin que le bloc ait immédiatement l’air complet.
<?php list( $section_classes, $container_classes ) = mytheme_section_classes( $a ); ?>
<section useBlockProps class="<?php echo esc_attr( $section_classes ); ?>">
<div class="<?php echo esc_attr( $container_classes ); ?>">
<?php if ( ! empty( $a['heading'] ) ) : ?>
<div class="text-center max-w-2xl mx-auto">
<h2 class="text-3xl font-medium tracking-tight sm:text-4xl">
<?php echo esc_html( $a['heading'] ); ?>
</h2>
<?php if ( ! empty( $a['description'] ) ) : ?>
<p class="mt-4 text-base leading-relaxed text-muted">
<?php echo esc_html( $a['description'] ); ?>
</p>
<?php endif; ?>
</div>
<?php endif; ?>
<?php if ( ! empty( $a['features'] ) ) : ?>
<div class="mt-16 grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3">
<?php foreach ( $a['features'] as $feature ) : ?>
<div class="card">
<h3 class="text-sm font-medium">
<?php echo esc_html( $feature['title'] ); ?>
</h3>
<p class="mt-2 text-sm leading-relaxed text-muted">
<?php echo esc_html( $feature['description'] ); ?>
</p>
</div>
<?php endforeach; ?>
</div>
<?php endif; ?>
</div>
</section>
Les éléments d’un répéteur sont accessibles sous la forme d’un simple tableau PHP. Utilisez foreach pour parcourir le tableau et accédez aux champs de chaque élément à l’aide de leur id.
Images et espaces réservés
Pour les blocs contenant des images, utilisez le type de champ files et le composant MediaPlaceholder. L’espace réservé affiche une zone de glisser-déposer dans l’éditeur :
{
"id": "image",
"type": "files",
"label": "Image"
}
Dans le modèle, affichez l’image avec wp_get_attachment_image() et un SVG d’espace réservé si aucune image n’est sélectionnée :
<div class="overflow-hidden rounded-2xl bg-elevated">
<MediaPlaceholder attribute="image" allowedTypes="<?php echo esc_attr( wp_json_encode( array( 'image' ) ) ); ?>" />
<?php if ( ! empty( $a['image'] ) ) : ?>
<?php echo wp_get_attachment_image( $a['image'][0]['ID'], 'full', false, array( 'class' => 'block w-full' ) ); ?>
<?php else : ?>
<?php echo blockstudio_placeholder_dark(); ?>
<?php endif; ?>
</div>
blockstudio_placeholder_dark() renvoie un SVG en ligne qui utilise currentColor avec la variable --color-accent ; il s’adapte ainsi automatiquement à votre thème. Pour les thèmes clairs, utilisez blockstudio_placeholder_light(). Les deux acceptent un argument de variante :
blockstudio_placeholder_dark( 'dashboard' ) // Dashboard mockup
blockstudio_placeholder_dark( 'chart' ) // Chart illustration
blockstudio_placeholder_dark( 'product' ) // Product shot
Composer des pages
Les pages assemblent des blocs en mises en page complètes avec la syntaxe <block>. Créez une page d’accueil :
{
"name": "home",
"title": "Home",
"slug": "home",
"postType": "page",
"postStatus": "publish",
"templateLock": "all"
}
<block name="my-theme/hero"></block>
<block name="my-theme/features"></block>
Voilà. Chaque élément <block> insère le bloc avec ses valeurs d’attribut par défaut. Exécutez wp bs pages sync pour appliquer la source de la page à WordPress.
Pour remplacer les valeurs par défaut d’une page spécifique, transmettez directement les attributs :
<block name="my-theme/hero" heading="About Us" description="Our story and mission."></block>
<block name="my-theme/features" heading="Our Values"></block>
Avec templateLock défini sur "all", les clients ne peuvent ni ajouter, ni supprimer, ni réorganiser les blocs. La structure de la page est verrouillée sur votre modèle. Consultez Pages pour découvrir d’autres modes de verrouillage et commandes de modification.
Développer la bibliothèque
Une bibliothèque minimale commence avec 3 à 5 blocs. Une bibliothèque complète en compte 8 à 14. Voici les types de blocs courants, classés approximativement selon leur fréquence d’utilisation :
| Bloc | Description | Champs principaux |
|---|---|---|
| Hero | Grand titre avec CTA | titre, description, liens |
| Features | Grille d’avantages | titre, répéteur avec titre + description |
| CTA | Bannière d’appel à l’action | titre, description, lien |
| Pricing | Comparaison des offres | titre, répéteur avec nom + prix + fonctionnalités |
| Testimonials | Citations de clients | répéteur avec citation + nom + fonction |
| FAQ | Accordéon de questions | titre, répéteur avec question + réponse |
| Logos | Nuage de logos clients | titre (les logos sont généralement des SVG intégrés en dur) |
| Content | Lignes alternant texte et image | répéteur avec titre + description + image |
| Showcase | Image pleine largeur avec légende | titre, description, image |
| Team | Grille de membres de l’équipe | titre, répéteur avec nom + fonction + image |
| Stats | Indicateurs clés | répéteur avec nombre + libellé |
Chaque bloc suit le même modèle : des onglets (Content + Section), des groupes pour organiser les champs, des répéteurs pour les listes et l’utilitaire de section pour un espacement cohérent. Après avoir créé deux ou trois blocs, l’ajout des suivants devient mécanique.
Ajouter d’autres pages
À mesure que votre bibliothèque s’agrandit, composez différentes pages à partir des mêmes blocs :
<block name="my-theme/hero" heading="Simple, Transparent Pricing" description="Choose the plan that fits."></block>
<block name="my-theme/pricing"></block>
<block name="my-theme/faq" heading="Pricing FAQ"></block>
<block name="my-theme/cta"></block>
<block name="my-theme/hero" heading="About Us" description="Our story."></block>
<block name="my-theme/team"></block>
<block name="my-theme/testimonials"></block>
<block name="my-theme/cta" heading="Join Our Team"></block>
Les mêmes blocs servent à plusieurs pages, chacune avec des valeurs par défaut différentes. C’est là tout l’intérêt de l’approche par bibliothèque : créez les blocs une seule fois et assemblez-les dans autant de pages que nécessaire.
Étapes suivantes
- Enregistrement des attributs : référence complète des types et propriétés de champs
- Types de champs : tous les types de champs disponibles
- Recueil de modèles de champs : groupes conditionnels, sélecteurs intelligents et recettes de répéteurs
- Pages : verrouillage des modèles, modes de modification et fusion par clé
- Créer des pages à partir de fichiers : guide pratique des modèles de page et de la synchronisation
- Interactivité : ajouter un comportement côté client aux blocs