Outils de validation

Un validateur est une fonction qui prend la nouvelle valeur des champs et agit en conséquence. Ils permettent de personnaliser facilement un champ. Ils vous permettent de déclencher une fonctionnalité lorsque la valeur d'un champ change, de modifier une entrée ou de limiter les valeurs acceptables.

Voici quelques exemples courants :

• Restreindre un champ de texte pour qu'il n'accepte que des lettres.
• Exige qu'un champ de texte ne soit pas vide.
• Exiger qu'une date soit dans le futur
• Modification de la forme d'un bloc en fonction d'un menu déroulant.

Remarque : Les validateurs modifient la valeur d'un champ, et non son texte.

Types de validateurs

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

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 les 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 validateur de classe dans 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 , à l'exception de la valeur transmise au constructeur. Cela signifie qu'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 :

• Directement ajoutée dans le constructeur d'un champ.

Remarque : La signature du constructeur de champ peut varier en fonction du type de 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));
  }
};

• Avec setValidator.

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.

Remarque : Seuls les champs modifiables acceptent les validateurs. Veillez donc à consulter la documentation du champ concerné.

Valeurs renvoyées

La valeur renvoyée par le validateur détermine ce que le champ fait ensuite. Trois possibilités s'offrent à vous :

Valeur renvoyée modifiée

Une valeur modifiée ou différente, qui devient la nouvelle valeur du champ. Elle est souvent utilisée pour nettoyer une valeur, par exemple en supprimant les espaces blancs de 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, '');
};

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 suppression :

// 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;
};

Valeur de retour non définie

"Undefined" (ou aucune instruction de retour) ou la 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 comme des écouteurs de modification.

Exemple de Listener Validator :

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

Notez encore une fois que le texte affiché ne reflète pas nécessairement la valeur du champ.

Valeur de ce

Dans un validateur, this fait référence au champ, et non au bloc. Si vous devez accéder au bloc à l'intérieur d'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);
  }
};