Una aplicación útil de la API de Google Slides es combinar información de una o más fuentes de datos en una presentación con plantillas.
En esta página, se describe cómo puedes tomar datos de una fuente externa e insertarlos en una presentación de plantilla existente. El concepto es similar al de una combinación de correspondencia con un procesador de texto y una hoja de cálculo.
Este enfoque es útil por varios motivos:
Los diseñadores pueden ajustar el diseño de una presentación con facilidad usando el editor de Presentaciones de Google. Esto es mucho más fácil que ajustar los parámetros en tu app para establecer el diseño de la diapositiva renderizada.
Separar el contenido de la presentación es un principio de diseño conocido con muchos beneficios.
Una receta básica
A continuación, se muestra un ejemplo de cómo puedes usar la API de Slides para combinar datos en una presentación:
Crea tu presentación como quieras que se vea usando contenido de marcador de posición para ayudarte con el diseño.
Para cada elemento de contenido que insertarás, reemplaza el contenido del marcador de posición por una etiqueta. Las etiquetas son cuadros de texto o formas con una cadena única. Asegúrate de usar cadenas que no es probable que ocurran normalmente. Por ejemplo,
{{account-holder-name}}
podría ser una buena etiqueta.En tu código, usa la API de Google Drive para crear una copia de la presentación.
En tu código, usa el método
batchUpdate
de la API de Slides, con un conjunto de solicitudes dereplaceAllText
, para realizar todas las sustituciones de texto en la presentación. Usa solicitudes dereplaceAllShapesWithImage
para realizar sustituciones de imágenes en toda la presentación.
Una vez que hayas creado una presentación con etiquetas, asegúrate de hacer una copia y usar la API de Slides para manipularla. No uses la API de Slides para manipular tu copia principal de la "plantilla".
En las siguientes secciones, se incluyen fragmentos de código que ilustran parte de este proceso. También puedes mirar el video anterior para ver un ejemplo completo (en Python) que combina varios de los conceptos de las secciones individuales que se muestran a continuación.
Combinar texto
Puedes usar una solicitud replaceAllText
para reemplazar todas las instancias de una cadena de texto determinada en una presentación por texto nuevo. En el caso de las combinaciones, esto es más simple que buscar y reemplazar cada instancia de texto de forma individual. Una de las razones por las que este es el enfoque más sofisticado es que los IDs de los elementos de la página son difíciles de predecir, en especial a medida que los colaboradores refinan y mantienen la presentación de la plantilla.
Ejemplo
En este ejemplo, se usa la API de Drive para copiar una presentación de plantilla y crear una instancia nueva de la presentación. Luego, usa la API de Google Sheets para leer datos de una hoja de cálculo de Sheets y, por último, usa la API de Slides para actualizar la nueva presentación.
En el ejemplo, se toman datos de 3 celdas de una fila de un rango con nombre en la hoja de cálculo. Luego, sustituye esos datos en la presentación dondequiera que aparezcan las cadenas {{customer-name}}
, {{case-description}}
o {{total-portfolio}}
.
Apps Script
Go
Java
JavaScript
Node.js
PHP
Python
Ruby
Combina imágenes
También puedes combinar imágenes en tu presentación con una solicitud replaceAllShapesWithImage
. Esta solicitud reemplaza todas las instancias de formas que contienen la cadena de texto proporcionada por la imagen proporcionada. La solicitud posiciona y ajusta automáticamente la imagen para que quepa dentro de los límites de la forma de la etiqueta y, al mismo tiempo, conserva la relación de aspecto de la imagen.
Ejemplo
En este ejemplo, se usa la API de Google Drive para copiar una presentación de plantilla y crear una instancia nueva de la presentación. Luego, usa la API de Slides para buscar cualquier forma con el texto {{company-logo}}
y reemplazarlo por una imagen del logotipo de la empresa. La solicitud también reemplaza cualquier forma con el texto {{customer-graphic}}
por una imagen diferente.
Apps Script
Go
Java
JavaScript
Node.js
PHP
Python
Ruby
Reemplaza instancias específicas de cuadros de texto o imágenes
Las solicitudes replaceAllText
y replaceAllShapesWithImage
son útiles para reemplazar etiquetas en toda una presentación, pero, a veces, solo necesitas reemplazar elementos según otros criterios, como estar ubicados en una diapositiva específica.
En estos casos, debes recuperar los IDs de las formas de etiquetas que deseas reemplazar. En el caso de los reemplazos de texto, borra el texto existente en esas formas y, luego, inserta el texto nuevo (consulta el ejemplo Edita texto en una forma específica).
Los reemplazos de imágenes son más complejos. Para combinar una imagen, debes hacer lo siguiente:
- Obtén el ID de la forma de la etiqueta.
- Copia la información de tamaño y transformación de la etiqueta.
- Agrega tu imagen a la página con la información de tamaño y transformación.
- Borra la forma de la etiqueta.
Preservar la relación de aspecto de la imagen mientras se ajusta su escala al tamaño deseado puede requerir cierto cuidado, como se describe en la siguiente sección. Consulta también este ejemplo: Reemplaza una etiqueta de forma por una imagen.
Conservar la relación de aspecto
Cuando creas imágenes con la API de Slides, los ajustes de proporción se basan solo en el tamaño de la imagen, no en los datos de tamaño y transformación. Los datos de tamaño que proporcionas en la solicitud createImage
se consideran el tamaño deseado de la imagen. La API ajusta la relación de aspecto de la imagen a este tamaño deseado y, luego, aplica la transformación proporcionada.
Cuando reemplazas una etiqueta por una imagen, conservas la relación de aspecto de la imagen configurando su tamaño y escala de la siguiente manera:
- width: Se establece en el producto de
width
yscaleX
de la etiqueta. - height: Se establece en el producto de
height
yscaleY
de la etiqueta. - scale_x: Se configura como
1
- scale_y: Se configura como
1
Esto hace que la API de Slides ajuste la imagen según la relación de aspecto de acuerdo con el tamaño visual de la etiqueta, en lugar de su tamaño sin escalar (consulta Cómo reemplazar una etiqueta de forma por una imagen).
Establecer los parámetros de escalamiento en 1
evita que la imagen se escale dos veces.
Esta disposición garantiza que se conserve la relación de aspecto de la imagen y evita que esta supere el tamaño de la forma de la etiqueta. La imagen tiene el mismo punto central que la forma de la etiqueta.
Administrar plantillas
En el caso de las presentaciones de plantillas que la aplicación define y posee, crea la plantilla con una cuenta dedicada que represente la aplicación. Las cuentas de servicio son una buena opción y evitan complicaciones con las políticas de Google Workspace que restringen el uso compartido.
Cuando crees instancias de presentaciones a partir de plantillas, siempre usa credenciales de usuario final. Esto les brinda a los usuarios control total sobre la presentación resultante y evita problemas de escalamiento relacionados con los límites por usuario en Google Drive.
Para crear una plantilla con una cuenta de servicio, sigue estos pasos con las credenciales de la aplicación:
- Crea una presentación con presentations.create en la API de Slides.
- Actualiza los permisos para permitir que los destinatarios de la presentación la lean con permissions.create en la API de Drive.
- Actualiza los permisos para permitir que los autores de plantillas escriban en él con permissions.create en la API de Drive.
- Edita la plantilla según sea necesario.
Para crear una instancia de la presentación, sigue estos pasos con las credenciales del usuario:
- Crea una copia de la plantilla con files.copy en la API de Drive.
- Reemplaza valores con presentation.batchUpdate en la API de Slides.