Cómo crear componentes personalizados

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Descripción general

La API de Embed viene con varios componentes integrados y también te brinda una manera fácil de crear los tuyos. En este documento, se explica cómo compilar un componente personalizado nuevo y cómo incluir componentes de terceros en tu aplicación.

Cómo crear un componente personalizado

Para crear componentes personalizados de la API de Embed, se llama a gapi.analytics.createComponent y se pasa un nombre de componente y un objeto de métodos.

El nombre que se pase a createComponent será el nombre de la función del constructor del componente, y se almacenará en gapi.analytics.ext. El objeto de métodos debe contener cualquier función o propiedad que desees agregar al prototipo del componente.

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

Una vez que se crea el componente, se puede usar llamando al operador new con el constructor del 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!"

El método de inicialización

Pasar un objeto de métodos a createComponent te brinda acceso al prototipo de tu componente, pero no te brinda acceso al constructor del componente.

Para solucionar este problema, cuando se creen nuevos componentes de la API de Embed, buscarán automáticamente la presencia de un método llamado initialize. Si se encuentra, se invocará con el mismo arguments que se pasa al constructor. Toda la lógica que normalmente colocarías en un constructor debería colocarse en el método de inicialización.

Este es un ejemplo que establece algunas propiedades predeterminadas cuando se crean instancias de MyComponent nuevas.

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 heredados

Los componentes creados con el método createComponent heredarán automáticamente los métodos base compartidos por todos los componentes integrados (get, set, on, once, off y emit). Esto garantiza que todos los componentes funcionen de manera coherente y predecible.

Por ejemplo, si tu componente requiere que el usuario esté autorizado, esto se puede lograr mediante los métodos de control de eventos heredados.

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

Esperando a que la biblioteca esté lista

El fragmento de la API de Embed carga la biblioteca y todas sus dependencias de manera asíncrona. Esto significa que métodos como createComponent no estarán disponibles de inmediato y el código que los invoca debe posponerse hasta que se cargue todo.

La API de Embed proporciona el método gapi.analytics.ready que acepta una devolución de llamada que se invoca cuando la biblioteca está completamente cargada. Cuando creas componentes personalizados, siempre debes unir tu código a la función ready para que no se ejecute antes de que existan todos los métodos obligatorios.

gapi.analytics.ready(function() {

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

Usa componentes de terceros

Por lo general, los componentes de la API de Embed de terceros se empaquetan como archivos JavaScript individuales que puedes incluir en tu página mediante una etiqueta <script>.

El orden de carga es importante, por lo que es importante incluir primero el fragmento de la API de incorporación, seguir las secuencias de comandos de sus componentes y cualquiera de sus dependencias.

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

Administración de dependencias

Un componente puede tener dependencias como una biblioteca de gráficos como d3.js o una biblioteca de formatos de fechas como moment.js. Depende del autor del componente documentar estas dependencias y del usuario del componente garantizar que se cumplan.