Conceptos básicos de Apps Script con Hojas de cálculo de Google, episodio 5: Presenta datos en gráficos y presentaciones

1. Introducción

Te damos la bienvenida a la quinta parte de la playlist del codelab de Fundamentos de Apps Script con Hojas de cálculo de Google. En este codelab, aprenderás a usar el servicio de hojas de cálculo en Apps Script para generar un gráfico a partir de un conjunto de datos. También aprenderás a usar el servicio de Slides para exportar el gráfico a una nueva presentación en Presentaciones de Google.

Qué aprenderás

  • Cómo crear un gráfico de líneas con Apps Script
  • Cómo exportar gráficos a una nueva presentación de Presentaciones
  • Cómo presentar diálogos al usuario en Hojas de cálculo

Antes de comenzar

Este es el quinto codelab de la playlist de Fundamentos de Apps Script con Hojas de cálculo de Google. Antes de comenzar este codelab, asegúrate de completar los codelabs anteriores:

  1. Macros y funciones personalizadas
  2. Hojas de cálculo, hojas y rangos
  3. Trabaja con datos
  4. Formato de datos

Requisitos

  • Conocimiento de los temas básicos de Apps Script que se exploraron en los codelabs anteriores de esta playlist
  • Conocimientos básicos sobre el editor de Apps Script
  • Conocimientos básicos de Hojas de cálculo de Google
  • Capacidad de leer la notación A1 de Hojas de cálculo
  • Conocimientos básicos de JavaScript y su clase String

2. Configurar

Antes de continuar, necesitas una hoja de cálculo con algunos datos. Al igual que antes, proporcionamos una hoja de datos que puedes copiar para estos ejercicios. Debes seguir estos pasos:

  1. Haz clic en este vínculo para copiar la hoja de datos y, luego, en Crear una copia. La nueva hoja de cálculo se colocará en tu carpeta de Google Drive y se llamará "Copia de Dates and USD Exchange Rates".
  2. Haz clic en el título de la hoja de cálculo y cámbialo de "Copia de Fechas y tipos de cambio en USD" a "Fechas y tipos de cambio en USD". Tu hoja debería verse así, con información básica sobre los diferentes tipos de cambio del dólar estadounidense en diferentes fechas:

45a3e8814ecb07fc.png

  1. Para abrir el editor de secuencias de comandos, haz clic en Extensiones> Apps Script.

Para ahorrarte tiempo, incluimos un poco de código para configurar un menú personalizado en esta hoja de cálculo. Es posible que hayas visto aparecer el menú cuando se abrió tu copia de la hoja de cálculo:

9b9caf6c1e9de34b.png

Con esta hoja de cálculo y este proyecto, ya puedes comenzar el codelab. Pasa a la siguiente sección para comenzar a aprender sobre los gráficos y los activadores basados en el tiempo.

3. Crea un gráfico en Hojas de cálculo con Apps Script

Supongamos que deseas diseñar un gráfico específico para visualizar un conjunto de datos. De hecho, puedes usar Apps Script para crear, editar e insertar gráficos en Hojas de cálculo de Google. Cuando un gráfico se incluye en una hoja de cálculo, se denomina gráfico incorporado.

Los gráficos se usan para visualizar una o más series de datos. En el caso de los gráficos incorporados, los datos que presentan suelen provenir de la hoja de cálculo. Por lo general, cuando actualizas los datos en la hoja de cálculo, Hojas de cálculo también actualiza el gráfico automáticamente.

Puedes usar Apps Script para crear gráficos personalizados integrados desde cero o para actualizar gráficos existentes. En esta sección, se presentan los conceptos básicos para crear gráficos incorporados en Hojas de cálculo con Apps Script y el servicio Spreadsheet.

Implementación

En tu copia de la hoja de cálculo de datos, el conjunto de datos "Fechas y tipos de cambio" muestra los tipos de cambio (para 1 dólar estadounidense) de diferentes monedas en diferentes fechas. Implementarás una función de Apps Script que crea un gráfico para visualizar parte de estos datos.

Debes seguir estos pasos:

  1. En el editor de Apps Script, agrega la siguiente función al final de la secuencia de comandos Code.gs de tu proyecto de secuencia de comandos, después de la función onOpen():
/**
 * Creates and inserts an embedded
 * line chart into the active sheet.
 */
