Panoramica
L'API Embed include diversi componenti integrati e ti consente di crearne uno facilmente. Questo documento spiega come creare un nuovo componente personalizzato e come includere componenti di terze parti nella tua applicazione.
Creare un componente personalizzato
I componenti API Embed personalizzati vengono creati chiamando
gapi.analytics.createComponent
e passando un oggetto componente e nome metodo.
Il nome passato a createComponent
sarà il nome della funzione costruttore del componente e verrà archiviato in gapi.analytics.ext
. L'oggetto method dovrebbe contenere tutte le funzioni o le proprietà che vuoi aggiungere al prototipo del componente.
gapi.analytics.createComponent('MyComponent', { execute: function() { alert('I have been executed!'); } });
Una volta creato, il componente può essere utilizzato chiamando l'operatore new
con il costruttore 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!"
Il metodo di inizializzazione
Il passaggio di un oggetto dei metodi a createComponent
ti consente di accedere
al prototipo del tuo componente, ma non ti consente di accedere
al costruttore del tuo componente.
Per risolvere il problema, quando vengono creati nuovi componenti dell'API Embed, cercano automaticamente la presenza di un metodo chiamato initialize
. Se la trova, viene richiamata con lo stesso arguments
passato al costruttore. Tutta la logica che in genere inseriresti in un costruttore
deve essere inserita nel metodo di inizializzazione.
Ecco un esempio che imposta alcune proprietà predefinite quando vengono create nuove istanze 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
Metodi ereditati
I componenti creati con il metodo createComponent
erediteranno automaticamente
i
metodi di base condivisi da tutti i componenti integrati (get
,
set
, on
, once
, off
,
emit
). In questo modo tutti i componenti funzionano in modo coerente e prevedibile.
Ad esempio, se il componente richiede l'autorizzazione dell'utente, puoi farlo utilizzando i metodi ereditati di gestione degli eventi.
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. });
In attesa che la libreria sia pronta
Lo snippet dell'API Embed carica la libreria e tutte le sue dipendenze in modo asincrono. Ciò significa che metodi come createComponent
non saranno disponibili immediatamente e il codice che richiama tali metodi dovrà essere differito fino a quando non verrà caricato tutto.
L'API Embed fornisce il metodo gapi.analytics.ready
,
che accetta un callback da richiamare quando la libreria è completamente caricata. Quando crei i componenti personalizzati, devi sempre inserire il codice nella funzione ready
in modo che non venga eseguito prima dell'esistenza di tutti i metodi richiesti.
gapi.analytics.ready(function() { // This code will not run until the Embed API is fully loaded. gapi.analytics.createComponent('MyComponent', { execute: function() { // ... } }); });
Utilizzo di componenti di terze parti
I componenti dell'API Embed di terze parti sono generalmente pacchettizzati come singoli file JavaScript che puoi includere nella pagina utilizzando un tag <script>
.
L'ordine di caricamento è importante, quindi è importante prima includere lo snippet dell'API Embed e seguire gli script del componente e tutte le relative dipendenze.
<!-- 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>
Gestione delle dipendenze
Un componente potrebbe avere dipendenze quali una libreria di grafici come d3.js o una libreria di formattazione di date come moment.js. Spetta all'autore del componente documentare queste dipendenze e fino all'utente del componente per assicurarsi che tali dipendenze siano soddisfatte.