Menangani Kejadian

Halaman ini menjelaskan cara memproses dan menangani peristiwa yang diaktifkan oleh diagram.

Daftar Isi

  1. Ringkasan
  2. Mendaftarkan dan Menangani Peristiwa
  3. Mengambil Informasi Peristiwa
  4. Peristiwa select
  5. Peristiwa siap
  6. Peristiwa error
  7. Contoh Penanganan Peristiwa

Ringkasan

Diagram Google dapat mengaktifkan peristiwa yang dapat Anda proses. Peristiwa dapat dipicu oleh tindakan pengguna, seperti saat pengguna mengklik diagram. Anda dapat mendaftarkan metode JavaScript untuk dipanggil setiap kali peristiwa tertentu diaktifkan, mungkin dengan data khusus untuk peristiwa tersebut.

Setiap diagram menentukan peristiwanya sendiri, dan dokumentasi untuk diagram tersebut harus menjelaskan kapan setiap peristiwa diaktifkan, artinya, dan cara mendapatkan kembali informasi apa pun yang terkait dengan peristiwa tersebut. Halaman ini menjelaskan cara mendaftar untuk menerima peristiwa dari diagram, serta cara menanganinya.

Ada satu peristiwa yang harus diaktifkan oleh diagram yang dapat dipilih: peristiwa pilih. Namun, perilaku dan makna peristiwa ini ditentukan oleh setiap diagram.

Penting untuk diperhatikan bahwa peristiwa diagram terpisah dan berbeda dari peristiwa DOM standar.

Mendaftarkan dan Menangani Peristiwa

Untuk mendaftarkan pengendali peristiwa, panggil google.visualization.events.addListener() atau addOneTimeListener() dengan nama diagram yang menampilkan peristiwa, nama string peristiwa yang akan diproses, dan nama fungsi yang akan dipanggil saat peristiwa tersebut diaktifkan. Fungsi Anda harus menerima satu parameter yang merupakan peristiwa yang diaktifkan. Peristiwa ini dapat memiliki informasi kustom tentang peristiwa tersebut, seperti yang dijelaskan dalam dokumentasi diagram.

Penting: Jika diagram menampilkan peristiwa siap, Anda harus selalu menunggu peristiwa tersebut diaktifkan sebelum mencoba mengirim metode atau menerima peristiwa dari diagram. Diagram ini mungkin berfungsi sebelum menampilkan peristiwa siap, tetapi perilaku tersebut tidak dijamin.

Cuplikan kode berikut menampilkan kotak peringatan setiap kali pengguna mengklik baris tabel:

// Create a table chart on your page.
var table = new google.visualization.Table(document.getElementById('table_div'));
table.draw(data, options);

// Every time the table fires the "select" event, it should call your
// selectHandler() function.
google.visualization.events.addListener(table, 'select', selectHandler);

function selectHandler(e) {
  alert('A table row was selected');
}

Perhatikan bahwa ini hanya akan mendaftar untuk memproses peristiwa untuk objek tabel spesifik ini; Anda hanya dapat mendaftar untuk menerima peristiwa dari objek tertentu.

Anda juga dapat meneruskan definisi fungsi, seperti yang ditunjukkan di sini:

// Pass in a function definition.
google.visualization.events.addListener(orgchart, 'select', function() {
  table.setSelection(orgchart.getSelection());
});

Mengambil Informasi Peristiwa

Peristiwa umumnya mengekspos informasi dengan dua cara: dengan meneruskan informasi ke dalam fungsi pengendali sebagai parameter; atau dengan menambahkan informasi ke objek global. Jika dan bagaimana peristiwa mengekspos informasi harus dijelaskan dalam dokumentasi untuk diagram tersebut. Berikut cara mengambil kedua jenis informasi tersebut:

Informasi peristiwa yang diteruskan ke pengendali Anda

Jika diagram meneruskan data sebagai parameter ke fungsi penanganan, Anda akan mengambilnya seperti yang ditunjukkan di sini:

// google.visualization.table exposes a 'page' event.
google.visualization.events.addListener(table, 'page', myPageEventHandler);
...
function myPageEventHandler(e) {
  alert('The user is navigating to page ' + e['page']);
}

Parameter yang diteruskan ke pengendali Anda akan memiliki properti yang harus didokumentasikan untuk diagram. Untuk contoh diagram yang menampilkan informasi peristiwa dengan cara ini, lihat peristiwa halaman diagram Tabel.

Informasi peristiwa yang diteruskan ke objek global

