Champs personnalisés
Les champs personnalisés permettent de définir des groupes de champs réutilisables auxquels plusieurs blocs peuvent faire référence. Considérez-les comme des modèles de champs : définissez-les une fois, utilisez-les partout.
Les champs personnalisés ne sont pas la même chose que les types de champs personnalisés. Utilisez custom/{name} pour des groupes réutilisables de champs existants. Utilisez un type de champ personnalisé avec espace de noms, tel que acme/dimensions, lorsqu’un thème ou une extension enregistre un nouveau contrôle d’éditeur et une nouvelle structure de valeur.
Enregistrement dans le système de fichiers
Créez un fichier field.json dans un répertoire fields/ de votre répertoire blockstudio :
theme/
└── blockstudio/
└── fields/
└── hero/
└── field.json
{
"$schema": "https://blockstudio.dev/schema/field",
"name": "hero",
"title": "Hero Section",
"attributes": [
{
"id": "heading",
"type": "text",
"label": "Heading",
"default": "Hello World"
},
{ "id": "description", "type": "textarea", "label": "Description" },
{ "id": "enabled", "type": "toggle", "label": "Enabled" }
]
}
Enregistrement avec le filtre PHP
Enregistrez les champs personnalisés par programmation à l’aide du filtre blockstudio/fields :
add_filter('blockstudio/fields', function ($fields) {
$fields['cta'] = [
'title' => 'Call to Action',
'attributes' => [
['id' => 'text', 'type' => 'text', 'label' => 'Button Text'],
['id' => 'url', 'type' => 'text', 'label' => 'URL'],
],
];
return $fields;
});
Utilisation dans block.json
Faites référence à un champ personnalisé à l’aide du type custom/{name} :
{
"blockstudio": {
"attributes": [{ "type": "custom/hero" }]
}
}
Cela développe en ligne les champs définis dans la définition du champ personnalisé. Les champs développés conservent leurs ID d’origine (heading, description, enabled).
Les champs personnalisés peuvent également réutiliser des définitions de groupe complètes :
{
"name": "section-header",
"attributes": [
{
"id": "section-header",
"type": "group",
"title": "Header",
"attributes": [
{ "id": "kicker", "type": "text", "label": "Kicker" },
{ "id": "title", "type": "text", "label": "Title" }
]
}
]
}
{
"blockstudio": {
"attributes": [{ "type": "custom/section-header" }]
}
}
Les enfants du groupe sont stockés sous forme de section-header_kicker, section-header_title, etc. Dans les modèles, utilisez bs_get_group() pour les extraire dans un objet de groupe bien structuré.
Structure des ID
Utilisez idStructure pour ajouter un préfixe aux ID de champ ou les transformer. Le marqueur {id} est remplacé par l’ID de champ d’origine :
{
"blockstudio": {
"attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
}
}
Cela génère des champs avec les ID suivants : hero_heading, hero_description, hero_enabled.
Remplacements
Personnalisez des champs individuels pour chaque instance à l’aide de overrides. Les clés sont les ID de champ d’origine de la définition :
{
"blockstudio": {
"attributes": [
{
"type": "custom/hero",
"idStructure": "hero_{id}",
"overrides": {
"heading": { "default": "Welcome", "label": "Title" },
"enabled": { "id": "active" }
}
}
]
}
}
Les propriétés de remplacement sont fusionnées avec la définition de champ d’origine. Un remplacement id contourne le modèle idStructure. Dans l’exemple ci-dessus, enabled devient active au lieu de hero_enabled.
La fusion s’effectue sur un seul niveau : toute propriété que vous remplacez écrase entièrement la propriété d’origine. Une surcharge options correspond à la liste complète des options, et non à un ajout à celle-ci ; il en va de même pour conditions et pour le attributes d’un groupe. Les conditions de la référence sont toujours ajoutées ensuite.
{
"type": "custom/background",
"overrides": {
"background": {
"options": [
{ "value": "white", "label": "White" },
{ "value": "grey", "label": "Grey" }
]
}
}
}
Ce bloc ne propose que les couleurs White et Grey, quel que soit le nombre d’options listées dans la définition.
Conditions
Les conditions dans les définitions de champs personnalisés sont automatiquement réécrites lorsque idStructure est appliqué. Un champ dont la condition dépend d’un champ frère continue de fonctionner après son développement.
{
"name": "font-size",
"attributes": [
{ "id": "enable", "type": "toggle", "label": "Modify font size" },
{
"id": "min",
"type": "number",
"label": "Min Size",
"conditions": [[{ "id": "enable", "operator": "==", "value": true }]]
},
{
"id": "max",
"type": "number",
"label": "Max Size",
"conditions": [[{ "id": "enable", "operator": "==", "value": true }]]
}
]
}
{ "type": "custom/font-size", "idStructure": "title_font_{id}" }
Blockstudio développe ceci en title_font_enable, title_font_min, title_font_max et réécrit les conditions pour faire référence à title_font_enable au lieu de enable. Les contrôles toggle fonctionnent exactement comme si les champs étaient définis en ligne.
Conditions au niveau de la référence
Ajoutez conditions à la référence pour appliquer les conditions à chaque champ développé. Cette option est utile pour masquer un groupe entier derrière une option toggle externe :
{
"type": "custom/font-size",
"idStructure": "subtitle_font_{id}",
"conditions": [[{ "id": "show_advanced", "operator": "==", "value": true }]]
}
Ces conditions sont fusionnées avec celles déjà définies dans la définition du champ. Les ID de condition sont également réécrits via idStructure.
Plusieurs champs personnalisés
Vous pouvez utiliser plusieurs champs personnalisés dans un même bloc, avec des champs classiques :
{
"blockstudio": {
"attributes": [
{ "id": "intro", "type": "text", "label": "Intro" },
{ "type": "custom/hero", "idStructure": "hero_{id}" },
{ "type": "custom/cta", "idStructure": "cta_{id}" }
]
}
}
Imbrication
Les champs personnalisés fonctionnent dans les groupes, les onglets et les répéteurs :
{
"blockstudio": {
"attributes": [
{
"type": "group",
"id": "content",
"title": "Content",
"attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
}
]
}
}
Chemins de découverte supplémentaires
Utilisez le filtre blockstudio/fields/paths pour ajouter des répertoires supplémentaires à la découverte des champs :
add_filter('blockstudio/fields/paths', function ($paths) {
$paths[] = get_stylesheet_directory() . '/blockstudio/fields';
return $paths;
});
Analyse statique
Le package blockstudio/phpstan développe les références custom/* issues de fichiers lors de la validation de PHP, Twig, Blade, des balises de bloc et des structures d’attributs déduites. Son développement suit les mêmes règles d’imbrication, de idStructure et de overrides décrites ci-dessus.
Pour les définitions situées hors du projet analysé, ajoutez le répertoire de la bibliothèque à blockstudioScanRoots dans phpstan.neon. Les champs enregistrés uniquement via le filtre blockstudio/fields PHP existent à l’exécution et ne peuvent pas être déduits statiquement.