Cette page a été traduite par l'API Cloud Translation.

Créer des types de graphiques

Cette page explique comment développer votre propre type de graphique et le mettre à la disposition des utilisateurs.

Audience

Dans cette page, nous partons du principe que vous avez lu la section Utiliser des graphiques. Nous supposons également que vous connaissez bien JavaScript et la programmation orientée objet. De nombreux tutoriels JavaScript sont disponibles sur le Web.

Créer un graphique

Les graphiques sont présentés à l'utilisateur via une bibliothèque JavaScript que vous créez. Voici les étapes à suivre pour créer une bibliothèque de graphiques:

Choisissez un espace de noms pour votre code. Votre code sera hébergé sur d'autres pages. Essayez d'éviter tout conflit de nom.
Implémentez votre objet graphique. Implémentez un objet JavaScript qui expose les éléments suivants :
- Un constructeur,
- Une méthode draw() pour dessiner votre objet dans l'élément DOM transmis au constructeur.
- Toute autre méthode standard facultative mise à la disposition d'un client, telle que getSelection(), et
- Toutes les méthodes personnalisées que vous souhaitez exposer à vos clients.
[Facultatif] Implémentez tous les événements que vous souhaitez déclencher pour que le client les intercepte.
Rédigez la documentation de votre graphique. Si vous ne le documentez pas, les utilisateurs ne pourront probablement pas l'intégrer.
Publier votre graphique dans la galerie de graphiques

Pourboire

Vous pouvez télécharger les définitions de classe et de méthode d'API goog.visualization pour activer la saisie semi-automatique dans votre IDE (éditeur de code). Téléchargez le fichier depuis http://www.google.com/uds/modules/gviz/gviz-api.js, puis enregistrez-le dans votre projet. La plupart des IDE l'indexent automatiquement et activent la saisie semi-automatique, bien que votre IDE puisse être différent. Notez que le fichier n'est pas toujours à jour. Consultez les pages de référence pour obtenir la documentation de référence de l'API la plus récente.

Choisir un espace de noms