function createEmbeddedLineChart() {
  var sheet = SpreadsheetApp.getActiveSheet();
  var chartDataRange = sheet.getRange(
    'Dates and USD Exchange Rates dataset!A2:F102');
  var hAxisOptions = {
    slantedText: true,
    slantedTextAngle: 60,
    gridlines: {
      count: 12
    }
  };
  
  var lineChartBuilder = sheet.newChart().asLineChart();
  var chart = lineChartBuilder
    .addRange(chartDataRange)
    .setPosition(5, 8, 0, 0)
    .setTitle('USD Exchange rates')
    .setNumHeaders(1)
    .setLegendPosition(Charts.Position.RIGHT)
    .setOption('hAxis', hAxisOptions)
    .setOption("useFirstColumnAsDomain", true)
    .build();
 
  sheet.insertChart(chart);  
}
  1. Guarda tu proyecto de secuencia de comandos.

Revisión de código

El código que agregaste implementa la función a la que llama el elemento de menú Chart "Dates and USD Exchange Rates dataset" para crear un gráfico de líneas básico. Revisemos el código.

Las primeras líneas configuran las siguientes tres variables:

  • sheet: Es una referencia a la hoja activa actual.
  • chartDataRange: Es el período de datos que queremos visualizar. El código usa la notación A1 para especificar que el rango abarca las celdas de la A2 a la F102 en la hoja llamada Conjunto de datos de fechas y tipos de cambio en USD. Si nombramos la hoja de forma específica, nos aseguramos de que el elemento de menú funcione incluso si hay otra hoja activa, ya que el rango siempre abarca la posición de los datos. Comenzar en la fila 2 significa que incluiremos los encabezados de columna y solo trazaremos las 100 fechas (filas) más recientes.
  • hAxisOptions: Es un objeto básico de JavaScript que incluye información de configuración que el código usa para configurar la apariencia del eje horizontal. Específicamente, establecen las etiquetas de texto del eje horizontal con una inclinación de 60 grados y la cantidad de líneas de cuadrícula verticales en 12.

La siguiente línea crea un objeto generador de gráficos de líneas. Los gráficos incorporados en Apps Script se construyen con un patrón de diseño de compilador. Una explicación completa de este patrón de diseño está fuera del alcance de este codelab, por lo que, por ahora, solo debes comprender que el servicio Spreadsheet proporciona varias clases EmbeddedChartBuilder. Para crear un gráfico, tu código primero crea un objeto compilador de gráficos incorporado, usa sus métodos para definir la configuración del gráfico y, luego, llama a un método build() para crear el objeto EmbeddedChart final. Tu código nunca modifica el objeto EmbeddedChart directamente, ya que toda la configuración del gráfico se administra a través de las clases de compilador.

El servicio de Hojas de cálculo proporciona una clase superior EmbeddedChartBuilder y varias clases de compilador secundarias (como EmbeddedLineChartBuilder) que heredan de ella. Las clases secundarias permiten que Apps Script proporcione los métodos de configuración de gráficos de los compiladores que solo se aplican a ciertos tipos de gráficos. Por ejemplo, la clase EmbeddedPieChartBuilder proporciona un método set3D() que solo se aplica a los gráficos circulares.

En tu código, esta línea crea la variable del objeto compilador lineChartBuilder:

var lineChartBuilder = sheet.newChart().asLineChart();

El código llama al método Sheet.newChart() para crear un objeto EmbeddedChartBuilder y, luego, usa EmbeddedChartBuilder.asLineChart() para establecer el tipo de compilador en EmbeddedLineChartBuilder.

Luego, el código compila el gráfico con lineChartBuilder. Esta parte del código es solo una serie de llamadas a métodos para definir la configuración del gráfico, seguida de una llamada a build() para crear el gráfico. Como viste en codelabs anteriores, el código usa el encadenamiento de métodos para que sea legible. Esto es lo que hacen las llamadas al método:

Por último, el código llama a Sheet.insertChart(chart) para colocar el gráfico compilado en la hoja activa.

Resultados

Para ver tu función de formato en acción, haz lo siguiente:

  1. Si aún no lo hiciste, guarda tu proyecto de secuencia de comandos en el editor de Apps Script.
  2. Haz clic en el elemento de menú Present dataset > Chart "Dates and USD Exchange Rates dataset".

Ahora, tu secuencia de comandos coloca un gráfico nuevo a la derecha de tus datos:

bbf856699b6d2b45.gif

¡Felicitaciones! Compilaste un gráfico de líneas incorporado con Apps Script. En la siguiente sección, aprenderás a exportar tu gráfico a Presentaciones de Google.

