Crear tipos de gráficos

En esta página, se describe cómo desarrollar tu propio tipo de gráfico y hacer que esté disponible para los usuarios.

Público

En esta página, se supone que leíste la página Usa gráficos. También se supone que estás familiarizado con JavaScript y la programación orientada a objetos. Hay muchos instructivos de JavaScript disponibles en la Web.

Cómo crear un gráfico

Los gráficos se exponen al usuario a través de la biblioteca JavaScript que crees. A continuación, se indican los pasos para crear una biblioteca de gráficos:

  1. Elige un espacio de nombres para el código. Otras páginas alojarán tu código; debes intentar evitar conflictos de nombres.
  2. Implementa el objeto de gráfico. Implementa un objeto JavaScript que exponga lo siguiente:
    • Un constructor,
    • Un método draw() para dibujar tu objeto dentro del elemento DOM que se pasa al constructor
    • Cualquier otro método estándar opcional para que use un cliente, como getSelection()
    • Cualquier método personalizado que desees exponer a tus clientes
  3. [Opcional] Implementa cualquier evento que quieras activar para que el cliente lo detecte.
  4. Escribe la documentación para tu gráfico. Si no lo documentas, es probable que las personas no puedan incorporarlo.
  5. Publique su gráfico en la Galería de gráficos.

Sugerencia

  • Puedes descargar las definiciones de la clase y el método de la API de goog.visualization para habilitar el autocompletado en tu IDE (editor de código). Descarga el archivo de http://www.google.com/uds/modules/gviz/gviz-api.js y guárdalo en tu proyecto. La mayoría de los IDE lo indexarán automáticamente y habilitarán el autocompletado, aunque tu IDE puede ser diferente. Ten en cuenta que el archivo podría no estar siempre actualizado. Consulta las páginas de referencia para obtener la referencia de API más actualizada.

Elige un espacio de nombres

Tu gráfico se puede incorporar en una página que aloje otros gráficos o cualquier otro JavaScript no relacionado. A fin de evitar conflictos de nombres con otros nombres de clase de código o CSS, debes elegir un espacio de nombres único para el código de tu gráfico. Una buena opción para un espacio de nombres es la URL que usarás para alojar tu secuencia de comandos (menos WWW y cualquier extensión). Por ejemplo, si el gráfico se publicará en www.example.com, debes usar example como tu espacio de nombres único. Puede agregar sufijos adicionales, separados por para agrupar aún más el gráfico (todos los gráficos de Google tienen el espacio de nombres google.visualization). Usa el objeto de espacio de nombres para almacenar el objeto de gráfico, así como cualquier variable global que puedas necesitar.

Este es un ejemplo de la creación de un objeto de espacio de nombres para contener una clase de gráfico llamada MyTable, así como cualquier variable global necesaria:

// 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) {
  // ...
}

Cómo evitar conflictos de CSS

Si usas CSS, asegúrate de no escribir reglas de CSS que puedan afectar a otros gráficos de la página. Por ejemplo, no se recomienda una regla como td {color: blue;}, ya que afectará a cualquier otro elemento <td> de la página, no solo a tu gráfico. Una forma de solucionar esto es encerrar todo el gráfico en una <div> con un nombre de clase, y hacer que todas las reglas de CSS se apliquen solo a los elementos que son descendientes de un elemento con ese nombre de clase. Por ejemplo, la siguiente regla de CSS solo afectará a los elementos <td> que tengan un elemento con el nombre de clase "example" como principal.

td.example {color: blue;}

Luego, puedes unir tu gráfico a una <div> con el siguiente comando :

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

Cómo implementar su gráfico

Deberás implementar tu gráfico como un objeto de JavaScript que exponga los métodos estándar descritos en la Sección de referencia. Los dos métodos obligatorios son el constructor y los métodos draw(). También puedes exponer cualquier método adicional para tu usuario que sea apropiado para tu gráfico. Solo recuerda que es más fácil de usar.

El constructor

El gráfico debe exponer un único constructor que tome un solo parámetro, un elemento DOM en el que dibujarás el gráfico. Por lo general, los gráficos almacenan una copia local de este elemento en el constructor para su uso posterior:

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

El método draw()

La clase de gráfico debe tener un método draw() definido en el prototipo de la clase. El método draw() acepta dos parámetros:

  1. Un objeto DataTable que contiene los datos que se mostrarán.
  2. Un mapa opcional de opciones de nombres/valores para su gráfico Tú defines los nombres y los tipos de valores de las opciones para tu gráfico específico. Por ejemplo, en el siguiente ejemplo de gráfico de Hello, el gráfico admite una opción llamada “showLineNumber” con un valor de tipo booleano. Deberías admitir un valor predeterminado para cada opción, en caso de que el usuario no pase un valor de una opción específica. Este parámetro es opcional, por lo que también debes estar preparado para usar todos los valores predeterminados si el usuario no pasa este parámetro (más información).
