Creazione di componenti personalizzati

Panoramica

L'API Embed è dotata di diversi componenti integrati e offre anche un modo semplice per creare i propri. Questo documento spiega come creare un nuovo componente personalizzato e come includere componenti di terze parti nella tua applicazione.

Creazione di un componente personalizzato

I componenti personalizzati dell'API Embed vengono creati chiamando gapi.analytics.createComponent e passando un nome del componente e un oggetto metodi.

Il nome passato a createComponent sarà il nome della funzione del costruttore del componente e verrà archiviato in gapi.analytics.ext. L'oggetto metodi deve 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 metodi a createComponent ti consente di accedere al prototipo del componente, ma non al costruttore del componente.

Per risolvere questo problema, quando vengono creati nuovi componenti dell'API Embed, questi cercano automaticamente la presenza di un metodo chiamato initialize. Se lo trova, verrà richiamato con lo stesso arguments passato al costruttore. Tutta la logica che inseriresti normalmente in un costruttore dovrebbe invece 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 che l'utente sia autorizzato, puoi farlo utilizzando i metodi di gestione degli eventi ereditati.

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 raccolta sia pronta

Lo snippet API Embed carica la libreria e tutte le sue dipendenze in modo asincrono. Ciò significa che metodi come createComponent non saranno immediatamente disponibili e il codice che richiama questi metodi deve essere differito fino a quando non viene caricato tutto.

L'API Embed fornisce il metodo gapi.analytics.ready che accetta il callback da richiamare quando la libreria è completamente caricata. Quando crei componenti personalizzati, devi sempre eseguire il wrapping del codice all'interno della funzione ready, in modo che non venga eseguito prima che esistano 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 tua pagina utilizzando un tag <script>.

L'ordine di caricamento è importante, perciò è importante includere prima lo snippet API Embed, seguito gli script dei componenti e 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 può avere dipendenze, ad esempio una libreria di grafici come d3.js o una libreria di formattazione delle date come moment.js. Spetta all'autore del componente documentare queste dipendenze e all'utente del componente per assicurarsi che vengano soddisfatte.