Membuat Jenis Diagram

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

Audiens

Halaman ini mengasumsikan bahwa Anda telah membaca halaman Menggunakan Diagram. Tutorial ini juga mengasumsikan bahwa Anda sudah memahami 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 langkah-langkah untuk membuat library diagram:

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

Memilih Namespace

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

Berikut contoh pembuatan objek namespace untuk menyimpan class diagram yang disebut MyTable, serta variabel global 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 di halaman, bukan hanya dalam diagram Anda. Salah satu cara untuk mengatasinya adalah dengan menyertakan seluruh diagram dalam <div> dengan nama class, dan membuat semua aturan CSS Anda 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 harus menerapkan diagram sebagai objek JavaScript yang mengekspos metode standar yang dijelaskan di Bagian Referensi. Dua metode yang diperlukan adalah metode konstruktor dan metode draw(). Anda juga dapat menampilkan metode tambahan yang sesuai untuk diagram Anda kepada pengguna. Ingatlah bahwa lebih mudah digunakan lebih baik.

Konstruktor

Diagram Anda harus menampilkan konstruktor tunggal yang menggunakan satu parameter, elemen DOM tempat Anda akan menggambar diagram. Biasanya, diagram 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 di prototipe class diagram Anda. Metode draw() menerima dua parameter:

1. DataTable yang menyimpan data yang akan 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 ini, diagram mendukung opsi bernama 'showLineNumber' dengan nilai jenis 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 untuk 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 Diagram!

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

Berikut adalah 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 Anda di Halaman Web

Untuk menggunakan diagram sebelumnya, simpan diagram dalam file .js yang dapat diakses dari browser Anda. Lalu, simpan kode berikut, dengan mengubah 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 Acara

Jika 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 Anda (nama, properti yang akan dikirim, dll.). Anda dapat menemukan detailnya di halaman Acara. Anda dapat menampilkan detail peristiwa kepada klien dengan menambahkan properti ke objek peristiwa, atau menampilkan 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.

Dokumentasikan Diagram Anda

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

• Jelaskan semua metode yang Anda dukung. Metode draw() 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 di Halaman Referensi.
• Jelaskan semua opsi yang didukung metode draw() Anda. Ini mencakup nama setiap opsi, jenis nilai yang diharapkan, dan nilai default-nya.
• Jelaskan semua peristiwa yang Anda picu. Ini berarti nama dan properti setiap peristiwa, dan kapan setiap peristiwa dipicu.
• Cantumkan URL library diagram Anda yang harus digunakan dalam pernyataan penyertaan <script> klien, dan berikan URL untuk dokumentasi Anda.
• Berikan nama diagram yang sepenuhnya memenuhi syarat.
• Buat halaman contoh yang menunjukkan cara menggunakan diagram Anda dengan opsi yang didukungnya, peristiwa, dan metode kustomnya.
• Gambarkan dengan jelas kebijakan data diagram Anda. Sebagian besar diagram memproses data dalam browser, tetapi beberapa diagram dapat mengirim data ke server, misalnya untuk membuat gambar diagram atau peta. Jika Anda mengirim data ke server:
  • Menentukan dengan jelas data yang dikirim.
  • Perhatikan berapa lama data akan disimpan di server.
  • Catat entity mana yang akan memiliki akses ke data. Misalnya, Perusahaan XYZ, dll.
  • Tentukan apakah data akan dicatat dalam log dan untuk berapa lama.

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

Mengirimkan Diagram Anda ke Galeri

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

Pemecahan masalah

Jika kode Anda tampaknya tidak berfungsi, berikut beberapa pendekatan yang mungkin membantu Anda menyelesaikan 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 Firebug. Di IE, Anda dapat menggunakan Microsoft Script Debugger.
• Telusuri grup diskusi Google Chart API. Jika tidak dapat menemukan postingan yang menjawab pertanyaan Anda, posting pertanyaan ke grup bersama dengan link ke halaman web yang menunjukkan masalah tersebut.

Pelokalan

Jika Anda menginginkan diagram digunakan oleh orang-orang di berbagai negara, Anda dapat mendesain diagram agar dilokalkan untuk berbagai bahasa dan budaya. 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 mungkin desain UI. Jika Anda memutuskan untuk melokalkan diagram, cantumkan bahasa yang didukung diagram Anda dalam dokumentasi Anda, dan berikan setelan default untuk bahasa yang umum digunakan. Sebaiknya sertakan tombol "ubah bahasa" pada UI diagram, jika Anda salah menggunakan bahasa. Cara umum untuk mendeteksi bahasa browser adalah dengan melihat header HTML Accept-Language.