Menangani Peristiwa

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

Daftar Isi

  1. Ringkasan
  2. Mendaftar dan Menangani Peristiwa
  3. Mengambil Informasi Peristiwa
  4. Peristiwa pilih
  5. Acara 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, kemungkinan dengan data khusus untuk peristiwa tersebut.

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

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

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

Mendaftar dan Menangani Peristiwa

Untuk mendaftarkan pengendali peristiwa, panggil google.visualization.events.addListener() atau addOneTimeListener() dengan nama diagram yang mengekspos 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, seperti yang dijelaskan dalam dokumentasi diagram.

Penting: Jika diagram menampilkan peristiwa siap, Anda harus selalu menunggu hingga 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 pemberitahuan 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 menampilkan informasi dengan dua cara: dengan meneruskan informasi ke 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 adalah 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 mengekspos informasi peristiwa dengan cara ini, lihat peristiwa halaman diagram Tabel.

Informasi peristiwa yang diteruskan ke objek global

Beberapa peristiwa mengubah properti objek global, yang kemudian dapat Anda minta. Contoh umumnya adalah peristiwa "select", yang diaktifkan saat pengguna memilih bagian diagram. Dalam hal ini, kode harus memanggil getSelection() pada diagram untuk mempelajari apa yang dipilih saat ini. Informasi selengkapnya diberikan terkait peristiwa pilih di bawah ini.

// 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 pilihan

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 menampilkan peristiwa "select" didesain dengan spesifikasi berikut:

  • Peristiwa select tidak meneruskan properti atau objek apa pun ke pengendali (pengendali fungsi Anda seharusnya tidak mengharapkan parameter apa pun akan diteruskan ke pengendali).
  • 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 dari item yang dipilih dalam DataTable. (Peristiwa pemilihan menjelaskan data pokok dalam grafik, bukan elemen HTML pada diagram.) Untuk mendapatkan data item yang dipilih, Anda harus memanggil DataTable.getValue() atau getFormattedValue().
    Jika row dan column sudah ditetapkan, 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 mengekspos metode setSelection(selection) untuk mengubah pilihan pada 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 dalam DataTable, dan properti column menentukan indeks kolom yang dipilih di DataTable. Saat metode ini dipanggil, diagram akan menunjukkan secara visual pilihan baru tersebut. Implementasi setSelection() tidak boleh memicu peristiwa 'select'.
    Jika row dan column sudah ditetapkan, 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 dapat mengabaikan bagian yang dipilih. 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 'select', dan beberapa diagram mungkin hanya mendukung seluruh pilihan baris atau seluruh pilihan kolom. Dokumentasi setiap diagram menentukan peristiwa dan metode yang didukungnya.
  • Multiselection ditangani secara berbeda dalam diagram yang berbeda (beberapa bahkan tidak mengizinkannya).
  • Untuk membaca data yang dipilih, Anda harus memanggil DataTable.getValue() di pengendali; cara termudah untuk mengaktifkannya adalah dengan membuat objek DataTable menjadi global.

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

Perlu diperhatikan bahwa diagram tabel hanya mengaktifkan peristiwa pemilihan baris. Namun, kode ini 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);
}

Peristiwa yang siap

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

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

  • Peristiwa ready tidak meneruskan properti apa pun ke pengendali (pengendali fungsi Anda seharusnya tidak mengharapkan parameter apa pun diteruskan ke pengendali).
  • Diagram harus mengaktifkan peristiwa yang sudah siap setelah diagram siap untuk berinteraksi. Jika penggambaran diagram bersifat asinkron, peristiwa harus diaktifkan saat metode interaksi benar-benar dapat dipanggil, bukan hanya saat metode draw berakhir.
  • Menambahkan pemroses ke peristiwa ini harus dilakukan sebelum memanggil metode draw(), karena jika tidak, peristiwa 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 baik.

Konvensinya adalah bahwa diagram yang tidak mengaktifkan peristiwa "siap" siap untuk berinteraksi segera setelah metode draw berakhir dan menampilkan kontrol kepada pengguna. Jika diagram memang mengaktifkan peristiwa siap, Anda harus menunggu hingga peristiwa ditampilkan sebelum memanggil metode untuk peristiwa tersebut, seperti yang ditunjukkan di sini:

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

Sintaksis Pengendali Peristiwa Siap

function myReadyHandler(){...}

Pengendali peristiwa siap tidak meneruskan parameter apa pun.

Peristiwa error

Diagram harus menampilkan peristiwa error saat menemukan semacam error, agar Anda dapat menanganinya dengan baik. Pengendali peristiwa diberi deskripsi error, serta properti peristiwa kustom khusus untuk setiap diagram. Anda harus berlangganan ke peristiwa ini segera setelah membuat instance diagram untuk menangkap error yang mungkin terjadi di langkah berikutnya.

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

Sintaksis Pengendali Peristiwa Error

function myErrorHandler(err){...}

Pengendali peristiwa error harus diteruskan objek dengan anggota berikut:

  • id [Wajib] - ID elemen DOM yang berisi diagram, atau pesan error yang ditampilkan sebagai ganti diagram jika tidak dapat dirender.
  • message [Wajib] - String pesan singkat yang menjelaskan error.
  • detailedMessage [Opsional] - Penjelasan mendetail terkait error.
  • options [Opsional]- Objek yang berisi parameter kustom yang sesuai untuk error dan jenis diagram ini.

Contoh Penanganan Peristiwa

Contoh berikut menunjukkan getSelection() dan setSelection(). Metode 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 penerapan pilihan: