Membuat Jenis Diagram

Halaman ini menjelaskan cara mengembangkan jenis diagram Anda sendiri dan menyediakannya untuk pengguna.

Penonton

Halaman ini mengasumsikan bahwa Anda telah membaca halaman Menggunakan Diagram. Ini juga mengasumsikan bahwa Anda sudah terbiasa dengan JavaScript dan pemrograman berorientasi objek. Ada banyak tutorial JavaScript yang tersedia di Web.

Membuat Diagram

Diagram ditampilkan kepada pengguna melalui library JavaScript yang Anda buat. Berikut adalah langkah-langkah untuk membuat library diagram:

1. Pilih namespace untuk kode Anda. Halaman lain akan menghosting kode; Anda harus mencoba menghindari konflik penamaan.
2. Terapkan objek diagram. Terapkan objek JavaScript yang mengekspos hal berikut:
   • Konstruktor,
   • Metode draw() untuk menggambar objek Anda di dalam elemen DOM yang diteruskan ke konstruktor,
   • Metode standar opsional lainnya yang dapat digunakan klien, seperti getSelection(), dan
   • Metode kustom apa pun yang ingin Anda tampilkan kepada klien.
3. [Opsional] Implementasikan semua peristiwa yang ingin diaktifkan agar dapat ditangkap klien.
4. Tulis dokumentasi untuk diagram Anda. Jika Anda tidak mendokumentasikannya, orang-orang mungkin tidak akan dapat menyematkannya.
5. Posting diagram Anda di Galeri Diagram.

Memilih Namespace

Diagram Anda dapat disematkan pada halaman yang menghosting diagram lain atau JavaScript lain yang tidak terkait. Agar tidak terjadi konflik penamaan dengan nama class CSS atau kode lainnya, Anda harus memilih namespace unik untuk kode diagram. Pilihan bagus untuk namespace adalah URL yang akan Anda gunakan untuk menghosting skrip (tanpa WWW dan ekstensi apa pun). Jadi, misalnya, jika diagram akan diposting di www.example.com, Anda akan menggunakan example sebagai namespace unik. Anda dapat menambahkan akhiran tambahan yang dipisahkan oleh karakter . marka, untuk mengelompokkan diagram lebih lanjut (semua diagram Google memiliki namespace google.visualization). Gunakan objek namespace Anda untuk menyimpan objek diagram, serta variabel global yang mungkin diperlukan.

Berikut adalah contoh pembuatan objek namespace untuk menyimpan class diagram yang disebut MyTable, serta variabel global apa pun yang diperlukan:

// Namespace, implemented as a global variable.
var example = {};

// MyTable class constructor.
example.MyTable = function(container) {
  // ...
}

// MyTable.draw() method.
example.MyTable.prototype.draw = function(data, options) {
  // ...
}

Menghindari Konflik CSS

Jika Anda menggunakan CSS, pastikan untuk tidak menulis aturan CSS yang dapat memengaruhi diagram lain di halaman. Misalnya, aturan seperti td {color: blue;} sangat tidak disarankan, karena akan memengaruhi elemen <td> lainnya pada halaman, tidak hanya dalam diagram. Salah satu cara untuk mengatasi hal ini adalah dengan menyertakan seluruh diagram di <div> dengan nama class, dan semua aturan CSS hanya berlaku untuk elemen yang merupakan turunan dari elemen dengan nama class tersebut. Misalnya, aturan CSS berikut hanya akan memengaruhi elemen <td> yang memiliki elemen dengan nama class "example" sebagai ancestor.

td.example {color: blue;}

Kemudian, Anda dapat menggabungkan diagram dalam <div> dengan :

<div class="example">
  ...
</div>

Menerapkan Diagram Anda

Anda harus menerapkan diagram sebagai objek JavaScript yang mengekspos metode standar yang dijelaskan di Bagian Referensi. Dua metode yang diperlukan adalah metode konstruktor dan draw(). Anda juga dapat mengekspos metode tambahan apa pun kepada pengguna yang sesuai untuk diagram Anda. Ingatlah bahwa lebih mudah digunakan lebih baik.

Konstruktor

Diagram Anda harus mengekspos satu konstruktor yang menggunakan satu parameter, elemen DOM tempat Anda akan menggambar diagram. Biasanya, diagram akan menyimpan salinan lokal elemen ini dalam konstruktor untuk digunakan nanti:

function example.MyTable(container) {
  this.container = container
}

Metode draw()

Class diagram Anda harus memiliki metode draw() yang ditentukan dalam prototipe class diagram Anda. Metode draw() menerima dua parameter:

