Aspectos básicos de Apps Script con Hojas de cálculo de Google n.o 5: Gráfico y presentación de datos en Presentaciones

1. Introducción

Te damos la bienvenida a la quinta parte de la lista de reproducción del codelab Aspectos básicos de Apps Script con Hojas de cálculo de Google. En este codelab, aprenderás a usar el servicio de hoja de cálculo en Apps Script para graficar un conjunto de datos. También aprenderás a usar el servicio de Presentaciones para exportar el gráfico a una presentación nueva 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 un nuevo archivo de Presentaciones
  • Cómo presentarle diálogos al usuario en Hojas de cálculo

Antes de comenzar

Este es el quinto codelab en la lista de reproducción Aspectos básicos 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 de cálculo y rangos
  3. Cómo trabajar con datos
  4. Formato de datos

Requisitos

  • Comprender los temas básicos de Apps Script que se analizaron en los codelabs anteriores de esta lista de reproducción
  • Conocimientos básicos sobre el editor de Apps Script
  • Conocimientos básicos de Hojas de cálculo de Google
  • Capacidad para leer Hojas de cálculo A1 Notation
  • Conocimientos básicos sobre 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. Sigue estos pasos:

  1. Haga clic en este vínculo para copiar la hoja de datos y, luego, en Crear una copia. La nueva hoja de cálculo se guarda en tu carpeta de Google Drive y se llama "Copia de fechas" y "Tasas de cambio".
  2. Haz clic en el título de la hoja de cálculo y cámbialo de "Tasas de cambio de USD y de copia" a "Tasas de cambio de USD y dólares". La hoja debería verse de la siguiente manera, con información básica sobre los diferentes tipos de cambio de dólares estadounidenses en diferentes fechas:

45a3e8814ecb07fc.png

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

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

9b9caf6c1e9de34b.png

Con esta hoja de cálculo y proyecto, estarás listo para comenzar el codelab. Avance a la siguiente sección para comenzar a aprender sobre los gráficos y activadores activadores en el tiempo.

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

Supongamos que quiere diseñar un gráfico específico para visualizar un conjunto de datos. Puede usar Apps Script para compilar, editar e insertar gráficos en Hojas de cálculo de Google. Cuando un gráfico se encuentra dentro de 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 suelen provenir provienen de la hoja de cálculo. Por lo general, si se actualizan los datos de la hoja de cálculo, Hojas de cálculo también se actualiza automáticamente.

Puede usar Apps Script para crear gráficos incorporados personalizados desde cero o actualizar los gráficos existentes. En esta sección, se presentan los conceptos básicos para compilar 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 las tasas 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.

Sigue estos pasos:

  1. En el editor de Apps Script, agrega la siguiente función al final de la secuencia de comandos Code.gs del proyecto de la 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. Guarde el proyecto de la secuencia de comandos.

Revisión de código

El código que agregaste implementa la función a la que llama el conjunto de datos del menú Gráficos & Fechas y tasas de cambio de USD para crear un gráfico de líneas básico. Revisemos el código.

En las primeras líneas, se configuran las siguientes tres variables:

  • sheet: es una referencia a la hoja activa actual.
  • chartDataRange: Es el rango de datos que queremos visualizar. El código usa la notación A1 para especificar que el rango abarque las celdas A2 a F102 de la hoja denominada Fechas y conjunto de datos de tasas de cambio de USD. Al nombrar específicamente la hoja, nos aseguramos de que el elemento de menú funcione incluso si una hoja diferente está activa, ya que el rango siempre cubre la posición de los datos. A partir de la fila 2, se incluirán los encabezados de las columnas y solo representaremos las 100 fechas más recientes (filas).
  • hAxisOptions: Es un objeto de JavaScript básico que incluye información de configuración que usa el código para configurar la apariencia del eje horizontal. Específicamente, fijan las etiquetas del texto del eje horizontal en una inclinación de 60 grados y establecen el número de líneas de cuadrícula verticales en 12.

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

El servicio de Hojas de cálculo proporciona una clase superior EmbeddedChartBuilder y varias clases de compiladores secundarios (como EmbeddedLineChartBuilder) que se heredan de ella. Las clases secundarias permiten que Apps Script proporcione los métodos de configuración de gráficos de 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 de objeto compilador lineChartBuilder:

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

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

Luego, el código compilará 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 encadenamiento de métodos para mantenerlo legible. Esto es lo que hacen las llamadas de 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 la función de formato en acción, haz lo siguiente:

  1. Si aún no lo hiciste, guarda el proyecto de la secuencia de comandos en el editor de Apps Script.
  2. Haz clic en el elemento de menú Presente el conjunto de datos (Chart data & chart).

