Übersicht
Die Embed API enthält mehrere integrierte Komponenten und ermöglicht es Ihnen außerdem, auf einfache Weise Ihre eigenen Komponenten zu erstellen. In diesem Dokument wird erläutert, wie Sie eine neue benutzerdefinierte Komponente erstellen und Drittanbieterkomponenten in Ihre Anwendung einbinden.
Benutzerdefinierte Komponente erstellen
Benutzerdefinierte Embed API-Komponenten werden erstellt, indem gapi.analytics.createComponent aufgerufen und ein Komponentenname und ein Methodenobjekt übergeben werden.
Der an createComponent übergebene Name ist der Name der Konstruktorfunktion der Komponente und wird unter gapi.analytics.ext gespeichert. Das method-Objekt sollte alle Funktionen oder Eigenschaften enthalten, die dem Prototyp der Komponente hinzugefügt werden sollen.
gapi.analytics.createComponent('MyComponent', {
execute: function() {
alert('I have been executed!');
}
});
Nachdem die Komponente erstellt wurde, kann sie verwendet werden, indem der Operator new mit dem Komponentenkonstruktor aufgerufen wird.
// Create a new instance of MyComponent. var myComponentInstance = new gapi.analytics.ext.MyComponent(); // Invoke the `execute` method. myComponentInstance.execute() // Alerts "I have been executed!"
Die Initialisierungsmethode
Durch die Übergabe eines Methodenobjekts an createComponent erhalten Sie Zugriff auf den Prototyp Ihrer Komponente, jedoch nicht auf den Konstruktor der Komponente.
Um dieses Problem zu beheben, suchen neue Embed API-Komponenten automatisch nach der Methode initialize. Wird sie gefunden, wird sie mit derselben arguments aufgerufen, die an den Konstruktor übergeben wird. Alle Logiken, die Sie normalerweise in einen Konstruktor einfügen, sollten stattdessen in die Initialisierungsmethode eingefügt werden.
In diesem Beispiel werden einige Standardattribute festgelegt, wenn neue MyComponent-Instanzen erstellt werden.
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
Übernommene Methoden
Für Komponenten, die mit der Methode createComponent erstellt werden, werden automatisch die Basismethoden übernommen, die von allen integrierten Komponenten (get, set, on, once, off, emit) gemeinsam genutzt werden. Dadurch werden alle Komponenten einheitlich und vorhersehbar ausgeführt.
Wenn der Nutzer beispielsweise für Ihre Komponente autorisiert werden muss, können Sie dazu die übernommenen Methoden zur Ereignisverarbeitung verwenden.
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.
});
Warten, bis die Mediathek bereit ist
Das Embed API-Snippet lädt die Bibliothek und alle zugehörigen Abhängigkeiten asynchron. Methoden wie createComponent sind also nicht sofort verfügbar. Code, der solche Methoden aufruft, muss verschoben werden, bis alles geladen ist.
Die Embed API stellt die Methode gapi.analytics.ready bereit, die einen Callback akzeptiert, der ausgelöst wird, wenn die Bibliothek vollständig geladen ist. Wenn Sie benutzerdefinierte Komponenten erstellen, sollten Sie Ihren Code immer in der Funktion ready zusammenfassen, damit er nicht ausgeführt wird, bevor alle erforderlichen Methoden vorhanden sind.
gapi.analytics.ready(function() {
// This code will not run until the Embed API is fully loaded.
gapi.analytics.createComponent('MyComponent', {
execute: function() {
// ...
}
});
});
Komponenten von Drittanbietern verwenden
Embed API-Komponenten von Drittanbietern werden normalerweise als einzelne JavaScript-Dateien gepackt, die du mithilfe eines <script>-Tags in deine Seite einfügen kannst.
Die Ladereihenfolge ist wichtig. Deshalb ist es wichtig, zuerst das Embed API-Snippet einzufügen, gefolgt von den Komponentenskripts und allen zugehörigen Abhängigkeiten.
<!-- 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>
Abhängigkeiten verwalten
Eine Komponente kann Abhängigkeiten haben, z. B. eine Diagrammbibliothek wie d3.js oder eine Datumsformatierungsbibliothek wie moment.js. Der Autor der Komponente muss diese Abhängigkeiten dokumentieren und der Komponentennutzer muss dafür sorgen, dass diese Abhängigkeiten erfüllt werden.