Criação de 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 de incorporação são criados se você chamar gapi.analytics.createComponent e passar um objeto de métodos e nome de componente.

O nome passado a createComponent será o nome da função do construtor do componente e será armazenado no 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 utilizado se você chamar 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

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

Para resolver esse problema, quando novos componentes da API de incorporação são criados, eles automaticamente procuram um método chamado initialize. Se ele for encontrado, será chamado com os mesmos arguments passados para o 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 de base compartilhados por todos os componentes integrados (get, set, on, once, off, emit). Isso garante que todos os componentes funcionem de uma forma 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();
myComponent.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 estarão disponíveis imediatamente, e o código que invoca esses métodos deve necessariamente ser adiado até que tudo esteja carregado.

A API de incorporação fornece o método gapi.analytics.ready, que aceita um retorno a ser invocado quando a biblioteca está totalmente carregada. Ao criar componentes personalizados, você deve sempre envolver 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() {
      // ...
    }
  });
});

Exemplos

Para ver exemplos funcionais de como criar seus próprios componentes, confira as demonstrações da API de incorporação no Github.

Utilização de componentes de terceiros

Componentes de terceiros da API de incorporação são normalmente organizados 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.