Namun, beberapa peristiwa mengubah properti objek global, yang kemudian dapat Anda minta. Contoh umum dari hal ini adalah peristiwa "select", yang dipicu saat pengguna memilih bagian dari diagram. Dalam hal ini, kode harus memanggil getSelection() pada diagram untuk mempelajari pilihan saat ini. Informasi selengkapnya diberikan pada peristiwa pilih di bawah.

// orgChart is my global orgchart chart variable.
google.visualization.events.addListener(orgChart, 'select', selectHandler);
...
// Notice that e is not used or needed.
function selectHandler(e) {
  alert('The user selected' + orgChart.getSelection().length + ' items.');

Peristiwa select

Seperti yang disebutkan sebelumnya, setiap diagram yang dapat dipilih harus mengaktifkan peristiwa "select" yang berfungsi dengan cara standar sehingga Anda dapat mengambil nilai item yang dipilih dalam diagram. (Namun, tidak ada persyaratan mutlak bahwa diagram berperilaku seperti ini; periksa dokumentasi untuk diagram Anda).

Secara umum, diagram yang mengekspos peristiwa "select" didesain dengan spesifikasi berikut:

  • Peristiwa yang dipilih tidak meneruskan properti atau objek apa pun ke pengendali (pengendali fungsi Anda tidak boleh meneruskan parameter apa pun).
  • Diagram harus menampilkan metode getSelection(), yang menampilkan array objek yang menjelaskan elemen data yang dipilih. Objek ini memiliki properti row dan column. row dan column adalah indeks baris dan kolom item yang dipilih di DataTable. (Peristiwa pemilihan menjelaskan data pokok dalam grafik, bukan elemen HTML dalam diagram.) Untuk mendapatkan data item yang dipilih, Anda harus memanggil DataTable.getValue() atau getFormattedValue().
    Jika row dan column ditentukan, elemen yang dipilih adalah sel. Jika hanya row yang ditentukan, elemen yang dipilih adalah baris. Jika hanya column yang ditentukan, elemen yang dipilih adalah kolom.
  • Diagram harus menampilkan metode setSelection(selection) untuk mengubah pilihan dalam tabel pokok dan memilih data yang sesuai dalam diagram. Parameter selection yang merupakan array yang mirip dengan array getSelection(), dengan setiap elemen adalah objek dengan properti row dan column. Properti row menentukan indeks baris yang dipilih di DataTable, dan properti column menentukan indeks kolom yang dipilih di DataTable. Jika metode ini dipanggil, diagram akan secara visual menunjukkan pilihan baru tersebut. Implementasi setSelection() tidak boleh memicu peristiwa 'select'.
    Jika row dan column ditentukan, elemen yang dipilih adalah sel. Jika hanya row yang ditentukan, elemen yang dipilih adalah baris. Jika hanya column yang ditentukan, elemen yang dipilih adalah kolom.

Beberapa peringatan:

  • Diagram mungkin mengabaikan bagian dari pilihan. Misalnya, tabel yang hanya dapat menampilkan baris yang dipilih dapat mengabaikan elemen sel atau kolom dalam implementasi setSelection-nya.)
  • Beberapa diagram mungkin tidak memicu peristiwa 'pilih', dan beberapa diagram mungkin hanya mendukung seluruh pemilihan baris atau seluruh pemilihan kolom. Dokumentasi setiap diagram menentukan peristiwa dan metode yang didukungnya.
  • Multi-pilihan ditangani secara berbeda dalam diagram yang berbeda (beberapa di antaranya bahkan tidak mengizinkannya).
  • Untuk membaca data yang dipilih, Anda harus memanggil DataTable.getValue() di pengendali; cara termudah untuk mengaktifkannya adalah menjadikan objek DataTable bersifat global.

Contoh berikut memunculkan kotak peringatan dengan elemen tabel yang dipilih, saat elemen diagram tabel dipilih:

Perhatikan bahwa diagram tabel hanya mengaktifkan peristiwa pemilihan baris; tetapi, kodenya bersifat umum, dan dapat digunakan untuk peristiwa pemilihan baris, kolom, dan sel.

Berikut adalah kode pengendali untuk contoh tersebut:

// Create our table.
var table = new google.visualization.Table(document.getElementById('table_div'));
table.draw(data, options);

// Add our selection handler.
google.visualization.events.addListener(table, 'select', selectHandler);

