Présentation
L'API Embed comprend plusieurs composants intégrés et vous permet de créer facilement les vôtres. Ce document explique comment créer un composant personnalisé et comment inclure des composants tiers dans votre application.
Créer un composant personnalisé
Les composants de l'API Embed personnalisés sont créés en appelant gapi.analytics.createComponent et en transmettant un nom de composant et un objet de méthodes.
Le nom transmis à createComponent sera le nom de la fonction de constructeur du composant et sera stocké sur gapi.analytics.ext. L'objet des méthodes doit contenir toutes les fonctions ou propriétés que vous souhaitez ajouter au prototype du composant.
gapi.analytics.createComponent('MyComponent', {
execute: function() {
alert('I have been executed!');
}
});
Une fois le composant créé, vous pouvez l'utiliser en appelant l'opérateur new avec le constructeur du composant.
// Create a new instance of MyComponent. var myComponentInstance = new gapi.analytics.ext.MyComponent(); // Invoke the `execute` method. myComponentInstance.execute() // Alerts "I have been executed!"
Méthode d'initialisation
Transmettre un objet de méthode à createComponent vous donne accès au prototype de votre composant, mais ne vous donne pas accès au constructeur de votre composant.
Pour résoudre ce problème, lorsque de nouveaux composants Embed API sont créés, ils recherchent automatiquement la présence d'une méthode appelée initialize. Si elle est trouvée, elle sera appelée avec le même arguments transmis au constructeur. Toute la logique que vous intégrez normalement dans un constructeur doit être placée dans la méthode d'initialisation.
Voici un exemple qui définit certaines propriétés par défaut lors de la création d'instances 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
Méthodes héritées
Les composants créés avec la méthode createComponent héritent automatiquement des méthodes de base partagées par tous les composants intégrés (get, set, on, once, off, emit). Cela permet de garantir la cohérence et la prévisibilité de tous les composants.
Par exemple, si votre composant nécessite une autorisation pour l'utilisateur, vous pouvez utiliser les méthodes héritées de gestion des événements.
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.
});
En attente de la bibliothèque
L'extrait de code de l'API Embed charge la bibliothèque et toutes ses dépendances de manière asynchrone. Cela signifie que des méthodes telles que createComponent ne seront pas disponibles immédiatement, et que le code appelant ces méthodes doit être reporté jusqu'à ce que tout soit chargé.
L'API Embed fournit la méthode gapi.analytics.ready qui accepte un rappel à invoquer lorsque la bibliothèque est entièrement chargée. Lorsque vous créez des composants personnalisés, vous devez toujours encapsuler votre code dans la fonction ready afin qu'il ne s'exécute pas avant que toutes les méthodes requises n'existent.
gapi.analytics.ready(function() {
// This code will not run until the Embed API is fully loaded.
gapi.analytics.createComponent('MyComponent', {
execute: function() {
// ...
}
});
});
Utiliser des composants tiers
Les composants d'API Embed tiers sont généralement empaquetés sous forme de fichiers JavaScript individuels que vous pouvez inclure sur votre page à l'aide d'une balise <script>.
L'ordre de chargement est important. Il est donc important d'inclure en premier l'extrait d'API Embed, suivi de vos scripts de composant et de leurs dépendances.
<!-- 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>
Gérer les dépendances
Un composant peut avoir des dépendances, telles qu'une bibliothèque de graphiques comme d3.js ou une bibliothèque de mise en forme de dates comme moment.js. Il appartient à l'auteur du composant de documenter ces dépendances et à l'utilisateur du composant de s'assurer que ces dépendances sont respectées.