Überblick
Die Embed API enthält mehrere integrierte Komponenten und bietet die einfache Möglichkeit, eigene zu erstellen. In diesem Dokument wird erläutert, wie Sie eine neue benutzerdefinierte Komponente erstellen und Komponenten von Drittanbietern in Ihre Anwendung einbinden.
Benutzerdefinierte Komponente erstellen
Zum Erstellen benutzerdefinierter Embed API-Komponenten müssen gapi.analytics.createComponent aufgerufen und ein Komponentenname sowie ein Methodenobjekt übergeben werden.
Der an createComponent übergebene Name ist der Name der Konstruktorfunktion der Komponente und wird in gapi.analytics.ext gespeichert. Das Methodenobjekt sollte alle Funktionen oder Eigenschaften enthalten, die Sie dem Prototyp der Komponente hinzufügen möchten.
gapi.analytics.createComponent('MyComponent', {
execute: function() {
alert('I have been executed!');
}
});
Nachdem die Komponente erstellt wurde, kann sie durch Aufrufen des Operators new mit dem Komponentenkonstruktor verwendet werden.
// 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
Wenn Sie ein Methodenobjekt an createComponent übergeben, erhalten Sie zwar Zugriff auf den Prototyp Ihrer Komponente, aber nicht auf den Konstruktor der Komponente.
Um dieses Problem zu beheben, wird beim Erstellen neuer Embed API-Komponenten automatisch nach einer Methode namens initialize gesucht. Falls sie gefunden wird, wird sie mit derselben arguments aufgerufen, die an den Konstruktor übergeben wird. Die gesamte Logik, die Sie normalerweise in einen Konstruktor einfügen würden, sollte stattdessen in der Initialisierungsmethode eingesetzt werden.
In diesem Beispiel werden einige Standardattribute beim Erstellen neuer MyComponent-Instanzen festgelegt.
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
Komponenten, die mit der Methode createComponent erstellt wurden, übernehmen automatisch die
Basismethoden, die von allen integrierten Komponenten (get, set, on, once, off, emit) gemeinsam genutzt werden. Dadurch wird sichergestellt, dass alle Komponenten einheitlich und vorhersehbar funktionieren.
Wenn für Ihre Komponente beispielsweise eine Autorisierung des Nutzers erforderlich ist, können Sie dies mit den übernommenen Methoden zur Ereignisverarbeitung erreichen.
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 Bibliothek bereit ist
Das Embed API-Snippet lädt die Bibliothek und alle zugehörigen Abhängigkeiten asynchron. Das bedeutet, dass Methoden wie createComponent nicht sofort verfügbar sind und Code, der solche Methoden aufruft, muss zurückgestellt werden, bis alles geladen ist.
Die Embed API bietet die Methode gapi.analytics.ready, die einen Callback akzeptiert, der aufgerufen werden soll, wenn die Bibliothek vollständig geladen ist. Wenn Sie benutzerdefinierte Komponenten erstellen, müssen Sie den Code immer in die Funktion ready einbetten, damit sie 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 verpackt, die du mit einem <script>-Tag auf deiner Seite einfügen kannst.
Die Ladereihenfolge ist wichtig. Daher ist es wichtig, zuerst das Embed API-Snippet und dann die Komponentenskripts und alle zugehörigen Abhängigkeiten einzufügen.
<!-- 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 wie eine Diagrammbibliothek wie d3.js oder eine Datumsformatierungsbibliothek wie moment.js haben. Es ist Aufgabe des Komponentenautors, diese Abhängigkeiten zu dokumentieren, und der Nutzer der Komponente, ob diese Abhängigkeiten erfüllt sind.