Présentation
L'API Embed est fournie avec plusieurs composants intégrés et vous permet également de créer facilement les vôtres. Ce document explique comment créer un composant personnalisé et inclure des composants tiers dans votre application.
Créer un composant personnalisé
Les composants de l'API Custom Embed 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 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!"
La méthode d'initialisation
La transmission d'un objet de méthodes à createComponent vous permet d'accéder au prototype de votre composant, mais pas au constructeur de votre composant.
Pour résoudre ce problème, lorsque des composants d'API Embed 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 auriez normalement placée 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 et emit). Cela garantit que tous les composants fonctionnent de manière cohérente et prévisible.
Par exemple, si votre composant nécessite une autorisation de l'utilisateur, vous pouvez utiliser les méthodes de gestion d'événements héritées.
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.
});
Attendre que la bibliothèque soit prête
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 qui appelle ces méthodes doit être différé jusqu'à ce que tout soit chargé.
L'API Embed fournit la méthode gapi.analytics.ready qui accepte un rappel à appeler 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'elle 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 tiers de l'API Embed 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. Vous devez donc inclure l'extrait de code d'API Embed en premier, suivi des scripts de vos composants 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, comme une bibliothèque de graphiques telle que d3.js ou une bibliothèque de mise en forme de date comme moment.js. Il revient à l'auteur du composant de documenter ces dépendances, et à l'utilisateur du composant de s'assurer que ces dépendances sont respectées.