Validatori

Un validator è una funzione che prende il nuovo valore dei campi e poi lo gestisce. Sono un modo semplice per personalizzare un campo. Ti consentono di attivare la funzionalità quando il valore di un campo cambia, di modificare l'input o di limitare i valori accettabili.

Alcuni esempi comuni:

• Limitare un campo di testo in modo che accetti solo lettere.
• Richiedere che un campo di testo non sia vuoto.
• Richiedere che una data sia futura.
• Modifica della forma di un blocco in base a un menu a discesa.

Nota: i controlli di convalida modificano il valore di un campo, non il relativo testo.

Tipi di convalidatori

I validator vengono eseguiti in momenti diversi a seconda del tipo di validator.

I validatori di classe fanno parte della definizione di classe di un tipo di campo e vengono solitamente utilizzati per limitare il tipo di valore consentito dal campo (ad es. i campi numerici accettano solo caratteri numerici). I validatori di classe vengono eseguiti su tutti i valori passati al campo (incluso il valore passato al costruttore).

Per ulteriori informazioni sui convalidatori di classi, consulta la sezione Implementazione di un convalidatore di classi nella pagina Creazione di un campo personalizzato.

I validatori locali vengono definiti al momento della creazione di un campo. I validatori locali vengono eseguiti su tutti i valori passati al campo tranne il valore passato al constructor. Ciò significa che vengono eseguiti su:

• Valori contenuti in XML.
• Valori passati a setValue.
• Valori passati a setFieldValue.
• Valori modificati dall'utente.

I validatori di classe vengono eseguiti prima di quelli locali perché agiscono come gatekeeper. Prima di trasmetterlo, si assicurano che il valore sia del tipo corretto.

Per ulteriori informazioni sulla sequenza di convalida dei valori e sui valori in generale, consulta la sezione Valori.

Registrazione di uno strumento di convalida locale

I validatori locali possono essere registrati in due modi:

• Aggiunto direttamente nel costruttore di un campo.

Nota: la firma del costruttore del campo può essere diversa a seconda del tipo di campo.

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

• Con 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);
  }
};

Entrambi i metodi precedenti possono essere racchiusi in un'estensione per supportare il formato JSON.

Il valore del campo può essere molto diverso a seconda del tipo di campo sottoposto a convalida (ad es. un campo numerico memorizza un numero, mentre un campo di immissione di testo memorizza una stringa), quindi è meglio leggere la documentazione relativa al campo specifico prima di creare un convalidatore.

Nota: solo i campi modificabili accettano i validatori, quindi assicurati di controllare la documentazione specifica del campo.

Valori restituiti

Il valore restituito dal validatore determina la successiva azione del campo. Esistono tre possibilità:

Valore restituito modificato

Un valore modificato o diverso, che diventa il nuovo valore del campo. Questo viene spesso utilizzato per pulire un valore, ad esempio rimuovendo gli spazi finali.

Esempio di convalidatore che modifica:

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

Valore restituito null

Null, il che significa che il valore specificato non è valido. Nella maggior parte dei casi il campo ignorerà il valore inserito. Il comportamento esatto è specificato dalla funzione doValueInvalid_ del campo.

Esempio di convalidatore che restituisce un valore nullo:

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

Valore restituito non definito

Non definito (o nessuna istruzione return) o il valore di input, il che significa che il valore di input deve diventare il nuovo valore del campo. Questi tipi di convalide in genere agiscono come listener di modifiche.

Esempio di validatore di ascoltatori:

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

Tieni presente ancora una volta che il testo visualizzato non riflette necessariamente il valore del campo.

Valore di questo

All'interno di un validatore, this fa riferimento al campo, non al blocco. Se devi accedere al blocco all'interno di un validatore, utilizza la funzione getSourceBlock. Puoi anche utilizzare la funzione bind per impostare il contesto in cui viene chiamato il convalidatore.

Codice di esempio che utilizza 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);
  }
};

Codice di esempio che utilizza 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);
  }
};