Extensions
Les extensions vous permettent d’étendre n’importe quel bloc enregistré dans votre installation WordPress au moyen d’une simple API basée sur .json, similaire à la configuration block.json. Cela inclut les blocs natifs, tiers et ceux créés avec Blockstudio.
Types de champs peuvent être ajoutés à n’importe quel bloc, et les données sont enregistrées dans les attributs du bloc. Toutes les fonctionnalités des attributs sont disponibles pour les extensions, notamment le filtrage, la désactivation, la logique conditionnelle et le remplissage des options.
Types d’extension
Les valeurs étendues peuvent être utilisées de différentes manières :
- class : ajoute une classe au bloc à l’aide de la valeur de l’attribut
- style : ajoute des styles en ligne au bloc à l’aide de la valeur de l’attribut
- attributes : définit directement toute valeur d’attribut sur le bloc
- data attributes : utilise les valeurs d’extension pour définir des attributs de données spécifiques
Configuration
Imaginons le scénario suivant : vous souhaitez ajouter un champ select de classe personnalisée à chaque bloc de base. Il vous suffit d’ajouter ce fichier .json n’importe où dans le dossier de votre bloc ; il sera automatiquement enregistré comme extension.
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"priority": 10,
"blockstudio": {
"extend": true,
"attributes": [
{
"id": "customColor",
"type": "select",
"label": "Custom color",
"options": [
{
"value": "#f00",
"label": "Red"
},
{
"value": "#00f",
"label": "Blue"
}
],
"set": [
{
"attribute": "style",
"value": "color: {attributes.customColor}"
}
]
}
]
}
}
Cela ajoutera un champ customColor à chaque bloc de base, afin de vous permettre de définir la couleur du texte du bloc.
Nom du fichier
Comme il n’existe aucun modèle de rendu, une extension n’a pas besoin d’un fichier index correspondant ni d’être nommée block.json. Toutes les extensions peuvent ainsi être stockées dans un seul dossier. Plusieurs fichiers peuvent étendre les mêmes blocs, par exemple deux fichiers avec "name": "core/*" ; chacun enregistre ses propres champs.
Schéma
Blockstudio fournit un schéma JSON personnalisé pour les configurations d’extension :
Afficher le schéma d’extension
Nom
La propriété name de l’objet de configuration définit les blocs à étendre. Selon vos besoins, trois options sont possibles :
- blockName : un seul nom de bloc, e.g.
core/paragraph - [blockNameA, blockNameB] : un tableau de noms de blocs, e.g.
["core/paragraph", "core/heading"] - core/* : un caractère générique pour étendre tous les blocs d’un type donné
Tout nom se terminant par un astérisque est un joker de préfixe, et pas seulement core/*. L’extension suivante s’applique à chaque bloc dont le nom commence par my-plugin/,
y compris les blocs créés avec Blockstudio :
{
"name": "my-plugin/*",
"blockstudio": {
"extend": true,
"attributes": []
}
}
Exclure des blocs
Utilisez un tableau exclude de premier niveau pour ignorer les blocs qui correspondraient autrement à name :
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"exclude": ["core/button", "core/image"],
"blockstudio": {
"extend": true,
"attributes": []
}
}
Les exclusions utilisent les mêmes règles de correspondance par nom exact et par préfixe final * que name.
Elles ont priorité sur les noms uniques, les listes de noms et les jokers. Un
bloc exclu ne reçoit ni les champs de l’éditeur de l’extension ni ses attributs
ou ressources frontaux. Les autres extensions correspondantes ne sont pas affectées. Omettez exclude ou utilisez un
tableau vide pour conserver le comportement existant.
Clé Blockstudio
Comme pour l’utilisation de block.json avec des blocs personnalisés, la propriété blockstudio doit figurer dans l’objet de configuration et extend doit être défini sur true.
Position
Par défaut, les extensions s’affichent dans leur propre onglet de l’inspecteur de blocs. Pour les déplacer, vous pouvez utiliser la propriété group :
- settings : position par défaut
- styles : onglet des styles
- advanced : onglet avancé
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"blockstudio": {
"extend": true,
"group": "styles",
"attributes": []
}
}
Priorité
La propriété priority vous permet de définir l’ordre d’affichage des extensions. Les extensions ayant une priorité plus élevée s’affichent plus tard. Définissez-la au niveau supérieur du fichier, comme dans l’exemple de configuration, ou dans extend :
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"blockstudio": {
"extend": { "priority": 10 },
"attributes": []
}
}
Lorsque les deux sont définis, blockstudio.extend.priority l’emporte.
Attributs
Pour en savoir plus sur le fonctionnement des attributs, consultez la section sur les attributs.
Pour les attributs des extensions, la seule chose à connaître est la propriété set. Elle sert à appliquer la valeur de l’attribut à l’un des types d’extension.
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"blockstudio": {
"extend": true,
"attributes": [
{
"id": "customColor",
"type": "select",
"label": "Heading color",
"options": [
{
"value": "#f00",
"label": "Red"
},
{
"value": "#00f",
"label": "Blue"
}
],
"set": [
{
"attribute": "style",
"value": "color: {attributes.customColor}"
}
]
}
]
}
}
Récupération des valeurs
La notation par points entre accolades permet de récupérer la valeur d’un attribut.
Il est également possible de récupérer des valeurs imbriquées lorsque les attributs ne renvoient pas une valeur unique, par exemple si vous définissez le format de retour sur both pour des types de champs avec des options.
{
"attributes": [
{
"id": "customColor",
"type": "select",
"label": "Heading color",
"options": [
{
"value": "#f00",
"label": "Red"
},
{
"value": "#00f",
"label": "Blue"
}
],
"returnFormat": "both",
"set": [
{
"attribute": "style",
"value": "color: {attributes.customColor.value}"
},
{
"attribute": "data-color",
"value": "{attributes.customColor.label}"
}
]
}
]
}
L’exemple ci-dessus définira l’attribut style sur color: #f00 ou color: #00f, et l’attribut data-color sur Red ou Blue, selon la valeur.
Pour l’instant, seules les valeurs de l’attribut actuel peuvent être utilisées dans les définitions set. La possibilité d’utiliser les valeurs d’autres attributs pourra être ajoutée ultérieurement.
Tableaux
Avec les tableaux, la propriété set s’applique à chaque élément du tableau.
Chaque élément ajoute sa propre classe ou déclaration de style. Tout autre attribut contient une seule valeur ; chaque élément l’écrase donc et le dernier l’emporte. Définissez join sur true pour écrire à la place les résultats de tous les éléments, séparés par des espaces et sans valeurs vides ni répétées, afin qu’un sélecteur comme [data-langs~="en"] corresponde à chaque élément choisi. join n’a aucun effet sur class et style, ni sur les champs qui renvoient une seule valeur.
{
"id": "langs",
"type": "checkbox",
"label": "Languages",
"options": [
{
"value": "en",
"label": "English"
},
{
"value": "de",
"label": "German"
}
],
"set": [
{
"attribute": "data-langs",
"value": "{attributes.langs}",
"join": true
}
]
}
Choisir les deux options génère data-langs="en de". Sans join, le résultat est data-langs="de".
Champ Attributes
Avec le champ attributes, la propriété set n’est pas nécessaire, car le champ associe automatiquement les valeurs au nom et à la valeur de l’attribut.
Examiner les champs des extensions
bs_block_extension_fields('core/paragraph') renvoie les définitions de champs de
chaque extension correspondant à un bloc. Consultez
Examen des blocs pour connaître la valeur renvoyée
et son lien avec bs_block_fields().