Votre graphique peut être intégré sur une page qui héberge d'autres graphiques ou d'autres éléments JavaScript sans rapport avec la vôtre. Pour éviter les conflits de noms avec d'autres noms de code ou de classe CSS, vous devez choisir un espace de noms unique pour le code de votre graphique. Nous vous recommandons d'utiliser l'URL que vous utiliserez pour héberger votre script en tant qu'espace de noms (à l'exception de l'adresse WWW et des extensions). Ainsi, si votre graphique est destiné à être publié sur www.example.com, vous devez utiliser example comme espace de noms unique. Vous pouvez ajouter des suffixes supplémentaires, séparés par . pour regrouper davantage votre graphique (tous les graphiques Google possèdent l'espace de noms google.visualization). Utilisez votre objet d'espace de noms pour stocker votre objet graphique, ainsi que toutes les variables globales dont vous pourriez avoir besoin.

Voici un exemple de création d'un objet d'espace de noms destiné à contenir une classe de graphique appelée MyTable, ainsi que toutes les variables globales requises:

// Namespace, implemented as a global variable.
var example = {};

// MyTable class constructor.
example.MyTable = function(container) {
  // ...
}

// MyTable.draw() method.
example.MyTable.prototype.draw = function(data, options) {
  // ...
}

Éviter les conflits CSS

Si vous utilisez du code CSS, assurez-vous de ne pas écrire de règles CSS susceptibles d'affecter les autres graphiques de la page. Par exemple, une règle telle que td {color: blue;} est fortement déconseillée, car elle affectera tout autre élément <td> de la page, pas seulement dans votre graphique. Pour contourner ce problème, vous pouvez placer l'ensemble de votre graphique dans une <div> avec un nom de classe. Vos règles CSS ne s'appliquent qu'aux éléments descendants d'un élément portant ce nom de classe. Par exemple, la règle CSS suivante n'affectera que les éléments <td> dont l'ancêtre est un élément dont le nom de classe est "example".

td.example {color: blue;}

Vous pouvez ensuite encapsuler votre graphique dans un <div> avec :

<div class="example">
  ...
</div>

Implémenter votre graphique

Vous devez implémenter votre graphique en tant qu'objet JavaScript qui expose les méthodes standards décrites dans la section de référence. Les deux méthodes obligatoires sont le constructeur et les méthodes draw(). Vous pouvez également présenter à l'utilisateur toute autre méthode appropriée pour votre graphique. N'oubliez pas qu'il est préférable d'utiliser cette fonctionnalité.

Le Constructeur

Votre graphique doit exposer un constructeur unique qui n'accepte qu'un seul paramètre, à savoir un élément DOM dans lequel vous allez dessiner votre graphique. En règle générale, les graphiques stockent une copie locale de cet élément dans le constructeur pour une utilisation ultérieure:

function example.MyTable(container) {
  this.container = container
}

Méthode `draw()`

Votre classe de graphique doit comporter une méthode draw() définie dans le prototype de votre classe de graphique. La méthode draw() accepte deux paramètres:

Un objet DataTable contenant les données à afficher.
Carte facultative des options de nom/valeur pour votre graphique. C'est vous qui définissez les noms et les types de valeurs des options pour votre graphique spécifique. Dans l'exemple de graphique Hello présenté ci-dessous, le graphique accepte une option nommée "showLineNumber" dont la valeur est de type booléen. Vous devez accepter une valeur par défaut pour chaque option, au cas où l'utilisateur ne transmette pas de valeur pour une option spécifique. Ce paramètre est facultatif. Vous devez donc également être prêt à utiliser toutes les valeurs par défaut si l'utilisateur ne le transmet pas (en savoir plus).

example.MyTable.prototype.draw = function(data, options) {
  // Process data and options and render output into the container element.
  ...
}

Graphique "Hello"

Voici un graphique simple qui affiche des données DataTable sous forme de tableau HTML:

Et voici le code d'implémentation:

// Declare a unique namespace.
var example = {};

// Class constructor. Parameter container is a DOM elementon the client that
// that will contain the chart.
example.MyTable = function(container) {
  this.containerElement = container;
}

// Main drawing logic.
// Parameters:
//   data is data to display, type google.visualization.DataTable.
//   options is a name/value map of options. Our example takes one option.
example.MyTable.prototype.draw = function(data, options) {

  // Create an HTML table
  var showLineNumber = options.showLineNumber; // Boolean configuration option.

  var html = [];
  html.push('<table border="1">');

  // Header row
  html.push('<tr>');
  if (showLineNumber) {
    html.push('<th>Seq</th>');
  }
  for (var col = 0; col < data.getNumberOfColumns(); col++) {
    html.push('<th>' + this.escapeHtml(data.getColumnLabel(col)) + '</th>');
  }
  html.push('</tr>');

  for (var row = 0; row < data.getNumberOfRows(); row++) {
    html.push('<tr>');
    if (showLineNumber) {
      html.push('<td align="right">', (row + 1), '</td>');
    }

    for (var col = 0; col < data.getNumberOfColumns(); col++) {
      html.push(data.getColumnType(col) == 'number' ? '<td align="right">' : '<td>');
      html.push(this.escapeHtml(data.getFormattedValue(row, col)));
      html.push('</td>');
    }
    html.push('</tr>');
  }
  html.push('</table>');

  this.containerElement.innerHTML = html.join('');
}

// Utility function to escape HTML special characters
example.MyTable.prototype.escapeHtml = function(text) {
  if (text == null)
    return '';
  return text.replace(/&/g, '&').replace(/</g, '<')
      .replace(/>/g, '>').replace(/"/g, '"');
}

Inclure un graphique dans une page Web

Pour utiliser le graphique précédent, enregistrez-le dans un fichier .js accessible depuis votre navigateur. Enregistrez ensuite le code suivant en modifiant le paramètre source <script> pour qu'il pointe vers votre fichier JavaScript:

<html>
  <head>
    <script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
    <script type="text/javascript" src="mytablevis.js"></script>
    <script type="text/javascript">
      google.charts.load("current");

      // Set callback to run when API is loaded
      google.charts.setOnLoadCallback(drawVisualization);

      // Called when the Chart API is loaded.
      function drawVisualization() {

        // Create and populate a data table.
        var data = new google.visualization.DataTable();
        data.addColumn('string', 'Task');
        data.addColumn('number', 'Daily Hours');
        data.addRows(5);
        data.setCell(0, 0, 'Work');
        data.setCell(0, 1, 11);
        // Add more data rows and cells here

        // Instantiate our table object.
        var vis = new example.MyTable(document.getElementById('mydiv'));

        // Draw our table with the data we created locally.
        vis.draw(data, {showLineNumber: true});
       }
   </script>
  <title>MyTable example page</title></head>
  <body>
    <div id="mydiv"></div>
    <p>This page demonstrates hosting a table visualization.</p>
  </body>
</html>

Implémenter vos événements

Si vous souhaitez que votre graphique déclenche des événements utiles (par exemple, des événements de minuteur ou des événements déclenchés par l'utilisateur tels que des clics), vous devez appeler la fonction google.visualization.events.trigger avec les détails de l'événement (nom, propriétés à envoyer, etc.). Pour plus d'informations, consultez la page Événements. Vous pouvez soit exposer les détails de votre événement au client en ajoutant des propriétés à l'objet événement, soit exposer une méthode get...() d'un type quelconque sur votre graphique, que le client peut appeler cette méthode pour obtenir les détails de l'événement. Dans les deux cas, documentez bien vos méthodes ou vos propriétés d'événement.

Documenter votre graphique

Si vous ne documentez pas correctement votre graphique, vous n’obtiendrez probablement pas beaucoup d’utilisateurs. Veillez à documenter les éléments suivants:

Décrivez toutes les méthodes que vous prenez en charge. La méthode draw() est commune à tous les graphiques, mais chaque graphique peut être compatible avec ses propres méthodes supplémentaires. (Vous n'avez probablement pas besoin de documenter votre constructeur, sauf si son comportement n'est pas standard.) Vous trouverez la liste des méthodes attendues sur la page de référence.
Décrivez toutes les options compatibles avec votre méthode draw(). Cela inclut le nom de chaque option, le type de valeur attendu et sa valeur par défaut.
Décrivez tous les événements que vous déclenchez. Il s'agit du nom et des propriétés de chaque événement, ainsi que du moment où chaque événement est déclenché.
Indiquez l'URL de la bibliothèque de graphiques à utiliser dans l'instruction "include" <script> du client, puis indiquez l'URL de votre documentation.
Donnez le nom complet de votre graphique.
Créez des exemples de pages qui montrent comment utiliser votre graphique avec les options qu'il accepte, ses événements et ses méthodes personnalisées.
Décrivez clairement la stratégie de données de votre graphique. La plupart des graphiques traitent les données dans le navigateur, mais certains peuvent en envoyer à un serveur, par exemple pour créer une image d'un graphique ou d'une carte. Si vous envoyez des données à un serveur :
- Définissez clairement quelles données sont envoyées.
- Notez la durée de conservation des données sur le serveur.
- Documentez les entités qui auront accès aux données. Par exemple, Entreprise XYZ, etc.
- Indiquez si les données doivent être consignées et pendant combien de temps.

Votre documentation sera hébergée au même endroit que le code de votre graphique (voir Envoyer votre graphique à la galerie ci-dessous).

Publier votre graphique dans la galerie

Une fois votre graphique rédigé, envoyez-le pour publication dans la section "Graphiques supplémentaires" de notre galerie. Lorsque vous envoyez un graphique, vous devez signer un accord avec nous pour accepter de ne pas créer de logiciels malveillants ou d'utiliser les données utilisateur de manière abusive. La galerie n'est qu'une liste de pointeurs vers les graphiques que nous avons créés ou que nous avons examinés. Vous pouvez choisir d'héberger la bibliothèque JavaScript et la documentation sur votre propre site, ou demander à Google d'héberger la bibliothèque et la documentation. Indiquez si vous souhaitez que nous hébergions votre graphique lorsque vous le publiez dans la galerie.

Dépannage

Si votre code ne semble pas fonctionner, voici quelques approches qui pourraient vous aider à résoudre vos problèmes:

Vérifiez qu'il ne contient pas de fautes de frappe. Rappelez-vous que le langage JavaScript est sensible à la casse.
Utilisez un débogueur JavaScript. Dans Firefox, vous pouvez utiliser la console JavaScript, le débogueur Venkman ou le module complémentaire Firebug. Dans IE, vous pouvez utiliser Microsoft Script Debugger.
Effectuez une recherche dans le groupe de discussion sur l'API Google Charts. Si vous ne trouvez pas de message qui réponde à votre question, posez votre question au groupe en l'accompagnant d'un lien vers une page Web qui illustre le problème.

Localisation

Si vous pensez que votre graphique sera utilisé par des personnes situées dans divers pays, vous pouvez choisir de le localiser dans différentes langues et cultures. La localisation la plus basique consiste à traduire les chaînes de texte standards dans l'interface utilisateur en fonction des paramètres du navigateur de l'utilisateur. Une forme plus avancée de localisation consisterait à modifier les formats numériques en fonction de la localisation, voire la conception de l'interface utilisateur. Si vous décidez de localiser votre graphique, indiquez dans votre documentation les langues prises en charge par celui-ci et indiquez le paramètre par défaut d'une langue couramment utilisée. Il est également utile d'inclure un bouton "Changer de langue" dans l'interface utilisateur de votre graphique au cas où vous vous trompez de langue. La méthode la plus courante pour détecter la langue du navigateur consiste à examiner l'en-tête HTML Accept-Language.