Creazione dei componenti personalizzati

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.