Crear componentes personalizados

Descripción general

La API de inserción incluye varios componentes integrados y también te ofrece una forma sencilla de crear los tuyos. En este documento se explica cómo crear un nuevo componente personalizado y cómo incluir componentes de terceros en la aplicación.

Crear un componente personalizado

Los componentes de la API de inserción personalizados se crean llamando a gapi.analytics.createComponent y pasando un nombre de componente y un objeto de método.

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étodo debe contener cualquier función o propiedad que quieras agregar al prototipo del componente.

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

Una vez creado 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!"

Método initialize

Pasar un objeto de método a createComponent te ofrece acceso al prototipo del componente, pero no a su constructor.

Para resolver este problema, cuando se crean nuevos componentes de la API de inserción, buscarán automáticamente un método llamado initialize. Si se encuentra, se invocará con los mismos argumentos pasados al constructor. Toda la lógica que normalmente pondrías en un constructor se debe incluir en el método initialize.

A continuación se ofrece un ejemplo que configura algunas propiedades predeterminadas cuando se crean nuevas instancias de 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

Métodos heredados

Los componentes creados con el método createComponent heredarán automáticamente los métodos base que comparten todos los componentes integrados (get, set, on, once, off y emit). De este modo se garantiza que todos los componentes funcionan de un modo coherente y predecible.

Por ejemplo, si tu componente requiere que se autorice al usuario, se pueden utilizar los métodos de gestión 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();
myComponent.on('render', function() {
  // Do something when the component renders.
});

Esperar hasta que la biblioteca esté lista

El fragmento de la API de inserción carga la biblioteca y todas sus dependencias de forma asíncrona. Por este motivo, los métodos como createComponent no estarán disponibles inmediatamente y el código que invoca dichos métodos se debe diferir hasta que se haya cargado todo.

La API de inserción proporciona el método gapi.analytics.ready que acepta que se invoque una devolución de llamada cuando la biblioteca está totalmente cargada. Al crear componentes personalizados, siempre debes incluir el código en la función ready, de modo que no se ejecute hasta que existan todos los métodos requeridos.

gapi.analytics.ready(function() {

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

Ejemplos

Para ver ejemplos funcionales de cómo crear tus propios componentes, consulta las demostraciones de la API de inserción en Github.

Utilizar componentes de terceros

Los componentes de la API de inserción de terceros normalmente se empaquetan con archivos JavaScript individuales que puedes incluir en tu página mediante una etiqueta <script>.

El orden de carga es importante, por lo que debes incluir el fragmento de la API de inserción en primer lugar, seguido de las secuencias de comandos de los componentes y cualquier dependencia.

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

Administrar las dependencias

Un componente puede tener dependencias, por ejemplo, una biblioteca de gráficos como d3.js o una biblioteca de formato de fecha como moment.js. El autor del componente es quien decide si quiere documentar estas dependencias y el usuario del componente quien decide si garantizará su cumplimiento.