Gérer les événements

Cette page explique comment écouter et gérer les événements déclenchés par un graphique.

Sommaire

Présentation

Les graphiques Google peuvent déclencher des événements que vous pouvez écouter. Les événements peuvent être déclenchés par des actions de l'utilisateur (par exemple, lorsqu'un utilisateur clique sur un graphique). Vous pouvez enregistrer une méthode JavaScript à appeler chaque fois que certains événements sont déclenchés, éventuellement avec des données spécifiques à cet événement.

Chaque graphique définit ses propres événements, et la documentation correspondante doit décrire le déclenchement de chaque événement, sa signification et comment récupérer toutes les informations associées à l'événement. Cette page explique comment s'inscrire pour recevoir des événements à partir d'un graphique et comment les gérer.

Un graphique que vous pouvez sélectionner doit se déclencher: l'événement "select". Cependant, le comportement et la signification de cet événement sont définis par chaque graphique.

Il est important de noter que les événements du graphique sont distincts des événements DOM standards.

Inscription et gestion d'un événement

Pour enregistrer vos gestionnaires d'événements, appelez google.visualization.events.addListener() ou addOneTimeListener() avec le nom du graphique exposant l'événement, le nom de la chaîne de l'événement à écouter et le nom de la fonction à appeler lors du déclenchement de l'événement. Votre fonction doit accepter un seul paramètre, à savoir l'événement déclenché. Cet événement peut disposer d'informations personnalisées, comme décrit dans la documentation du graphique.

Important : Si votre graphique expose un événement prêt, vous devez toujours attendre que cet événement se déclenche avant d'essayer d'envoyer des méthodes ou de recevoir des événements du graphique. Ces graphiques peuvent fonctionner avant de déclencher un événement prêt, mais ce comportement n'est pas garanti.

L'extrait de code suivant affiche une zone d'alerte chaque fois que l'utilisateur clique sur une ligne du tableau:

// Create a table chart on your page.
var table = new google.visualization.Table(document.getElementById('table_div'));
table.draw(data, options);

// Every time the table fires the "select" event, it should call your
// selectHandler() function.
google.visualization.events.addListener(table, 'select', selectHandler);

function selectHandler(e) {
  alert('A table row was selected');
}

Notez que cette valeur ne s'enregistre que pour écouter les événements associés à cet objet de table spécifique. Vous ne pouvez vous enregistrer que pour recevoir des événements provenant d'un objet spécifique.

Vous pouvez également transmettre une définition de fonction, comme indiqué ci-dessous:

// Pass in a function definition.
google.visualization.events.addListener(orgchart, 'select', function() {
  table.setSelection(orgchart.getSelection());
});

Récupérer des informations sur un événement

Les événements exposent généralement des informations de deux manières: en transmettant des informations à la fonction du gestionnaire en tant que paramètre ou en ajoutant des informations à un objet global. Le cas échéant, la description de l'événement doit être décrite dans la documentation de ce graphique. Voici comment récupérer ces deux types d'informations:

Informations sur l'événement transmises à votre gestionnaire

Si le graphique transmet des données en tant que paramètre à votre fonction de traitement, vous les récupérez comme indiqué ci-dessous:

// google.visualization.table exposes a 'page' event.
google.visualization.events.addListener(table, 'page', myPageEventHandler);
...
function myPageEventHandler(e) {
  alert('The user is navigating to page ' + e['page']);
}

Le paramètre transmis à votre gestionnaire possède une propriété qui doit être documentée pour le graphique. Pour obtenir un exemple de graphique présentant les informations sur un événement de cette manière, consultez l'événement de page du graphique Tableau.

Informations sur les événements transmises à un objet global

Certains événements modifient plutôt une propriété d'un objet global, que vous pouvez ensuite demander. C'est le cas de l'événement "select", qui se déclenche lorsqu'un utilisateur sélectionne une partie d'un graphique. Dans ce cas, le code doit appeler getSelection() sur le graphique pour connaître la sélection actuelle. Vous trouverez plus d'informations sur l'événement "select" ci-dessous.