example.MyTable.prototype.draw = function(data, options) {
  // Process data and options and render output into the container element.
  ...
}

¡Hola, gráfico!

A continuación, se incluye un gráfico sencillo que muestra los datos de DataTable como una tabla HTML:

Este es el código de implementación:

// 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, '"');
}

Cómo incluir un gráfico en una página web

Para usar el gráfico anterior, guárdalo en un archivo .js al que puedas acceder desde tu navegador. Luego, guarda el siguiente código y cambia el parámetro fuente <script> para que apunte a tu archivo 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>

 

Cómo implementar sus eventos

Si deseas que tu gráfico active eventos útiles (por ejemplo, eventos de temporizador o eventos iniciados por el usuario, como los clics), deberás llamar a la función google.visualization.events.trigger con los detalles de tu evento (nombre, propiedades a enviar, etc.). Puedes encontrar detalles en la página Eventos. Puedes exponer los detalles de tu evento al cliente agregando propiedades al objeto de evento o puedes exponer un método get...() de algún tipo en tu gráfico, y el cliente puede llamar a ese método para obtener los detalles del evento. En cualquier caso, debes documentar bien tus métodos o propiedades de eventos.

Documenta tu gráfico

Si no documenta su gráfico de manera adecuada, es probable que no obtenga muchos usuarios. Asegúrese de documentar lo siguiente:

  • Describe todos los métodos que admites. El método draw() es común a todos los gráficos, pero cada gráfico puede admitir sus propios métodos adicionales. (Es probable que no necesites documentar tu constructor, a menos que tenga un comportamiento no estándar). Puedes encontrar una lista de los métodos esperados en la página de referencia.
  • Describe todas las opciones que admite tu método draw(). Esto incluye el nombre de cada opción, el tipo de valor esperado y su valor predeterminado.
  • Describa todos los eventos que activa. Esto significa el nombre y las propiedades de cada evento, y cuándo se activa cada uno.
  • Enumera la URL de la biblioteca de gráficos que se debe usar en la declaración de inclusión <script> del cliente y proporciona la URL para la documentación.
  • Asigne el nombre completo a su gráfico.
  • Crea páginas de muestra que demuestren cómo usar un gráfico con las opciones que admite, sus eventos y métodos personalizados.
  • Describa claramente la política de datos de su gráfico. La mayoría de los gráficos procesan los datos dentro del navegador, pero algunos pueden enviar los datos a un servidor, por ejemplo, para crear la imagen de un gráfico o un mapa. Si envías datos a un servidor, haz lo siguiente:
    • Defina claramente qué datos se envían.
    • Observa cuánto tiempo se guardarán los datos en el servidor.
    • Documenta qué entidades tendrán acceso a los datos. Por ejemplo, la empresa XYZ, etcétera.
    • Especifica si se registrarán los datos y durante cuánto tiempo.

La documentación se alojará en el mismo lugar que el código del gráfico (consulta Enviar gráfico a la galería a continuación).

Después de redactar su gráfico, envíelo para que se publique en la sección "Gráficos adicionales" de nuestra galería. Si envías un gráfico, deberás firmar un acuerdo con nosotros para no crear software malicioso ni hacer un uso inadecuado de los datos del usuario. La galería es simplemente una lista de punteros a los gráficos que hemos creado o que hemos revisado. Puedes elegir alojar la biblioteca JavaScript y la documentación reales en tu propio sitio, o puedes hacer que Google aloje la biblioteca y la documentación. Especifica si deseas que alojemos tu gráfico cuando lo publiques en la galería.

Solución de problemas

Si tu código parece no funcionar, estos son algunos enfoques que pueden ayudarte a resolver tus problemas:

  • Busca errores de ortografía. Recuerda que JavaScript es un lenguaje en el que se distinguen mayúsculas y minúsculas.
  • Usa un depurador de JavaScript. En Firefox, puedes usar la Consola de JavaScript, Venkman Debugger o el complemento de Firebug. En IE, puedes usar el Depurador de secuencias de comandos de Microsoft.
  • Busque en el grupo de discusión de la API de Google Chart. Si no encuentras una publicación que responda tu pregunta, publícala en el grupo junto con un vínculo a una página web que demuestre el problema.

Localización

Si esperas que personas de diferentes países utilicen tu gráfico, es posible que quieras adaptarlo a diferentes idiomas y culturas. La localización más básica es traducir las strings de texto estándar en la IU según la configuración del navegador del usuario. Una forma más avanzada de localización sería cambiar los formatos de número según la localización o, incluso, el diseño de la IU. Si decides localizar el gráfico, enumera los idiomas que admite el gráfico y proporciona una configuración predeterminada de un idioma de uso común. También es útil incluir un botón "cambiar idioma" en la IU de tu gráfico, en caso de que cometas el error en el idioma. La forma más común de detectar el idioma del navegador es observar el encabezado HTML Accept-Language.