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 page Utiliser des graphiques. Nous supposons également que vous maîtrisez 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 par le biais d'une bibliothèque JavaScript que vous créez. Pour créer une bibliothèque de graphiques, procédez comme suit:

Choisissez un espace de noms pour votre code. D'autres pages hébergeront votre code. Essayez d'éviter les conflits de noms.
Implémentez votre objet de 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 pour un client, telle que getSelection(), et
- Toute méthode personnalisée que vous souhaitez exposer à vos clients.
[Facultatif] Implémentez tous les événements que vous souhaitez déclencher pour le client.
Rédigez la documentation de votre graphique. Si vous ne le documentez pas, les utilisateurs ne pourront probablement pas l'intégrer.
Publier un graphique dans la galerie

Conseil

Vous pouvez télécharger les définitions de classes et de méthodes 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 et 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 la plus récente sur l'API.

Choisir un espace de noms

Votre graphique peut être intégré à une page qui héberge d'autres graphiques ou du code JavaScript sans rapport. Pour éviter les conflits de noms avec d'autres noms de code ou de classes CSS, vous devez choisir un espace de noms unique pour le code de votre graphique. L'URL que vous utiliserez pour héberger votre script est un bon choix pour l'espace de noms (à l'exception du WWW et des extensions). Par exemple, si votre graphique est publié sur www.example.com, vous devez utiliser example comme espace de noms unique. Vous pouvez ajouter des suffixes supplémentaires en les séparant par une virgule . pour regrouper davantage votre graphique (tous les graphiques de Google comportent l'espace de noms google.visualization). Utilisez votre objet d'espace de noms pour stocker votre objet de graphique, ainsi que les variables globales nécessaires.

Voici un exemple de création d'un objet espace de noms qui contiendra une classe de graphique appelée MyTable, ainsi que les variables globales nécessaires:

// 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, veillez à 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> sur la page, pas seulement dans votre graphique. Pour résoudre ce problème, vous pouvez délimiter l'intégralité de votre graphique dans une <div> avec un nom de classe et faire en sorte que toutes 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 s'appliquera uniquement aux éléments <td> ayant un élément dont le nom de classe est "example" en tant qu'ancêtre.

td.example {color: blue;}

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

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

Insérer un graphique

Vous devrez implémenter votre graphique en tant qu'objet JavaScript exposant les méthodes standards décrites à la section Documentation de référence. Les deux méthodes requises sont le constructeur et la méthode draw(). Vous pouvez également présenter à l'utilisateur d'autres méthodes appropriées pour votre graphique. Gardez à l'esprit que la simplicité d'utilisation est préférable.

Le constructeur

Votre graphique doit comporter 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()`

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

DataTable contenant les données à afficher.
Carte facultative des options de nom/valeur de votre graphique. C'est vous qui définissez les noms et les types de valeurs des options pour votre graphique. Par exemple, dans l'exemple de graphique Hello ci-dessous, le graphique accepte une option nommée "showLineNumber" avec une valeur de type booléen. Vous devez accepter une valeur par défaut pour chaque option, au cas où l'utilisateur ne transmettrait pas de valeur pour une option spécifique. Ce paramètre est facultatif. Vous devez donc ê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.
  ...
}

Bonjour,

Voici un graphique simple qui affiche une donnée DataTable sous forme de table HTML:

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 votre 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>

Mettre en œuvre vos événements

Si vous souhaitez que votre graphique déclenche des événements utiles (par exemple, des événements timer ou des événements déclenchés par l'utilisateur comme des clics), vous devez appeler la fonction google.visualization.events.trigger avec les détails de votre événement (nom, propriétés à envoyer, etc.). Pour en savoir plus, consultez la page Événements. Vous pouvez exposer les détails de l'événement au client en ajoutant des propriétés à l'objet événement, ou exposer une méthode get...() d'un certain type sur votre graphique. 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 propriétés d'événements.

Documenter le graphique

Si vous ne documentez pas correctement votre graphique, vous n'aurez probablement pas beaucoup d'utilisateurs. Veillez à fournir les informations suivantes:

Décrivez toutes les méthodes que vous proposez. La méthode draw() est commune à tous les graphiques, mais chaque graphique est compatible avec ses propres méthodes supplémentaires. (Vous n'avez probablement pas besoin de documenter le constructeur, sauf s'il a un comportement non standard.) La liste des méthodes attendues est disponible 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. Autrement dit, le nom et les propriétés de chaque événement, ainsi que le moment où chaque événement est déclenché.
Répertoriez l'URL de votre bibliothèque de graphiques à utiliser dans l'instruction <script> d'inclusion du client, puis indiquez l'URL de votre documentation.
Attribuez 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 envoyer des données à un serveur, par exemple pour créer une image de graphique ou de carte. Si vous envoyez des données à un serveur :
- Définissez clairement les données 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 seront conservées et pendant combien de temps.

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

Envoyer votre graphique à la galerie

Une fois le graphique rédigé, vous pouvez l'envoyer pour qu'il soit publié dans la section "Graphiques supplémentaires" de notre galerie. Si vous envoyez un graphique, vous devrez signer un contrat que nous n'accepterons pas afin de ne pas créer de logiciel malveillant ni d'utiliser de manière abusive les données utilisateur. Il s'agit simplement d'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 et la documentation JavaScript sur votre propre site, ou vous pouvez laisser Google héberger la bibliothèque et la documentation à votre place. 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 Script Debugger Microsoft.
Effectuez une recherche dans le groupe de discussion de l'API Google Charts. Si vous ne trouvez pas la réponse à votre question, publiez-la dans le groupe, accompagnée d'un lien vers une page Web illustrant le problème.

Localisation

Si vous pensez que votre graphique sera utilisé par des utilisateurs de différents pays, il peut être judicieux de le faire traduire pour différentes langues et cultures. La localisation la plus simple consiste à traduire les chaînes de texte standards dans l'interface utilisateur en fonction des paramètres du navigateur de l'utilisateur. Une forme de localisation plus avancée consisterait à modifier les formats numériques selon la localisation, voire la conception de l'interface utilisateur. Si vous décidez de localiser votre graphique, répertoriez les langues qu'il accepte dans la documentation et spécifiez un paramètre par défaut pour chaque langue couramment utilisée. Il est également utile d'inclure un bouton "Changer la langue" dans l'interface utilisateur de votre graphique, au cas où vous vous tromperiez. La méthode la plus courante pour détecter la langue du navigateur consiste à consulter l'en-tête HTML Accept-Language.