1. DataTable yang menyimpan data untuk ditampilkan.
2. Peta opsional opsi nama/nilai untuk diagram Anda. Nama dan jenis nilai opsi ditentukan oleh Anda untuk diagram tertentu. Misalnya, dalam contoh Hello Chart di bawah, diagram mendukung opsi bernama 'showLineNumber' dengan nilai berjenis Boolean. Anda harus mendukung nilai default untuk setiap opsi, jika pengguna tidak meneruskan nilai untuk opsi tertentu. Parameter ini bersifat opsional, jadi Anda juga harus siap menggunakan semua nilai default jika pengguna tidak meneruskan parameter ini (informasi selengkapnya).

example.MyTable.prototype.draw = function(data, options) {
  // Process data and options and render output into the container element.
  ...
}

Halo Chart!

Berikut adalah diagram sederhana yang menampilkan data DataTable sebagai tabel HTML:

Dan berikut ini kode penerapannya:

// Declare a unique namespace.
var example = {};

// Class constructor. Parameter container is a DOM elementon the client that
// that will contain the chart.
example.MyTable = function(container) {
  this.containerElement = container;
}

// Main drawing logic.
// Parameters:
//   data is data to display, type google.visualization.DataTable.
//   options is a name/value map of options. Our example takes one option.
example.MyTable.prototype.draw = function(data, options) {

  // Create an HTML table
  var showLineNumber = options.showLineNumber; // Boolean configuration option.

  var html = [];
  html.push('<table border="1">');

  // Header row
  html.push('<tr>');
  if (showLineNumber) {
    html.push('<th>Seq</th>');
  }
  for (var col = 0; col < data.getNumberOfColumns(); col++) {
    html.push('<th>' + this.escapeHtml(data.getColumnLabel(col)) + '</th>');
  }
  html.push('</tr>');

  for (var row = 0; row < data.getNumberOfRows(); row++) {
    html.push('<tr>');
    if (showLineNumber) {
      html.push('<td align="right">', (row + 1), '</td>');
    }

    for (var col = 0; col < data.getNumberOfColumns(); col++) {
      html.push(data.getColumnType(col) == 'number' ? '<td align="right">' : '<td>');
      html.push(this.escapeHtml(data.getFormattedValue(row, col)));
      html.push('</td>');
    }
    html.push('</tr>');
  }
  html.push('</table>');

  this.containerElement.innerHTML = html.join('');
}

