Outils de validation

Un validateur est une fonction qui reçoit la nouvelle valeur des champs, puis agit dessus. Ils permettent de personnaliser facilement un champ. Ils vous permettent de déclencher une fonctionnalité lorsque la valeur d'un champ change, de modifier l'entrée ou de limiter les valeurs acceptables.

Voici quelques exemples courants :

  • Limiter un champ de texte à l'acceptation de lettres uniquement.
  • Exiger qu'un champ de texte ne soit pas vide.
  • Exiger que la date soit future
  • Modification de la forme d'un bloc en fonction d'une liste déroulante.

Types de validateurs

Les validateurs s'exécutent à différents moments en fonction du type de validateur.

Les validateurs de classe font partie de la définition de classe d'un type de champ et sont généralement utilisés pour limiter le type de valeur autorisé par le champ (par exemple, les champs numériques n'acceptent que des caractères numériques). Les validateurs de classe sont exécutés sur toutes les valeurs transmises au champ (y compris la valeur transmise au constructeur).

Pour en savoir plus sur les validateurs de classe, consultez la section Implémenter un valideur de classe dans la section "Créer un champ personnalisé".

Les validateurs locaux sont définis au moment de la création d'un champ. Les validateurs locaux s'exécutent sur toutes les valeurs transmises au champ sauf la valeur transmise au constructeur. Ils s'exécutent sur:

  • Valeurs contenues dans le fichier XML.
  • Valeurs transmises à setValue.
  • Valeurs transmises à setFieldValue.
  • Valeurs modifiées par l'utilisateur.

Les validateurs de classe sont exécutés avant les validateurs locaux, car ils agissent comme des gardiens. Ils s'assurent que la valeur est du bon type avant de la transmettre.

Pour en savoir plus sur la séquence de validation des valeurs et sur les valeurs en général, consultez la section "Valeurs".

Enregistrer un validateur local

Vous pouvez enregistrer des validateurs locaux de deux manières:

  • Ajouté directement dans le constructeur d'un champ.
Blockly.Blocks['validator_example'] = {
  init: function() {
    // Remove all 'a' characters from the text input's value.
    var validator = function(newValue) {
      return newValue.replace(/\a/g, '');
    };

    this.appendDummyInput()
        .appendField(new Blockly.FieldTextInput('default', validator));
  }
};

Blockly.Blocks['validator_example'] = {
  init: function() {
    // Remove all 'a' characters from the text input's value.
    var validator = function(newValue) {
      return newValue.replace(/\a/g, '');
    };

    var field = new Blockly.FieldTextInput('default');
    field.setValidator(validator);

    this.appendDummyInput().appendField(field);
  }
};

Chacune des méthodes ci-dessus peut être encapsulée dans une extension pour prendre en charge le format JSON.

La valeur du champ peut être très différente selon le type de champ validé (par exemple, un champ numérique stocke un nombre, tandis qu'un champ de saisie de texte stocke une chaîne). Il est donc préférable de lire la documentation de votre champ spécifique avant de créer un validateur.

Valeurs renvoyées

La valeur renvoyée par le validateur détermine ce que le champ fait ensuite. Il existe trois possibilités:

Valeur renvoyée modifiée

Valeur modifiée ou différente, qui devient la nouvelle valeur du champ. Cette opération est souvent utilisée pour nettoyer une valeur, par exemple en supprimant les espaces vides à la fin.

Exemple de validateur de modification:

// Remove all 'a' characters from the text input's value.
var validator = function(newValue) {
  return newValue.replace(/\a/g, '');
};

Champ de saisie de texte avec un validateur de modification

Valeur renvoyée nulle

Null, ce qui signifie que la valeur donnée n'est pas valide. Dans la plupart des cas, le champ ignore la valeur saisie. Le comportement exact est spécifié par la fonction doValueInvalid_ du champ.

Exemple de validateur de valeurs nulles:

// Any value containing a 'b' character is invalid.  Other values are valid.
var validator = function(newValue) {
  if (newValue.indexOf('b') != -1) {
    return null;
  }
  return newValue;
};

Champ de saisie de texte avec un validateur de valeurs nulles

Valeur renvoyée non définie

Non défini (ou aucune instruction de retour) ou valeur d'entrée, ce qui signifie que la valeur d'entrée doit devenir la nouvelle valeur du champ. Ces types de validateurs agissent généralement en tant qu'écouteurs de modifications.

Exemple de validateur d'écouteur:

// Log the new value to console.
var validator = function(newValue) {
  console.log(newValue);
};

Notez à nouveau que le texte affiché ne reflète pas nécessairement la valeur du champ.

Valeur de ce paramètre

Dans un valideur, this fait référence au champ, et non au bloc. Si vous devez accéder au bloc dans un validateur, utilisez la fonction getSourceBlock. Vous pouvez également utiliser la fonction bind pour définir le contexte dans lequel le validateur est appelé.

Exemple de code utilisant getSourceBlock:

Blockly.Blocks['colour_match'] = {
  init: function() {
    this.appendDummyInput()
        .appendField(new Blockly.FieldColour(
            null, this.validate
        ), 'COLOUR');
    this.setColour(this.getFieldValue('COLOUR'));
  },

  validate: function(colourHex) {
    this.getSourceBlock().setColour(colourHex);
  }
};

Exemple de code utilisant bind:

Blockly.Blocks['colour_match'] = {
  init: function() {
    this.appendDummyInput()
      .appendField(new Blockly.FieldColour(
          null, this.validate.bind(this)
      ), 'COLOUR');
    this.validate(this.getFieldValue('COLOUR'));
  },

  validate: function(colourHex) {
    this.setColour(colourHex);
  }
};