// orgChart is my global orgchart chart variable.
google.visualization.events.addListener(orgChart, 'select', selectHandler);
...
// Notice that e is not used or needed.
function selectHandler(e) {
  alert('The user selected' + orgChart.getSelection().length + ' items.');
  

Événement select

Comme indiqué précédemment, tout graphique pouvant être sélectionné doit déclencher un événement "select" qui fonctionne de manière standard afin de vous permettre de récupérer les valeurs de l'élément sélectionné dans le graphique. (Cependant, il n'existe aucune exigence absolue quant au comportement d'un graphique de cette manière. Consultez la documentation de votre graphique.

En général, les graphiques exposant l'événement "select" sont conçus selon les spécifications suivantes:

  • L'événement "select" ne transmet aucune propriété ni aucun objet au gestionnaire (votre gestionnaire de fonctions ne doit pas attendre qu'il reçoive des paramètres).
  • Le graphique devrait exposer la méthode getSelection(), qui renvoie un tableau d'objets décrivant les éléments de données sélectionnés. Ces objets ont les propriétés row et column. row et column sont les index de ligne et de colonne de l'élément sélectionné dans DataTable. Les événements de sélection décrivent les données sous-jacentes du graphique, et non les éléments HTML du graphique. Pour obtenir les données de l'élément sélectionné, vous devez appeler DataTable.getValue() ou getFormattedValue().
    Si les valeurs row et column sont spécifiées, l'élément sélectionné est une cellule. Si seul row est spécifié, l'élément sélectionné est une ligne. Si seul column est spécifié, l'élément sélectionné est une colonne.
  • Le graphique devrait exposer la méthode setSelection(selection) pour modifier la sélection dans le tableau sous-jacent et sélectionner les données correspondantes dans le graphique. Le paramètre selection, qui est un tableau semblable au tableau getSelection(), où chaque élément est un objet avec les propriétés row et column. La propriété row définit l'index de la ligne sélectionnée dans DataTable, tandis que la propriété column définit l'index de la colonne sélectionnée dans DataTable. Lorsque cette méthode est appelée, le graphique doit indiquer visuellement la nouvelle sélection. L'implémentation de setSelection() ne doit pas déclencher d'événement "select".
    Si les valeurs row et column sont spécifiées, l'élément sélectionné est une cellule. Si seul row est spécifié, l'élément sélectionné est une ligne. Si seul column est spécifié, l'élément sélectionné est une colonne.

Avertissement :

  • Le graphique risque d'ignorer une partie de la sélection. Par exemple, une table ne pouvant afficher que des lignes sélectionnées peut ignorer les éléments de cellule ou de colonne dans leur mise en œuvre de setSelection.
  • Certains graphiques peuvent ne pas déclencher d'événement "select", tandis que d'autres peuvent n'accepter que la sélection de lignes ou de colonnes. La documentation de chaque graphique définit les événements et les méthodes compatibles.
  • La sélection multiple n'est pas gérée de la même façon dans les différents graphiques (certains ne l'autorisent même pas).
  • Pour lire les données sélectionnées, vous devez appeler DataTable.getValue() dans votre gestionnaire. Le moyen le plus simple d'activer est de rendre l'objet DataTable global.

L'exemple suivant apparaît dans une zone d'alerte avec les éléments de table sélectionnés, lorsqu'un élément d'un graphique de table est sélectionné:

Notez que le graphique de table ne déclenche que les événements de sélection de ligne. Toutefois, le code est générique et peut être utilisé pour les événements de sélection de ligne, de colonne et de cellule.

Voici le code de gestionnaire de cet exemple:

// Create our table.
var table = new google.visualization.Table(document.getElementById('table_div'));
table.draw(data, options);

// Add our selection handler.
google.visualization.events.addListener(table, 'select', selectHandler);

// The selection handler.
// Loop through all items in the selection and concatenate
// a single message from all of them.
function selectHandler() {
  var selection = table.getSelection();
  var message = '';
  for (var i = 0; i < selection.length; i++) {
    var item = selection[i];
    if (item.row != null && item.column != null) {
      var str = data.getFormattedValue(item.row, item.column);
      message += '{row:' + item.row + ',column:' + item.column + '} = ' + str + '\n';
    } else if (item.row != null) {
      var str = data.getFormattedValue(item.row, 0);
      message += '{row:' + item.row + ', column:none}; value (col 0) = ' + str + '\n';
    } else if (item.column != null) {
      var str = data.getFormattedValue(0, item.column);
      message += '{row:none, column:' + item.column + '}; value (row 0) = ' + str + '\n';
    }
  }
  if (message == '') {
    message = 'nothing';
  }
  alert('You selected ' + message);
}

