Validatori

Un validatore è una funzione che accetta il nuovo valore dei campi e poi agisce su di esso. Sono un modo semplice per personalizzare un campo. Consentono di attivare funzionalità quando il valore di un campo cambia, modificare l'input o 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.
• Richiede che una data sia futura.
• Modifica della forma di un blocco in base a un menu a discesa.

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

Tipi di validatori

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

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

Per saperne di più sui validator di classe, consulta la sezione Implementazione di un validator di classe in 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 costruttore. Ciò significa che funzionano su:

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

I validatori di classe vengono eseguiti prima dei validatori locali perché fungono da gatekeeper. Si assicurano che il valore sia del tipo corretto prima di passarlo.

Per ulteriori informazioni sulla sequenza di convalida dei valori e sui valori in generale, vedi 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ò variare 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);
  }
};

Uno dei metodi precedenti può essere racchiuso in un'estensione per supportare il formato JSON.

Il valore del campo può variare notevolmente a seconda del tipo di campo convalidato (ad es. un campo numerico memorizzerà un numero, mentre un campo di input di testo memorizzerà una stringa), pertanto è consigliabile 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 del campo specifico.

Valori restituiti

Il valore restituito del validatore determina l'azione successiva del campo. Ci sono tre possibilità:

Modified Return Value (Valore restituito modificato)

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

Esempio di un validatore di modifica:

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

Valore restituito nullo

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

Esempio di un validatore di annullamento:

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

Undefined Return Value

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 validatori in genere fungono da listener di modifiche.

Esempio di un validatore di listener:

// 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 si 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 validatore.

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