// The selection handler.
// Loop through all items in the selection and concatenate
// a single message from all of them.
function selectHandler() {
  var selection = table.getSelection();
  var message = '';
  for (var i = 0; i < selection.length; i++) {
    var item = selection[i];
    if (item.row != null && item.column != null) {
      var str = data.getFormattedValue(item.row, item.column);
      message += '{row:' + item.row + ',column:' + item.column + '} = ' + str + '\n';
    } else if (item.row != null) {
      var str = data.getFormattedValue(item.row, 0);
      message += '{row:' + item.row + ', column:none}; value (col 0) = ' + str + '\n';
    } else if (item.column != null) {
      var str = data.getFormattedValue(0, item.column);
      message += '{row:none, column:' + item.column + '}; value (row 0) = ' + str + '\n';
    }
  }
  if (message == '') {
    message = 'nothing';
  }
  alert('You selected ' + message);
}

Acara siap

Sebagian besar diagram dirender secara asinkron; semua diagram Google menampilkan peristiwa siap setelah Anda memanggil draw() di dalamnya, yang menunjukkan bahwa diagram tersebut dirender, dan siap menampilkan properti atau menangani panggilan metode lebih lanjut. Anda harus selalu memproses peristiwa siap sebelum mencoba memanggil metode di dalamnya setelah memanggil draw().

Secara umum, diagram yang mengekspos peristiwa "siap" didesain dengan spesifikasi berikut:

  • Peristiwa siap tidak meneruskan properti apa pun ke pengendali (pengendali fungsi Anda tidak boleh meneruskan parameter apa pun).
  • Diagram harus mengaktifkan peristiwa siap setelah diagram siap berinteraksi. Jika gambar diagram bersifat asinkron, penting agar peristiwa tersebut diaktifkan saat metode interaksi benar-benar dapat dipanggil, dan bukan hanya saat metode draw berakhir.
  • Menambahkan pemroses ke peristiwa ini harus dilakukan sebelum memanggil metode draw(), karena peristiwa tersebut mungkin akan diaktifkan sebelum pemroses disiapkan dan Anda tidak akan menangkapnya.
  • Dengan memanggil metode interaksi sebelum peristiwa siap diaktifkan, Anda berisiko bahwa metode ini tidak akan berfungsi dengan benar.

Konvensinya adalah diagram yang tidak mengaktifkan peristiwa "ready" siap untuk interaksi segera setelah metode draw berakhir dan menampilkan kontrol kepada pengguna. Jika diagram memang mengaktifkan peristiwa siap, Anda harus menunggunya ditampilkan sebelum memanggil metode di dalamnya, seperti yang ditunjukkan di sini:

google.visualization.events.addListener(tableChart, 'ready', myReadyHandler);

Sintaksis Pengendali Peristiwa Siap

function myReadyHandler(){...}

Pengendali peristiwa siap tidak menerima parameter apa pun.

Peristiwa error

Diagram harus melemparkan peristiwa error saat menemukan error tertentu agar Anda dapat menanganinya dengan baik. Pengendali peristiwa mendapatkan deskripsi error, serta properti peristiwa kustom yang spesifik untuk setiap diagram. Anda harus berlangganan peristiwa ini tepat setelah instance diagram untuk menangkap error yang mungkin terjadi di langkah berikutnya.

Anda dapat menggunakan fungsi bantuan goog.visualization.errors untuk membantu menampilkan error apa pun dengan baik kepada pengguna.

Sintaksis Pengendali Peristiwa Error

function myErrorHandler(err){...}

Pengendali peristiwa error harus meneruskan objek dengan anggota berikut:

  • id [Wajib] - ID elemen DOM yang berisi diagram, atau pesan error yang ditampilkan, bukan diagram, jika tidak dapat dirender.
  • pesan [Wajib] - String pesan singkat yang menjelaskan error.
  • mendetailMessage [Opsional] - Penjelasan mendetail tentang error tersebut.
  • options [Opsional]- Objek yang berisi parameter kustom yang sesuai dengan error dan jenis diagram ini.

Contoh Penanganan Peristiwa

Contoh berikut menunjukkan getSelection() dan setSelection(). Tindakan ini menyinkronkan pilihan antara dua diagram yang menggunakan tabel data yang sama. Klik salah satu diagram untuk menyinkronkan pilihan di diagram lainnya.

// Create our two charts.
var table = new google.visualization.Table(document.getElementById('table_div'));
table.draw(data, {});

var orgchart = new google.visualization.OrgChart(document.getElementById('org_div'));
orgchart.draw(data, {});

// When the table is selected, update the orgchart.
google.visualization.events.addListener(table, 'select', function() {
  orgchart.setSelection(table.getSelection());
});

// When the orgchart is selected, update the table chart.
google.visualization.events.addListener(orgchart, 'select', function() {
  table.setSelection(orgchart.getSelection());
});

Klik diagram di bawah pada baris tabel atau elemen diagram untuk melihat cara kerja pemilihan: