Dans ce document, nous allons voir comment utiliser JSON pour définir les entrées, les champs (y compris les libellés) et les connexions de votre bloc. Si vous ne connaissez pas ces termes, consultez la section Anatomie d'un bloc avant de continuer.
Vous pouvez également définir vos entrées, vos champs et vos connexions en JavaScript.
Présentation
En JSON, vous décrivez la structure d'un bloc avec une ou plusieurs chaînes de message (message0, message1, ...) et leurs tableaux d'arguments correspondants (args0, args1, ...). Les chaînes de message sont constituées de texte, qui est converti en libellés, et de jetons d'interpolation (%1, %2, ...), qui marquent les emplacements des connexions et des champs sans libellé. Les tableaux d'arguments décrivent comment gérer les jetons d'interpolation.
Par exemple, ce bloc :
est défini par le code JSON suivant :
JSON
{
"message0": "set %1 to %2",
"args0": [
{
"type": "field_variable",
"name": "VAR",
"variable": "item",
"variableTypes": [""]
},
{
"type": "input_value",
"name": "VALUE"
}
]
}
Le premier jeton d'interpolation (%1) représente un champ
de variable
(type: "field_variable"). Il est décrit par le premier objet du args0
tableau. Le deuxième jeton (%2) représente la connexion d'entrée à la fin d'une
entrée de valeur
(type: "input_value"). Il est décrit par le deuxième objet du args0
tableau.
Messages et entrées
Lorsqu'un jeton d'interpolation marque une connexion, il marque en réalité la fin de l'entrée qui contient la connexion. En effet, les connexions dans les entrées de valeur et d'instruction sont affichées à la fin de l'entrée. L'entrée contient tous les champs (y compris les libellés) après l'entrée précédente et jusqu'au jeton actuel. Les sections suivantes présentent des exemples de messages et les entrées créées à partir de ceux-ci.
Exemple 1
JSON
{
"message0": "set %1 to %2",
"args0": [
{"type": "field_variable", ...} // token %1
{"type": "input_value", ...} // token %2
],
}
Cela crée une seule entrée de valeur avec trois champs : un libellé ("set"), un
champ de variable et un autre libellé ("to").
Exemple 2
JSON
{
"message0": "%1 + %2",
"args0": [
{"type": "input_value", ...} // token %1
{"type": "input_value", ...} // token %2
],
}
Cela crée deux entrées de valeur. La première ne comporte aucun champ et la seconde en comporte un
champ ("+").
Exemple 3
JSON
{
"message0": "%1 + %2 %3",
"args0": [
{"type": "input_value", ...} // token %1
{"type": "input_end_row", ...} // token %2
{"type": "input_value", ...} // token %3
],
}
Cela crée :
- une entrée de valeur sans champ ;
- une entrée de fin de ligne
avec un champ de libellé (
"+"), ce qui entraîne l'affichage de l'entrée de valeur suivante sur une nouvelle ligne ; - une entrée de valeur sans champ.
Entrée factice à la fin du message
Si votre chaîne message se termine par du texte ou des champs, vous n'avez pas besoin d'ajouter de jeton d'interpolation pour l'entrée factice qui les contient. Blockly l'ajoute pour vous. Par exemple, au lieu de définir un bloc lists_isEmpty comme ceci :
JSON
{
"message0": "%1 is empty %2",
"args0": [
{"type": "input_value", ...} // token %1
{"type": "input_dummy", ...} // token %2
],
}
vous pouvez laisser Blockly ajouter l'entrée factice et la définir comme ceci :
JSON
{
"message0": "%1 is empty",
"args0": [
{"type": "input_value", ...} // token %1
],
}
L'ajout automatique d'une entrée factice de fin permet aux traducteurs de modifier message sans avoir à modifier les arguments qui décrivent les jetons d'interpolation. Pour en savoir plus, consultez Ordre des jetons
d'interpolation.
implicitAlign
Dans de rares cas, l'entrée factice de fin créée automatiquement doit être alignée
sur "RIGHT" ou "CENTRE". La valeur par défaut, si elle n'est pas spécifiée, est "LEFT".
Dans l'exemple ci-dessous message0 est "send email to %1 subject %2 secure %3"
et Blockly ajoute automatiquement une entrée factice pour la troisième ligne. Définir
implicitAlign0 sur "RIGHT" force l'alignement de cette ligne à droite.
implicitAlign
s'applique à toutes les entrées qui ne sont pas explicitement définies dans la définition de bloc JSON, y compris les entrées de fin de ligne qui remplacent les caractères de nouvelle ligne
('\n'). Il existe également la propriété obsolète
lastDummyAlign0 qui a le même comportement que implicitAlign0.
Lors de la conception de blocs pour les langues s'écrivant de droite à gauche (arabe et hébreu), la gauche et la droite sont inversées.
Ainsi, "RIGHT" alignerait les champs à gauche.
Plusieurs messages
Certains blocs sont naturellement divisés en deux parties distinctes ou plus. Prenons l'exemple de ce bloc de répétition qui comporte deux lignes :
Si ce bloc était décrit avec un seul message, la message0 propriété
serait "repeat %1 times %2 do %3", où %2 représente une entrée de fin de ligne. Cette chaîne est difficile à traduire, car il est difficile d'expliquer ce que signifie la substitution %2. L'entrée de fin de ligne %2 peut même ne pas être souhaitée dans certaines langues. De plus, plusieurs blocs peuvent souhaiter partager le texte de la deuxième ligne. Une meilleure approche consiste à utiliser plusieurs propriétés message et args :
JSON
{
"message0": "repeat %1 times",
"args0": [
{"type": "input_value", ...} // token %1 in message0
],
"message1": "do %1",
"args1": [
{"type": "input_statement", ...} // token %1 in message1
],
}
Vous pouvez définir autant de propriétés message, args et implicitAlign que vous le souhaitez au format JSON, en commençant par 0 et en incrémentant de manière séquentielle. Notez que la Block Factory n'est pas en mesure de diviser les messages en plusieurs parties, mais vous pouvez le faire manuellement.
Ordre des jetons d'interpolation
Lorsque vous localisez des blocs, vous devrez peut-être modifier l'ordre des jetons d'interpolation dans un message. Cela est particulièrement important dans les langues dont l'ordre des mots est différent de l'anglais. Par exemple, nous avons commencé par un bloc défini
par le message "set %1 to %2" :
Prenons maintenant l'exemple d'une langue hypothétique dans laquelle "set %1 to %2" doit être inversé
pour dire "put %2 in %1". Si vous modifiez le message (y compris l'ordre des jetons d'interpolation) et que vous laissez le tableau d'arguments inchangé, vous obtenez le bloc suivant :
Blockly a automatiquement modifié l'ordre des champs, créé une entrée factice input, et est passé d'entrées externes à des entrées internes inputs.
La possibilité de modifier l'ordre des jetons d'interpolation dans un message facilite la localisation. Pour en savoir plus, consultez Interpolation de messages JSON.
Gestion du texte
Le texte de part et d'autre d'un jeton d'interpolation est tronqué par des espaces.
Le texte utilisant le caractère % (par exemple, lorsqu'il fait référence à un pourcentage) doit utiliser
%% afin qu'il ne soit pas interprété comme un jeton d'interpolation.
Blockly remplace également automatiquement tout caractère de nouvelle ligne (\n) dans la chaîne de message par une entrée de fin de ligne.
JSON
{
"message0": "set %1\nto %2",
"args0": [
{"type": "field_variable", ...}, // token %1
{"type": "input_value", ...}, // token %2
]
}
Tableaux d'arguments
Chaque chaîne de message est associée à un tableau args du même nombre. Par exemple, message0 est associé à args0. Les jetons d'interpolation
(%1, %2, ...) font référence aux éléments du tableau args et doivent correspondre entièrement au
args0 tableau : pas de doublons, pas d'omissions. Les numéros de jeton font référence à l'ordre des éléments dans le tableau d'arguments. Ils ne sont pas obligatoires dans une chaîne de message.
Chaque objet du tableau d'arguments comporte une chaîne type. Le reste des paramètres varie en fonction du type :
Vous pouvez également définir vos propres champs personnalisés et entrées personnalisées et les transmettre en tant qu'arguments.
Champs alt
Chaque objet peut également comporter un champ alt. Si Blockly ne reconnaît pas le type de l'objet, l'objet alt est utilisé à la place. Par exemple, si un nouveau champ nommé field_time est ajouté à Blockly, les blocs utilisant ce champ peuvent utiliser alt pour définir un remplacement field_input pour les anciennes versions de Blockly :
JSON
{
"message0": "sound alarm at %1",
"args0": [
{
"type": "field_time",
"name": "TEMPO",
"hour": 9,
"minutes": 0,
"alt":
{
"type": "field_input",
"name": "TEMPOTEXT",
"text": "9:00"
}
}
]
}
Un objet alt peut avoir son propre objet alt, ce qui permet de les enchaîner.
En fin de compte, si Blockly ne parvient pas à créer un objet dans le tableau args0 (après avoir tenté d'utiliser des objets alt), cet objet est simplement ignoré.