// Utility function to escape HTML special characters
example.MyTable.prototype.escapeHtml = function(text) {
  if (text == null)
    return '';
  return text.replace(/&/g, '&').replace(/</g, '<')
      .replace(/>/g, '>').replace(/"/g, '"');
}

Menyertakan Diagram di Halaman

Untuk menggunakan diagram sebelumnya, simpan diagram di file .js yang dapat diakses dari browser Anda. Lalu, simpan kode berikut, dan ubah parameter sumber <script> agar mengarah ke file JavaScript Anda:

<html>
  <head>
    <script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
    <script type="text/javascript" src="mytablevis.js"></script>
    <script type="text/javascript">
      google.charts.load("current");

      // Set callback to run when API is loaded
      google.charts.setOnLoadCallback(drawVisualization);

      // Called when the Chart API is loaded.
      function drawVisualization() {

        // Create and populate a data table.
        var data = new google.visualization.DataTable();
        data.addColumn('string', 'Task');
        data.addColumn('number', 'Daily Hours');
        data.addRows(5);
        data.setCell(0, 0, 'Work');
        data.setCell(0, 1, 11);
        // Add more data rows and cells here

        // Instantiate our table object.
        var vis = new example.MyTable(document.getElementById('mydiv'));

        // Draw our table with the data we created locally.
        vis.draw(data, {showLineNumber: true});
       }
   </script>
  <title>MyTable example page</title></head>
  <body>
    <div id="mydiv"></div>
    <p>This page demonstrates hosting a table visualization.</p>
  </body>
</html>

 

Menerapkan Peristiwa

Jika Anda ingin diagram mengaktifkan peristiwa yang berguna (misalnya, peristiwa timer, atau peristiwa yang dimulai pengguna seperti klik), Anda harus memanggil fungsi google.visualization.events.trigger dengan detail peristiwa (nama, properti yang akan dikirim, dll.). Anda dapat menemukan detailnya di halaman Peristiwa. Anda dapat menampilkan detail peristiwa ke klien dengan menambahkan properti ke objek peristiwa, atau mengekspos metode get...() dari beberapa jenis pada diagram, dan klien dapat memanggil metode tersebut untuk mendapatkan detail peristiwa. Dalam kedua kasus tersebut, dokumentasikan metode atau properti peristiwa Anda dengan baik.

Mendokumentasikan Diagram Anda

Jika tidak mendokumentasikan diagram dengan benar, Anda mungkin tidak akan mendapatkan banyak pengguna. Pastikan untuk mendokumentasikan hal berikut:

• Jelaskan semua metode yang Anda dukung. Metode draw() bersifat umum untuk semua diagram, tetapi setiap diagram dapat mendukung metode tambahannya sendiri. (Anda mungkin tidak perlu mendokumentasikan konstruktor, kecuali jika memiliki perilaku non-standar.) Anda dapat menemukan daftar metode yang diharapkan pada Halaman Referensi.
• Jelaskan semua opsi yang didukung metode draw() Anda. Ini mencakup nama setiap opsi, jenis nilai yang diharapkan, dan nilai defaultnya.
• Jelaskan semua peristiwa yang Anda picu. Artinya, nama dan properti setiap peristiwa, dan kapan setiap peristiwa dipicu.
• Cantumkan URL library diagram yang harus digunakan dalam pernyataan penyertaan <script> klien, dan berikan URL untuk dokumentasi Anda.
• Berikan nama yang sepenuhnya memenuhi syarat untuk diagram Anda.
• Buat halaman contoh yang menunjukkan cara menggunakan diagram dengan opsi yang didukung, peristiwanya, dan metode kustomnya.
• Jelaskan kebijakan data diagram Anda dengan jelas. Sebagian besar diagram memproses data dalam browser, tetapi beberapa diagram mungkin mengirim data ke server, misalnya untuk membuat gambar diagram atau peta. Jika Anda mengirim data ke server:
  • Tentukan dengan jelas data yang dikirim.
  • Perhatikan berapa lama data akan disimpan di server.
  • Dokumentasikan entity mana yang akan memiliki akses ke data. Misalnya, Perusahaan XYZ, dll.
  • Tentukan apakah data akan dicatat dan berapa lama.

Dokumentasi Anda akan dihosting di tempat yang sama seperti kode diagram (lihat Mengirim Diagram ke Galeri di bawah).

Mengirimkan Diagram ke Galeri

Setelah menulis diagram, kirimkan diagram untuk mempostingnya di bagian "Diagram Tambahan" galeri kami. Mengirimkan diagram berarti Anda harus menandatangani perjanjian dengan kami yang menyetujui untuk tidak membuat software berbahaya atau menyalahgunakan data pengguna. Galeri hanyalah daftar pointer ke diagram yang telah kami buat, atau yang telah kami tinjau; Anda dapat memilih untuk menghosting library dan dokumentasi JavaScript aktual di situs Anda sendiri, atau meminta Google menghosting library dan dokumentasi untuk Anda. Tentukan apakah Anda ingin kami menghosting diagram saat mempostingnya ke galeri.

Pemecahan masalah

Jika kode Anda tampaknya tidak berfungsi, berikut adalah beberapa pendekatan yang dapat membantu Anda memecahkan masalah:

• Cari kesalahan ketik. Ingatlah, JavaScript adalah bahasa yang membedakan huruf besar dan kecil.
• Menggunakan debugger JavaScript. Di Firefox, Anda dapat menggunakan konsol JavaScript, Venkman Debugger, atau add-on ExoPlayer. Di IE, Anda dapat menggunakan Microsoft Script Debugger.
• Telusuri grup diskusi Google Chart API. Jika Anda tidak dapat menemukan postingan yang menjawab pertanyaan Anda, posting pertanyaan Anda ke grup bersama dengan link ke halaman web yang menunjukkan masalah tersebut.

Pelokalan

Jika Anda memperkirakan diagram akan digunakan oleh orang di berbagai negara, sebaiknya desain diagram Anda agar dilokalkan untuk bahasa dan budaya yang berbeda. Pelokalan yang paling dasar adalah menerjemahkan string teks standar di UI sesuai dengan setelan browser pengguna. Bentuk pelokalan yang lebih canggih adalah dengan mengubah format angka bergantung pada pelokalan, atau bahkan desain UI. Jika Anda memutuskan untuk melokalkan diagram, cantumkan bahasa yang didukung diagram dalam dokumentasi, dan berikan setelan default bahasa yang biasa digunakan. Penting juga untuk menyertakan tombol "ubah bahasa" pada UI diagram, jika Anda salah memahami bahasa. Cara umum untuk mendeteksi bahasa browser adalah dengan melihat header HTML Accept-Language.