Membuat Komponen Khusus

Ringkasan

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

Membuat komponen kustom

Komponen Embed API kustom dibuat dengan memanggil gapi.analytics.createComponent serta 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 Anda tambahkan ke prototipe komponen.

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

Setelah dibuat, komponen dapat digunakan dengan memanggil operator new bersama 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, tetapi tidak memberi Anda akses ke konstruktor komponen.

Untuk mengatasi masalah ini, saat komponen Embed API baru dibuat, komponen tersebut akan otomatis mencari keberadaan metode yang disebut initialize. Jika ditemukan, fungsi tersebut akan dipanggil dengan arguments yang sama yang diteruskan ke konstruktor. Semua logika yang biasanya Anda masukkan ke dalam konstruktor harus dimasukkan 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 dibagikan oleh semua komponen bawaan (get, set, on, once, off, emit). Hal ini memastikan semua komponen berfungsi secara konsisten dan dapat diprediksi.

Misalnya, jika komponen Anda mengharuskan pengguna untuk diberi otorisasi, hal ini dapat dilakukan 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 hingga library siap

Cuplikan Embed API memuat library dan semua dependensinya secara asinkron. Artinya, metode seperti createComponent tidak akan segera 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 di dalam fungsi ready agar tidak berjalan sebelum semua metode yang diperlukan tersedia.

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 dipaketkan sebagai file JavaScript individual yang dapat Anda sertakan di halaman menggunakan tag <script>.

Urutan pemuatan penting, jadi penting untuk menyertakan cuplikan Embed API terlebih dahulu, diikuti 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 komponen dapat mendokumentasikan dependensi tersebut dan pengguna komponen dapat memastikan bahwa dependensi ini terpenuhi.