Tworzenie komponentów niestandardowych

Przegląd

Interfejs Embed API ma kilka wbudowanych komponentów i umożliwia łatwe tworzenie własnych. Z tego dokumentu dowiesz się, jak utworzyć nowy niestandardowy komponent i jak uwzględnić komponenty innych firm w swojej aplikacji.

Tworzenie komponentu niestandardowego

Niestandardowe komponenty interfejsu Embed API tworzy się przez wywołanie gapi.analytics.createComponent i przekazywanie nazwy komponentu i obiektu metod.

Nazwa przekazana do createComponent będzie nazwą funkcji konstruktora komponentu i będzie przechowywana w gapi.analytics.ext. Obiekt metod powinien zawierać wszystkie funkcje lub właściwości, które chcesz dodać do prototypu komponentu.

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

Po utworzeniu komponentu można go użyć, wywołując operator new za pomocą konstruktora komponentów.

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

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

Metoda inicjowania

Przesłanie obiektu metod do funkcji createComponent daje dostęp do prototypu komponentu, ale nie daje dostępu do konstruktora komponentu.

Aby rozwiązać ten problem, podczas tworzenia nowych komponentów interfejsu Embed API automatycznie wykrywają one obecność metody o nazwie initialize. Jeśli zostanie znaleziony, zostanie wywołany z tym samym atrybutem arguments przekazanym do konstruktora. Wszystkie funkcje logiczne, które zwykle umieszcza się w konstruktorze, należy umieścić w metodzie inicjowania.

Oto przykład, który ustawia niektóre właściwości domyślne podczas tworzenia nowych instancji MyComponent.

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

Metody dziedziczone

Komponenty utworzone za pomocą metody createComponent automatycznie dziedziczą metody podstawowe wspólne ze wszystkich wbudowanych komponentów (get, set, on, once, off, emit). Dzięki temu wszystkie komponenty będą działać w spójny i przewidywalny sposób.

Jeśli na przykład komponent wymaga autoryzacji użytkownika, możesz to osiągnąć za pomocą dziedziczonych metod obsługi zdarzeń.

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

Czekam, aż biblioteka będzie gotowa

Fragment kodu Embed API wczytuje bibliotekę i wszystkie jej zależności asynchronicznie. Oznacza to, że metody takie jak createComponent nie będą dostępne od razu, a kod wywołujący te metody musi być odroczony do czasu wczytania wszystkich elementów.

Interfejs Embed API udostępnia metodę gapi.analytics.ready, która akceptuje wywołanie zwrotne wywoływane po pełnym wczytaniu biblioteki. Podczas tworzenia komponentów niestandardowych zawsze pakuj kod wewnątrz funkcji ready, aby nie uruchamiała się, zanim będą istnieć wszystkie wymagane metody.

gapi.analytics.ready(function() {

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

Używanie komponentów innych firm

Komponenty interfejsu Embed API innych firm są zwykle opracowywane w postaci pojedynczych plików JavaScript, które można umieścić na stronie za pomocą tagu <script>.

Kolejność wczytywania ma znaczenie, dlatego ważne jest, aby najpierw umieścić fragment kodu Embed API, a po skryptach komponentów i ich zależnościach.

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

Zarządzanie zależnościami

Komponent może zawierać zależności, np. bibliotekę wykresów (np. d3.js) lub bibliotekę formatowania daty, taką jak moment.js. Zadaniem autora komponentu jest udokumentowanie tych zależności, a użytkownik komponentu musi zadbać o ich spełnienie.