Membuat Komponen Khusus

Ringkasan

Embed API dilengkapi dengan beberapa komponen bawaan dan juga mempermudah Anda untuk membuatnya sendiri. Dokumen ini menjelaskan cara membuat komponen kustom baru dan cara menyertakan komponen pihak ketiga dalam aplikasi Anda.

Membuat komponen kustom

Komponen Custom Embed API dibuat dengan memanggil gapi.analytics.createComponent dan meneruskan nama komponen dan objek metode.

Nama yang diteruskan ke createComponent akan menjadi nama fungsi konstruktor komponen, dan akan disimpan di gapi.analytics.ext. Objek metode harus berisi fungsi atau properti yang ingin ditambahkan ke prototipe komponen.

gapi.analytics.createComponent('MyComponent', {
  execute: function() {
    alert('I have been executed!');
  }
});

Setelah dibuat, komponen dapat digunakan dengan memanggil operator new dengan konstruktor komponen.

// Create a new instance of MyComponent.
var myComponentInstance = new gapi.analytics.ext.MyComponent();

// Invoke the `execute` method.
myComponentInstance.execute() // Alerts "I have been executed!"

Metode inisialisasi

Meneruskan objek metode ke createComponent akan memberi Anda akses ke prototipe komponen Anda, tetapi tidak memberi Anda akses ke konstruktor komponen Anda.

Untuk mengatasi masalah ini, saat komponen Embed API baru dibuat, komponen tersebut akan otomatis mencari keberadaan metode yang disebut initialize. Jika ditemukan, Callback akan dipanggil dengan arguments yang sama yang diteruskan ke konstruktor. Semua logika yang biasanya Anda tempatkan dalam konstruktor harus ditempatkan dalam metode inisialisasi.

Berikut adalah contoh yang menetapkan beberapa properti default saat instance MyComponent baru dibuat.

gapi.analytics.createComponent('MyComponent', {
  initialize: function(options) {
    this.name = options.name;
    this.isRendered = false;
  }
});

var myComponentInstance = new gapi.analytics.ext.MyComponent({name: 'John'});
alert(myComponentInstance.name); // Alerts "John"
alert(myComponentInstance.isRendered); // Alerts false

Metode turunan

Komponen yang dibuat dengan metode createComponent akan otomatis mewarisi metode dasar yang digunakan bersama oleh semua komponen bawaan (get, set, on, once, off, emit). Hal ini memastikan semua komponen bekerja dengan cara yang konsisten dan dapat diprediksi.

Misalnya, jika komponen Anda mewajibkan pengguna diberi otorisasi, Anda dapat melakukannya menggunakan metode penanganan peristiwa yang diwarisi.

gapi.analytics.createComponent('MyComponent', {
  initialize: function() {
    this.isRendered = false;
  },
  execute: function() {
    if (gapi.analytics.auth.isAuthorized()) {
      this.render();
    }
    else {
      gapi.analytics.auth.once('success', this.render.bind(this));
    }
  },
  render: function() {
    if (this.isRendered == false) {

      // Render this component...

      this.isRendered = true;
      this.emit('render');
    }
  }
});

var myComponentInstance = new gapi.analytics.ext.MyComponent();

// Calling execute here will delay rendering until after
// the user has been successfully authorized.
myComponentInstance.execute();
myComponentInstance.on('render', function() {
  // Do something when the component renders.
});

Menunggu sampai koleksi siap

Cuplikan Embed API memuat library dan semua dependensinya secara asinkron. Ini berarti metode seperti createComponent tidak akan langsung tersedia, dan kode yang memanggil metode tersebut harus ditangguhkan hingga semuanya dimuat.

Embed API menyediakan metode gapi.analytics.ready yang menerima callback untuk dipanggil saat library dimuat sepenuhnya. Saat membuat komponen kustom, Anda harus selalu menggabungkan kode Anda di dalam fungsi ready agar tidak berjalan sebelum semua metode yang diperlukan ada.

gapi.analytics.ready(function() {

  // This code will not run until the Embed API is fully loaded.
  gapi.analytics.createComponent('MyComponent', {
    execute: function() {
      // ...
    }
  });
});

Menggunakan komponen pihak ketiga

Komponen Embed API pihak ketiga biasanya dikemas sebagai file JavaScript individu yang dapat Anda sertakan di halaman menggunakan tag <script>.

Pemuatan sangatlah penting, jadi penting untuk menyertakan cuplikan Embed API terlebih dahulu, mengikuti skrip komponen Anda dan dependensinya.

<!-- Include the Embed API snippet first. -->
<script>
(function(w,d,s,g,js,fjs){
  g=w.gapi||(w.gapi={});g.analytics={q:[],ready:function(cb){this.q.push(cb)}};
  js=d.createElement(s);fjs=d.getElementsByTagName(s)[0];
  js.src='https://apis.google.com/js/platform.js';
  fjs.parentNode.insertBefore(js,fjs);js.onload=function(){g.load('analytics')};
}(window,document,'script'));
</script>
<!-- Then include your components. -->
<script src="path/to/component.js"></script>
<script src="path/to/another-component.js"></script>

Mengelola dependensi

Komponen mungkin memiliki dependensi seperti library diagram seperti d3.js atau library pemformatan tanggal seperti moment.js. Penulis dependensi harus mendokumentasikan dependensi ini dan memilih pengguna komponen untuk memastikan dependensi ini terpenuhi.