Validator

Validator adalah fungsi yang mengambil nilai baru kolom, lalu bertindak berdasarkan nilai tersebut. Ini adalah cara mudah untuk menyesuaikan kolom. Dengan peristiwa ini, Anda dapat memicu fungsi saat nilai kolom berubah, mengubah input, atau membatasi nilai yang dapat diterima.

Beberapa contoh umum:

  • Membatasi kolom teks agar hanya menerima huruf.
  • Mewajibkan kolom teks tidak kosong.
  • Memerlukan tanggal di masa mendatang.
  • Mengubah bentuk blok berdasarkan dropdown.

Jenis validator

Validator dijalankan pada waktu yang berbeda-beda, bergantung pada jenis validatornya.

Pemvalidasi class adalah bagian dari definisi class jenis kolom, dan biasanya digunakan untuk membatasi jenis nilai yang diizinkan oleh kolom (misalnya, kolom angka hanya menerima karakter numerik). Validator class dijalankan pada semua nilai yang diteruskan ke kolom (termasuk nilai yang diteruskan ke konstruktor).

Untuk informasi selengkapnya tentang validator class, lihat bagian Menerapkan validator class dalam Membuat Kolom Kustom.

Pemvalidasi lokal ditentukan pada saat pembuatan kolom. Validator lokal berjalan pada semua nilai yang diteruskan ke kolom kecuali nilai yang diteruskan ke konstruktor. Artinya, aplikasi tersebut berjalan di:

  • Nilai yang terdapat dalam XML.
  • Nilai yang diteruskan ke setValue.
  • Nilai yang diteruskan ke setFieldValue.
  • Nilai yang diubah oleh pengguna.

Validator class dijalankan sebelum validator lokal karena bertindak seperti penjaga gerbang. Fungsi ini memastikan bahwa nilainya adalah jenis yang benar sebelum meneruskannya.

Untuk informasi selengkapnya tentang urutan validasi nilai, dan nilai secara umum, lihat Nilai.

Mendaftarkan validator lokal

Validator lokal dapat didaftarkan dengan dua cara:

  • Ditambahkan langsung di konstruktor kolom.
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);
  }
};

Salah satu metode di atas dapat digabungkan dalam ekstensi, untuk mendukung format JSON.

Nilai kolom mungkin sangat berbeda bergantung pada jenis kolom yang divalidasi (misalnya, kolom angka akan menyimpan angka, sedangkan kolom input teks akan menyimpan string), jadi sebaiknya baca dokumentasi untuk kolom khusus Anda sebelum membuat validator.

Nilai yang ditampilkan

Nilai yang ditampilkan validator menentukan tindakan kolom berikutnya. Ada tiga kemungkinan:

Nilai Hasil yang Diubah

Nilai yang diubah atau berbeda, yang kemudian menjadi nilai baru kolom. Ini sering digunakan untuk membersihkan nilai, seperti dengan menghapus spasi kosong di akhir.

Contoh Validator Pengubah:

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

Kolom input teks dengan validator pengubah

Nilai Hasil Null

Null, yang berarti nilai yang diberikan tidak valid. Pada umumnya, kolom akan mengabaikan nilai input. Perilaku yang tepat ditentukan oleh fungsi doValueInvalid_ kolom.

Contoh Validator Nulling:

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

Kolom input teks dengan validator nulling

Nilai Hasil yang Tidak Ditetapkan

Tidak ditentukan (atau tidak ada pernyataan return) atau nilai input, yang berarti bahwa nilai input harus menjadi nilai baru kolom. Jenis validator ini umumnya bertindak sebagai pemroses perubahan.

Contoh Validator Pemroses:

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

Perhatikan sekali lagi bagaimana teks tampilan tidak selalu mencerminkan nilai kolom.

Nilai ini

Di dalam validator, this mengacu pada kolom, bukan blok. Jika Anda perlu mengakses blok di dalam validator, gunakan fungsi getSourceBlock. Anda juga dapat menggunakan fungsi bind untuk menetapkan konteks tempat validator dipanggil.

Contoh kode yang menggunakan 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);
  }
};

Contoh kode menggunakan 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);
  }
};