Özel Bileşenler Oluşturma

Genel bakış

Embed API, çeşitli yerleşik bileşenler ile birlikte gelir ve kendi öğenizi kolayca oluşturmanızı sağlar. Bu belgede, yeni bir özel bileşenin nasıl oluşturulacağı ve uygulamanıza üçüncü taraf bileşenlerin nasıl dahil edileceği açıklanmaktadır.

Özel bileşen oluşturma

Özel Embed API bileşenleri, gapi.analytics.createComponent çağırılıp bir bileşen adı ve yöntem nesnesi iletilerek oluşturulur.

createComponent öğesine iletilen ad, bileşenin kurucu işlevinin adı olur ve gapi.analytics.ext üzerinde depolanır. Yöntem nesnesi, bileşenin prototipine eklenmesini istediğiniz tüm işlevleri veya özellikleri içermelidir.

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

Bileşen oluşturulduktan sonra, bileşen oluşturucuyla new operatörü çağrılarak kullanılabilir.

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

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

İlk kullanıma hazırlama yöntemi

createComponent öğesine bir yöntem nesnesi iletmek, bileşeninizin prototipine erişmenizi sağlar ancak bileşeninizin oluşturucusuna erişim izni vermez.

Bu sorunu çözmek için yeni Embed API bileşenleri oluşturulduğunda otomatik olarak initialize adlı yöntemin olup olmadığına bakarlar. Bu bulunursa kurucuya aynı arguments ile çağrılır. Normalde kurucuya yerleştireceğiniz tüm mantık, bunun yerine ilk kullanıma hazırlama yöntemine yerleştirilmelidir.

Yeni MyComponent örnekleri oluşturulduğunda bazı varsayılan özelliklerin ayarlandığı bir örneği burada bulabilirsiniz.

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

Devralınan yöntemler

createComponent yöntemiyle oluşturulan bileşenler, tüm yerleşik bileşenler (get, set, on, once, off,emit) tarafından paylaşılan temel yöntemleri otomatik olarak devralır. Bu, tüm bileşenlerin tutarlı ve tahmin edilebilir bir şekilde çalışmasını sağlar.

Örneğin, bileşeniniz kullanıcının yetkilendirilmesini gerektiriyorsa bu işlem, devralınan etkinlik işleme yöntemleri kullanılarak gerçekleştirilebilir.

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.
});

Kitaplık hazır olana kadar bekleniyor

Embed API snippet'i, kitaplığı ve tüm bağımlılıklarını eşzamansız olarak yükler. Bu, createComponent gibi yöntemlerin hemen kullanılamayacağı ve bu tür yöntemleri çağıran kodun her şey yüklenene kadar ertelenmesi gerektiği anlamına gelir.

Embed API, kitaplık tamamen yüklendiğinde bir geri çağırmanın çağrılmasını kabul eden gapi.analytics.ready yöntemini sağlar. Özel bileşenler oluştururken kodunuzu her zaman ready işlevinin içine sarmalamanız gerekir. Böylece kod, gerekli tüm yöntemler mevcut olmadan çalışmaz.

gapi.analytics.ready(function() {

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

Üçüncü taraf bileşenlerini kullanma

Üçüncü taraf Embed API bileşenleri genellikle bağımsız JavaScript dosyaları olarak paketlenir. Bu dosyalar, bir <script> etiketi kullanarak sayfanıza ekleyebileceğiniz şekilde sunulur.

Yükleme sırası önemlidir. Bu nedenle, önce Embed API snippet'ini, ardından bileşen komut dosyalarınızı ve bunların bağımlılıklarını izlemek önemlidir.

<!-- 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>

Bağımlılıkları yönetme

Bir bileşenin, d3.js gibi bir grafik kitaplığı veya moment.js gibi bir tarih biçimlendirme kitaplığı gibi bağımlılıkları olabilir. Bu bağımlılıkların belgelenmesi bileşen yazarına, bu bağımlılıkların karşılandığından emin olmak ise bileşen kullanıcısına bağlıdır.