Remplissage des options
Au lieu de fournir différents types de champs comme les articles, les utilisateurs ou les termes, Blockstudio permet de remplir les données de manière modulaire directement depuis block.json. Cette fonctionnalité est compatible avec les types de champs select, radio, checkbox, color et gradient.
Les données peuvent être remplies de quatre façons :
- Requête – Renvoie les résultats d’une requête sur des articles, des utilisateurs ou des termes
- Récupération – Renvoie les résultats d’une source externe
- Fonction – Renvoie les résultats d’une fonction personnalisée
- Personnalisé – Renvoie les résultats d’un jeu de données personnalisé
Requête
En mode requête, il est possible de remplir les options avec des articles, des utilisateurs ou des termes.
{
"$schema": "https://blockstudio.dev/schema/block",
"name": "blockstudio/native",
"title": "Native Block",
"blockstudio": {
"attributes": [
{
"id": "posts",
"type": "select",
"label": "Posts",
"populate": {
"type": "query",
"query": "posts"
}
}
]
}
}
Les types de requête disponibles utilisent en interne les fonctions WordPress suivantes :
Arguments
Vous pouvez transmettre des arguments personnalisés avec l’attribut arguments :
{
"blockstudio": {
"attributes": [
{
"id": "posts",
"type": "select",
"label": "Posts",
"populate": {
"type": "query",
"query": "posts",
"arguments": {
"post_type": "jobs",
"numberposts": "20"
}
}
}
]
}
}
Format de retour
Par défaut, Blockstudio renvoie :
| Requête | Valeur | Libellé |
|---|---|---|
posts |
objet d’article | post_title |
users |
objet utilisateur | display_name |
terms |
objet de terme | name |
Personnalisez la réponse avec returnFormat :
{
"blockstudio": {
"attributes": [
{
"id": "posts",
"type": "select",
"label": "Posts",
"populate": {
"type": "query",
"query": "posts",
"arguments": {
"post_type": "posts",
"numberposts": "20"
},
"returnFormat": {
"value": "id",
"label": "post_name"
}
}
}
]
}
}
Mode Fetch
Activez la recherche dynamique avec l’option fetch :
{
"blockstudio": {
"attributes": [
{
"id": "posts",
"type": "select",
"label": "Posts",
"populate": {
"type": "query",
"query": "posts",
"fetch": true,
"arguments": {
"post_type": "posts",
"numberposts": "20"
}
}
}
]
}
}
Cela active stylisedUi et récupère d’abord les 20 premiers articles. La saisie dans le champ de sélection recherche des articles à l’aide de l’argument s.
Fonction
Utilisez une fonction personnalisée pour remplir les options :
{
"blockstudio": {
"attributes": [
{
"id": "postTypes",
"type": "checkbox",
"label": "Post types",
"populate": {
"type": "function",
"function": "get_post_types"
}
}
]
}
}
Arguments
Transmettez les arguments sous forme de tableau (utilise call_user_func_array en interne) :
{
"blockstudio": {
"attributes": [
{
"id": "postTypes",
"type": "checkbox",
"label": "Post types",
"populate": {
"type": "function",
"function": "get_post_types",
"arguments": [[], "objects"]
}
}
]
}
}
Format de retour
{
"blockstudio": {
"attributes": [
{
"id": "postTypes",
"type": "checkbox",
"label": "Post types",
"populate": {
"type": "function",
"function": "get_post_types",
"arguments": [[], "objects"],
"returnFormat": {
"value": "name",
"label": "label"
}
}
}
]
}
}
Mélange d’options
Combinez des options statiques avec des données récupérées :
{
"blockstudio": {
"attributes": [
{
"id": "users",
"type": "radio",
"label": "Users",
"options": [
{
"value": "administrators",
"label": "Administrators"
},
{
"value": "editors",
"label": "Editors"
}
],
"populate": {
"type": "query",
"query": "users",
"position": "before"
}
}
]
}
}
L’option position (before ou after) détermine l’emplacement des options récupérées par rapport aux options statiques.
Avertissement
Le mélange d’options et de données récupérées n’est pas pris en charge en mode fetch.
Données personnalisées
Créez des jeux de données réutilisables avec le filtre blockstudio/blocks/attributes/populate. Le filtre reçoit un seul argument : un tableau de tous les jeux de données personnalisés indexés par nom. Ajoutez votre jeu de données sous une clé, puis renvoyez le tableau :
add_filter('blockstudio/blocks/attributes/populate', function($options) {
$options['customData'] = [
['value' => '1', 'label' => 'Option 1'],
['value' => '2', 'label' => 'Option 2'],
];
return $options;
});
Référencez ensuite la clé dans votre bloc :
{
"blockstudio": {
"attributes": [
{
"id": "posts",
"type": "select",
"label": "Posts",
"populate": {
"type": "custom",
"custom": "customData"
}
}
]
}
}
Données externes
Récupérez des données depuis une source externe :
{
"blockstudio": {
"attributes": [
{
"id": "select",
"type": "select",
"label": "Select",
"multiple": true,
"populate": {
"type": "fetch",
"arguments": {
"urlSearch": "https://example.com/wp-json/wp/v2/posts?search="
},
"returnFormat": {
"value": "id",
"label": "title.rendered"
}
}
}
]
}
}
Le terme de recherche est ajouté à urlSearch.
Arguments dynamiques
Les arguments de remplissage peuvent faire référence à d’autres attributs du bloc avec la syntaxe {attributes.*}. Lorsque l’attribut référencé change, les options du champ sont automatiquement récupérées à nouveau.
{
"blockstudio": {
"attributes": [
{
"id": "post_type",
"type": "select",
"label": "Post Type",
"options": [
{ "label": "Pages", "value": "page" },
{ "label": "Posts", "value": "post" }
]
},
{
"id": "selected_post",
"type": "select",
"label": "Select Post",
"populate": {
"type": "query",
"query": "posts",
"arguments": {
"post_type": "{attributes.post_type.value}",
"numberposts": 10
}
}
}
]
}
}
Cela fonctionne avec tous les types de remplissage (query, function, custom). Toute valeur de la configuration de remplissage contenant {attributes.*} est résolue côté client avec la valeur actuelle de l’attribut avant l’exécution de la requête.
Les références utilisent les valeurs enregistrées dans l’éditeur. Pour une option de sélection, utilisez {attributes.post_type.value} pour sa valeur ou {attributes.post_type.label} pour son libellé ; returnFormat contrôle la valeur du modèle, et non cette structure enregistrée dans l’éditeur.
Les arguments imbriqués sont résolus sans être sérialisés dans une chaîne de modèle.
Un argument composé d’un seul paramètre conserve le type de la référence, y compris les nombres, les booléens, les tableaux et les objets. Un paramètre intégré à un autre texte produit une chaîne. Les références manquantes restent inchangées, et les valeurs entre guillemets ou sur plusieurs lignes sont transmises telles quelles.
Les rappels de fonction conservent leurs listes d’arguments positionnels. L’éditeur ajoute des arguments de recherche WordPress uniquement aux fonctions query, pas aux appels de fonction.
Rendu de sélections dépendantes
Les options dépendantes ne sont pas chargées lors de l’enregistrement du bloc, car chaque instance de bloc peut avoir des arguments différents. Le rendu utilise la sélection enregistrée au lieu de la rejeter face à une liste d’options vide. Le rappel de remplissage n’est pas exécuté à nouveau sur le site.
Le paramètre returnFormat du champ s’applique toujours :
returnFormat |
Sélection unique | Sélection multiple |
|---|---|---|
value (par défaut) |
La valeur enregistrée, par exemple "a" |
Un tableau de valeurs enregistrées, par exemple ["a", "b"] |
label |
Le libellé enregistré | Un tableau de libellés enregistrés |
both |
L’option {value, label} enregistrée |
Un tableau d’options enregistrées |
Pour les sélections alimentées par une requête, les valeurs correspondent toujours à l’objet publication, utilisateur ou terme WordPress correspondant, sauf si populate.returnFormat.value est "id". Les libellés proviennent de la sélection enregistrée. Si une sélection importée n’a pas de libellé, sa valeur sert de libellé. Une option statique correspondante déclarée dans options est prioritaire sur l’option enregistrée : son libellé actuel s’applique.
Les sélections vides restent false (ou utilisent la valeur fallback configurée pour le champ). Cela ne modifie pas la validation des options statiques ordinaires : une valeur enregistrée qui ne figure plus dans une liste d’options statiques renvoie toujours false.
Les sélections dynamiques préservent également les sélections default et fallback lorsque leurs options sont différées. Utilisez une valeur scalaire, une option {value, label} ou un tableau de l’un ou l’autre pour une sélection multiple. Une valeur scalaire utilise sa valeur comme libellé, sauf si elle correspond à une option statique déclarée. Un objet option préserve le libellé fourni ; une option statique correspondante est prioritaire. Aucun rappel populate ne s’exécute sur le serveur pour rechercher ces valeurs par défaut.