Descripción general
La API de Embed viene con varios componentes integrados y también te permite crear los tuyos con facilidad. En este documento, se explica cómo compilar un nuevo componente personalizado y cómo incluir componentes de terceros en tu aplicación.
Cómo crear un componente personalizado
Los componentes personalizados de la API de Embed se crean llamando a gapi.analytics.createComponent y pasando 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 las funciones o propiedades 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 da acceso al prototipo de tu componente, pero no al constructor de tu componente.
Para solucionar este problema, cuando se creen nuevos componentes de la API de Embed, se buscarán automáticamente la presencia de un método llamado initialize. Si se encuentra, se invocará con el mismo arguments pasado al constructor. En su lugar, toda la lógica que normalmente usarías en un constructor se debe incluir en el método de inicialización.
En este ejemplo, se configuran 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 básicos compartidos por todos los componentes integrados (get, set, on, once, off, 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 con 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. Eso significa que los métodos como createComponent no estarán disponibles de inmediato y que el código que los invoque debe aplazarse 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 invocará cuando la biblioteca esté completamente cargada. Cuando creas componentes personalizados, siempre debes unir tu código dentro de 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() {
// ...
}
});
});
Utiliza 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 Embed y, luego, seguir las secuencias de comandos de los 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 formato de fecha, como moment.js. Depende del autor del componente documentar estas dependencias y el usuario del componente garantizar que se cumplan.