Como criar componentes personalizados

Visão geral

A API de incorporação vem com vários componentes integrados e fornece a você uma maneira fácil de criar seu próprio componente. Este documento explica como criar um novo componente personalizado e incluir componentes de terceiros no seu aplicativo.

Criação de um componente personalizado

Os componentes personalizados da API Embed são criados chamando gapi.analytics.createComponent e passando um objeto de métodos e nome de componente.

O nome transmitido para createComponent será o nome da função de construtor do componente e será armazenado em gapi.analytics.ext. O objeto de métodos deve conter quaisquer funções ou propriedades que você deseja adicionar ao protótipo do componente.

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

Depois que o componente é criado, ele pode ser usado chamando o operador new com o construtor do componente.

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

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

O método de inicialização

Transmitir um objeto de métodos para createComponent dá acesso ao protótipo do componente, mas não ao construtor do componente.

Para resolver esse problema, quando novos componentes da API de incorporação são criados, eles procuram automaticamente a presença de um método chamado initialize. Se encontrado, ele será invocado com o mesmo arguments transmitido ao construtor. Toda lógica que você normalmente coloca em um construtor deve ser colocada no método de inicialização.

Veja um exemplo que define algumas propriedades padrão quando novas instâncias MyComponent são criadas.

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

Métodos herdados

Os componentes criados com o método createComponent herdam automaticamente os métodos básicos compartilhados por todos os componentes integrados (get, set, on, once, off, emit). Isso garante que todos os componentes funcionem de maneira consistente e previsível.

Por exemplo, se seu componente requer que o usuário seja autorizado, isso pode ser realizado utilizando os métodos de tratamento do evento herdado.

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

Espera até que a biblioteca esteja pronta

O snippet da API de incorporação carrega a biblioteca e todas as suas dependências de forma assíncrona. Isso significa que métodos como createComponent não ficarão disponíveis imediatamente e que o código que invoca esses métodos precisa ser adiado até que tudo esteja carregado.

A API de incorporação fornece o método gapi.analytics.ready, que aceita um callback a ser invocado quando a biblioteca está totalmente carregada. Ao criar componentes personalizados, sempre envolva seu código na função ready para que ele não seja executado antes da existência de todos os métodos necessários.

gapi.analytics.ready(function() {

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

Utilização de componentes de terceiros

Os componentes de terceiros da API de incorporação geralmente são empacotados como arquivos JavaScript individuais que você pode incluir na sua página usando uma tag <script>.

A ordem do carregamento é importante, por isso, inclua o snippet da API de incorporação primeiro, seguido dos seus scripts de componentes e de todas as dependências deles.

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

Gerenciamento de dependências

Um componente pode ter dependências, como uma biblioteca de gráficos (por exemplo, d3.js) ou uma biblioteca de formatação de datas, como moment.js. Cabe ao autor do componente documentar essas dependências e ao usuário do componente garantir que essas dependências sejam atendidas.