Su secuencia de comandos ahora colocará un nuevo gráfico a la derecha de sus datos:

bbf856699b6d2b45.gif

Felicitaciones. Creaste un gráfico de líneas incorporado con Apps Script. En la siguiente sección, se explica cómo exportar el gráfico a Presentaciones de Google.

4. Exporta tus gráficos a Presentaciones

Una de las grandes ventajas de Apps Script es que le permite mover datos de una aplicación de Google Workspace a otra con facilidad. La mayoría de estas aplicaciones tienen un servicio exclusivo de Apps Script, similar al servicio de hoja de cálculo. Por ejemplo, Gmail tiene el servicio de Gmail, Documentos de Google tiene el servicio Documento y Presentaciones de Google tiene el servicio Presentaciones. Con todos estos servicios integrados, puede 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 de una hoja de cálculo de Google a un nuevo archivo de Presentaciones de Google. También verás dos formas de mostrar los mensajes personalizados a los usuarios en Hojas de cálculo.

Implementación

Aquí, implementarás la función a la que llama el elemento de menú Presentar conjunto de datos & exportar gráficos a Presentaciones. Sigue estos pasos:

  1. En el editor de Apps Script, agrega la siguiente función al final de la secuencia de comandos Code.gs del proyecto de la 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. Guarde el proyecto de la secuencia de comandos.

Revisión de código

Es posible que este código sea más corto de lo que esperabas. Para ver lo que hace, dividamos el código en cinco secciones:

1: Obtén los gráficos

Las primeras líneas buscan la hoja de cálculo activa para buscar todos los gráficos incorporados y recopilarlos 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 a charts la lista de gráficos de cada hoja.

2. Verifique si hay gráficos para exportar

El código verifica si hay gráficos para exportar. Queremos evitar que se realice una presentación en blanco, por lo que, si no hay gráficos, el código crea un mensaje de aviso con Spreadsheet.toast(message). Este es un pequeño diálogo 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 aviso y sale sin hacer nada más. Si hay gráficos para exportar, el código seguirá creando una presentación en las próximas líneas.

3: Crea una presentación

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

Las presentaciones nuevas se crean con una sola diapositiva en blanco. Como no queremos eso en nuestra presentación, 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 el position y el size de los objetos de JavaScript para establecer dónde se colocarán los gráficos importados en la diapositiva y qué tan grande será el gráfico (en píxeles).

El código se repite indefinidamente en cada gráfico de la lista de gráficos. Para cada gráfico, se crea un newSlide con Presentation.appendSlide() y se 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 las position y size especificadas.

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

Por último, el código debe indicarle al usuario dónde se encuentra la presentación nueva, preferentemente con un vínculo en el que puede hacer clic para abrirla. Para hacerlo, el código usa el HTML servicio de Apps Script a fin de crear un diálogo modal personalizado. Los diálogos modales (también conocidos como diálogos personalizados en Apps Script) son ventanas que aparecen en 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 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 nueva pestaña del navegador y no en el diálogo.

El método HtmlService.createHtmlOutput(html) analiza el 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 del menú, podrás verlo en acción. Para probar la función exportChartsToSlides(), haz lo siguiente:

  1. Si aún no lo hiciste, guarda el proyecto de la secuencia de comandos en el editor de Apps Script.
  2. Abre la hoja de cálculo y haz clic en el elemento de menú Presentar conjunto de datos & gráfico; fechas y tipos de cambio de USD para crear un gráfico para exportar. Aparecerá como anclada en la celda H5 de la hoja activa.
  3. Haga clic en el elemento de menú Presentar conjunto de datos > Exportar gráficos a Presentaciones. Es posible que se le solicite que vuelva a autorizar la secuencia de comandos.
  4. Debería ver la secuencia de comandos que procesa la solicitud y muestra el diálogo personalizado.
  5. Para abrir el nuevo archivo de Presentaciones, haz clic en el vínculo Fechas y presentación de los tipos de cambio de USD:

51326ceaeb3e49b2.gif

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

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

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

5. Conclusión

¡Felicitaciones! Completaste este codelab y la lista de reproducción sobre aspectos básicos de Apps Script con Hojas de cálculo de Google. Puede usar los principios que se enseñan en esta lista de reproducción para extender la experiencia en Hojas de cálculo y explorar las funciones 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 de aviso y diálogos personalizados a un usuario en Hojas de cálculo
  • Cómo exportar un gráfico a una nueva presentación de Google

¿Qué sigue?

Completaste correctamente esta lista de reproducción. Sin embargo, todavía hay más información para aprender sobre Apps Script.

Consulta estos recursos:

¡Feliz secuencia de comandos!

¿Te pareció útil esta lista de reproducción de codelab?

Sí No

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

Sí No