4. Exporta tus gráficos a Presentaciones

Una de las grandes fortalezas de Apps Script es que te permite transferir datos fácilmente de una aplicación de Google Workspace a otra. La mayoría de estas aplicaciones tienen un servicio de Apps Script dedicado, similar al servicio de hojas de cálculo. Por ejemplo, Gmail tiene el servicio de Gmail, Documentos de Google tiene el servicio de Documentos y Presentaciones de Google tiene el servicio de Presentaciones. Con todos estos servicios integrados, puedes extraer datos de una aplicación, procesarlos y escribir el resultado en otra.

En esta sección, aprenderás a exportar todos los gráficos incorporados en una hoja de cálculo de Google a una nueva presentación de Presentaciones de Google. También verás dos formas de mostrar los mensajes personalizados de los usuarios en Hojas de cálculo.

Implementación

Aquí implementarás la función que llama el elemento de menú Present dataset > Export charts to Slides. Debes seguir estos pasos:

  1. En el editor de Apps Script, agrega la siguiente función al final de la secuencia de comandos Code.gs de tu proyecto de secuencia de comandos, después de la función createEmbeddedLineChart():
/**
 * Create a Slides presentation and export
 * all the embedded charts in this spreadsheet
 * to it, one chart per slide.
 */
function exportChartsToSlides() {
  var ss = SpreadsheetApp.getActiveSpreadsheet();
  
  // Fetch a list of all embedded charts in this
  // spreadsheet.
  var charts = [];
  var sheets = ss.getSheets();
  for (var i = 0; i < sheets.length; i++) {
    charts = charts.concat(sheets[i].getCharts());
  }
  
  // If there aren't any charts, display a toast
  // message and return without doing anything
  // else.
  if (charts.length == 0) {
    ss.toast('No charts to export!');
    return;
  }
  
  // Create a Slides presentation, removing the default
  // title slide.
  var presentationTitle =
    ss.getName() + " Presentation";
  var slides = SlidesApp.create(presentationTitle);
  slides.getSlides()[0].remove();  
  
  // Add charts to the presentation, one chart per slide.
  var position = {left: 40, top: 30};
  var size = {height: 340, width: 430};
  for (var i = 0; i < charts.length; i++) {
    var newSlide = slides.appendSlide();
    newSlide.insertSheetsChart(
      charts[i],
      position.left,
      position.top,
      size.width,
      size.height);   
  }
  
  // Create and display a dialog telling the user where to
  // find the new presentation.
  var slidesUrl = slides.getUrl();
  var html = "<p>Find it in your home Drive folder:</p>"
      + "<p><a href=\"" + slidesUrl + "\" target=\"_blank\">"
      + presentationTitle + "</a></p>";
  
  SpreadsheetApp.getUi().showModalDialog(
    HtmlService.createHtmlOutput(html)
      .setHeight(120)
      .setWidth(350),
      "Created a presentation!"
  );
}
  1. Guarda tu proyecto de secuencia de comandos.

Revisión de código

Este código podría ser más corto de lo que esperabas. Revisemos lo que hace dividiendo el código en cinco secciones:

1: Obtén los gráficos

Las primeras líneas buscan en la hoja de cálculo activa todos los gráficos incorporados y los recopilan en el array charts. Estas líneas usan los métodos Spreadsheet.getSheets() y Sheet.getCharts() para obtener listas de hojas y gráficos. El método Array.concat() de JavaScript se usa para agregar la lista de gráficos de cada hoja en charts.

2: Verifica que haya gráficos para exportar

El código verifica si hay gráficos para exportar. Queremos evitar crear una presentación en blanco, por lo que, si no hay gráficos, el código crea un mensaje emergente con Spreadsheet.toast(message). Este es un pequeño diálogo de "vista previa" que aparece en la esquina inferior derecha de Hojas de cálculo, permanece durante unos segundos y, luego, desaparece:

db7e87dcb8010bef.gif

Si no hay gráficos para exportar, el código crea el mensaje de notificación y sale sin hacer nada más. Si hay gráficos para exportar, el código continúa creando una presentación en las siguientes líneas.

3: Crea una presentación

La variable presentationTitle se crea para contener el nombre del archivo de la nueva presentación. Se establece como el nombre de la hoja de cálculo, con " Presentation" concatenado al final. Luego, el código llama al método del servicio de Slides SlidesApp.create(name) para crear una presentación.

Las presentaciones nuevas se crean con una sola diapositiva en blanco. No queremos eso en nuestra presentación, por lo que el código lo quita con Presentation.getSlides() y Slide.remove().

4: Exporta los gráficos

En la siguiente sección, el código define los objetos position y size de JavaScript para establecer dónde se colocarán los gráficos importados en la diapositiva y qué tamaño tendrá el gráfico (en píxeles).

El código itera sobre cada gráfico de la lista de gráficos. Para cada gráfico, se crea un newSlide con Presentation.appendSlide(), lo que agrega la diapositiva al final de la presentación. El método Slide.insertSheetsChart(sourceChart, left, top, width, height) se usa para importar el gráfico a la diapositiva con los parámetros position y size especificados.

5: Comparte la ubicación de la presentación

Por último, el código debe indicarle al usuario dónde se encuentra la nueva presentación, de preferencia con un vínculo en el que pueda hacer clic para abrirla. Para ello, el código usa el HTML servicio de Apps Script para crear un diálogo modal personalizado. Los diálogos modales (también conocidos como diálogos personalizados en Apps Script) son ventanas que aparecen sobre la interfaz de Hojas de cálculo. Cuando se muestran, los diálogos personalizados impiden que el usuario interactúe con Hojas de cálculo.

Para crear un diálogo personalizado, el código necesita el HTML que define su contenido. Esto se proporciona en la variable html. El contenido incluye un párrafo corto y un hipervínculo. El hipervínculo es la variable presentationTitle, vinculada a la URL de la presentación proporcionada por Presentation.getUrl(). El hipervínculo también usa el atributo target="_blank" para que la presentación se abra en una pestaña nueva del navegador, en lugar de dentro del diálogo.

El método HtmlService.createHtmlOutput(html) analiza el código HTML en un objeto HtmlOutput. El objeto HtmlOutput permite que el código establezca el tamaño del diálogo personalizado con HtmlOutput.setHeight(height) y HtmlOutput.setWidth(width).

Una vez que se crea htmlOutput, el código usa el método Ui.showModalDialog(htmlOutput, title) para mostrar el diálogo con el título determinado.

Resultados

Ahora que implementaste el segundo elemento de menú, puedes verlo en acción. Para probar la función exportChartsToSlides(), haz lo siguiente:

  1. Si aún no lo hiciste, guarda tu proyecto de secuencia de comandos en el editor de Apps Script.
  2. Abre tu hoja de cálculo y haz clic en el elemento de menú Present dataset > Chart "Dates and USD Exchange Rates dataset" para crear un gráfico que se pueda exportar. Aparecerá anclado a la celda H5 de la hoja activa.
  3. Haz clic en el elemento de menú Presentar conjunto de datos > Exportar gráficos a Presentaciones. Es posible que se te solicite que vuelvas a autorizar la secuencia de comandos.
  4. Deberías ver que tu secuencia de comandos procesa la solicitud y muestra el diálogo personalizado.
  5. Para abrir la nueva presentación de Presentaciones, haz clic en el vínculo Presentación de tipos de cambio en USD y fechas:

51326ceaeb3e49b2.gif

Si quieres, también puedes agregar más gráficos a tu hoja de cálculo y volver a seleccionar el elemento de menú para crear una presentación con varias diapositivas.

Ahora puedes exportar los gráficos creados en Hojas de cálculo a una presentación de Presentaciones. También puedes escribir código para crear un diálogo personalizado.

Completaste el último ejercicio de este codelab. Ve a la siguiente sección para revisar lo que aprendiste.

5. Conclusión

¡Felicitaciones! Completaste este codelab y toda la playlist de codelabs de Aspectos básicos de Apps Script con Hojas de cálculo de Google. Puedes usar los principios que se enseñan en esta playlist para ampliar tu experiencia con Hojas de cálculo y explorar las capacidades de Apps Script.

¿Te resultó útil este codelab?

Sí No

Qué aprendiste

  • Cómo compilar un gráfico de líneas incorporado con Apps Script
  • Cómo presentar mensajes emergentes y diálogos personalizados a un usuario en Hojas de cálculo
  • Cómo exportar un gráfico a una nueva presentación de Presentaciones

¿Qué sigue?

Completaste esta playlist correctamente. Sin embargo, aún hay más para aprender sobre Apps Script.

Consulta los siguientes recursos:

¡Que disfrutes la escritura de secuencias de comandos!

¿Te resultó útil esta playlist de codelabs?

Sí No

¿Te gustaría ver más codelabs de Apps Script en el futuro?

Sí No