Événement ready

La plupart des graphiques sont affichés de manière asynchrone. Tous les graphiques Google lancent un événement prêt lorsque vous appelez draw(), indiquant que le graphique est affiché, et prêt à renvoyer des propriétés ou à gérer d'autres appels de méthode. Vous devez toujours écouter l'événement "ready" avant d'essayer d'y appeler des méthodes après avoir appelé draw().

En général, les graphiques présentant l'événement "ready" sont conçus selon les spécifications suivantes:

  • L'événement "ready" ne transmet aucune propriété au gestionnaire (votre gestionnaire de fonctions ne doit pas s'attendre à ce qu'aucun paramètre lui soit transmis).
  • Le graphique devrait déclencher l'événement prêt une fois qu'il est prêt à interagir. Si le dessin du graphique est asynchrone, il est important que l'événement se déclenche lorsque des méthodes d'interaction peuvent être appelées, et pas seulement à la fin de la méthode draw.
  • Vous devez ajouter un écouteur à cet événement avant d'appeler la méthode draw(), sinon il risque de se déclencher avant que l'écouteur ne soit configuré et vous ne l'interceptez pas.
  • Si vous appelez des méthodes d'interaction avant le déclenchement de l'événement prêt, vous risquez de ne pas fonctionner correctement.

La convention est la suivante : les graphiques qui ne déclenchent pas d'événement "prêt" sont prêts à interagir immédiatement après la fin de la méthode draw et redonne le contrôle à l'utilisateur. Si votre graphique déclenche un événement prêt, vous devez attendre qu'il soit déclenché avant d'appeler des méthodes sur celui-ci, comme indiqué ci-dessous:

google.visualization.events.addListener(tableChart, 'ready', myReadyHandler);

Syntaxe du gestionnaire d'événements prêts

function myReadyHandler(){...}

Aucun paramètre n'est transmis au gestionnaire d'événements prêts.

Événement error

Les graphiques doivent générer un événement d'erreur lorsqu'ils rencontrent une erreur, pour vous permettre de le gérer correctement. Le gestionnaire d'événements reçoit une description de l'erreur, ainsi que les propriétés d'événements personnalisées spécifiques à chaque graphique. Vous devez vous abonner à cet événement juste après avoir instancié le graphique pour repérer les erreurs qui pourraient se produire ultérieurement.

Les fonctions de l'outil d'aide goog.visualization.errors vous permettent d'afficher facilement toutes les erreurs.

Syntaxe du gestionnaire d'événements d'erreur

function myErrorHandler(err){...}

Le gestionnaire d'événements d'erreur doit transmettre un objet comprenant les membres suivants:

  • id [obligatoire] : ID de l'élément DOM contenant le graphique, ou message d'erreur affiché à la place du graphique s'il ne peut pas être affiché.
  • message [obligatoire] : chaîne de message courte décrivant l'erreur.
  • detailedMessage [facultatif] : explication détaillée de l'erreur.
  • L'attribut options [Optional] contient un objet contenant des paramètres personnalisés adaptés à l'erreur et au type de graphique.

Exemple de gestion des événements

L'exemple suivant montre à la fois getSelection() et setSelection(). Il synchronise la sélection entre deux graphiques qui utilisent la même table de données. Cliquez sur l'un des graphiques pour synchroniser la sélection dans l'autre graphique.

// Create our two charts.
var table = new google.visualization.Table(document.getElementById('table_div'));
table.draw(data, {});

var orgchart = new google.visualization.OrgChart(document.getElementById('org_div'));
orgchart.draw(data, {});

// When the table is selected, update the orgchart.
google.visualization.events.addListener(table, 'select', function() {
  orgchart.setSelection(table.getSelection());
});

// When the orgchart is selected, update the table chart.
google.visualization.events.addListener(orgchart, 'select', function() {
  table.setSelection(orgchart.getSelection());
});

Cliquez sur les graphiques ci-dessous sur les lignes du tableau ou sur les éléments du graphique pour voir la sélection en action: