Un'applicazione utile dell'API Presentazioni Google è l'unione di informazioni provenienti da una o più origini dati in una presentazione basata su modelli.
Questa pagina illustra come estrarre i dati da un'origine esterna e inserirli in una presentazione di modelli esistente. Il concetto è simile a quello di un mail merge utilizzando un elaboratore di testi e un foglio di lavoro.
Questo approccio è utile per diversi motivi:
Per i designer è facile perfezionare il design di una presentazione utilizzando l'editor di Presentazioni Google. È molto più facile che regolare i parametri nella tua app per impostare il design della diapositiva visualizzato.
Separare i contenuti dalla presentazione è un principio di design ben noto con molti vantaggi.
Una ricetta di base
Ecco un esempio di come utilizzare l'API Presentazioni per unire i dati in una presentazione:
Crea la presentazione come vuoi che venga visualizzata utilizzando contenuti segnaposto per aiutarti con il design.
Per ogni elemento di contenuto che inserirai, sostituisci il contenuto del segnaposto con un tag. I tag sono caselle di testo o forme con una stringa univoca. Assicurati di utilizzare stringhe che difficilmente si verificano normalmente. Ad esempio,
{{account-holder-name}}
potrebbe essere un buon tag.Nel codice, utilizza l'API Google Drive per creare una copia della presentazione.
Nel codice, utilizza il metodo
batchUpdate
dell'API Slides, con un insieme direplaceAllText
richieste, per eseguire tutte le sostituzioni di testo nella presentazione. Utilizza le richiestereplaceAllShapesWithImage
per eseguire sostituzioni di immagini in tutta la presentazione.
Dopo aver creato una presentazione con i tag, assicurati di farne una copia e di utilizzare l'API Slides per manipolarla. Non utilizzare l'API di Presentazioni per manipolare la copia principale del "modello".
Le sezioni seguenti includono snippet di codice che illustrano alcuni aspetti di questa procedura. Puoi anche guardare il video qui sopra per vedere un esempio completo (in Python) che combina diversi concetti delle singole sezioni riportate di seguito.
Unisci testo
Puoi utilizzare una richiesta replaceAllText
per sostituire tutte le istanze di una determinata stringa di testo in una presentazione con nuovo testo. Per le unioni, questa operazione è più semplice rispetto a trovare e sostituire singolarmente ogni occorrenza di testo. Uno dei motivi per cui si tratta dell'approccio più sofisticato è che gli ID degli elementi della pagina sono difficili da prevedere, soprattutto man mano che i collaboratori perfezionano e gestiscono la presentazione del modello.
Esempio
Questo esempio utilizza l'API Drive per copiare una presentazione modello, creando una nuova istanza della presentazione. Poi utilizza l'API Fogli Google per leggere i dati da un foglio di lavoro di Fogli e infine l'API Presentazioni per aggiornare la nuova presentazione.
L'esempio prende i dati da 3 celle in una riga di un intervallo denominato nel foglio di lavoro. Poi sostituisce questi dati nella presentazione ovunque si verifichino le stringhe {{customer-name}}
, {{case-description}}
o {{total-portfolio}}
.
Apps Script
Vai
Java
JavaScript
Node.js
PHP
Python
Ruby
Unisci immagini
Puoi anche unire le immagini alla presentazione utilizzando una richiesta replaceAllShapesWithImage
. Questa richiesta sostituisce tutte le istanze di forme contenenti la
stringa di testo fornita con l'immagine fornita. La richiesta posiziona e ridimensiona automaticamente l'immagine in modo che rientri nei limiti della forma del tag, mantenendo al contempo le proporzioni dell'immagine.
Esempio
Questo esempio utilizza l'API Google Drive per copiare una presentazione modello, creando
una nuova istanza della presentazione. Poi utilizza l'API Slides per trovare qualsiasi forma con il testo {{company-logo}}
e sostituirla con un'immagine del logo dell'azienda. La richiesta sostituisce inoltre qualsiasi forma con il testo {{customer-graphic}}
con un'immagine diversa.
Apps Script
Vai
Java
JavaScript
Node.js
PHP
Python
Ruby
Sostituire istanze specifiche di caselle di testo o immagini
Le richieste replaceAllText
e replaceAllShapesWithImage
sono utili per sostituire i tag in una presentazione, ma
a volte è sufficiente sostituire gli elementi in base ad altri criteri, come
la posizione in una diapositiva specifica.
In questi casi, devi recuperare gli ID delle forme dei tag che vuoi sostituire. Per le sostituzioni di testo, elimina il testo esistente nelle forme e inserisci il nuovo testo (vedi l'esempio Modificare il testo in una forma specificata).
Le sostituzioni delle immagini sono più complesse. Per unire un'immagine, devi:
- Recupera l'ID della forma del tag.
- Copia le informazioni sulle dimensioni e sulle trasformazioni dal tag.
- Aggiungi l'immagine alla pagina utilizzando le informazioni sulle dimensioni e sulla trasformazione.
- Elimina la forma del tag.
Mantenere le proporzioni dell'immagine durante il ridimensionamento alle dimensioni desiderate potrebbe richiedere un po' di attenzione, come descritto nella sezione seguente. Consulta anche questo esempio: Sostituisci un tag forma con un'immagine.
Mantieni le proporzioni
Quando crei immagini utilizzando l'API Slides, le adattamenti alle proporzioni si basano solo sulle dimensioni dell'immagine, non sulle dimensioni e sui dati di trasformazione. I dati sulle dimensioni forniti
nella richiesta createImage
sono considerati le dimensioni desiderate dell'immagine. L'API adatta le proporzioni dell'immagine alle dimensioni desiderate, quindi applica la trasformazione fornita.
Quando sostituisci un tag con un'immagine, mantieni invariato il formato dell'immagine impostando le dimensioni e la scalatura come segue:
- width: impostato sul prodotto di
width
escaleX
del tag - height: impostato sul prodotto di
height
escaleY
del tag - scale_x: impostato su
1
- scale_y: impostato su
1
Di conseguenza, l'API Slides adatta l'immagine alle proporzioni in base alle dimensioni visualizzate del tag anziché alle dimensioni non scalate (vedi Sostituisci un tag forma con un'immagine).
L'impostazione dei parametri di ridimensionamento su 1
impedisce il ridimensionamento
dell'immagine.
Questa disposizione garantisce che le proporzioni dell'immagine vengano conservate e impedisce all'immagine di superare le dimensioni della forma del tag. L'immagine ha lo stesso punto di centro della forma del tag.
Gestisci modelli
Per le presentazioni dei modelli definiti e di proprietà dell'applicazione, crea il modello utilizzando un account dedicato che rappresenta l'applicazione. Gli account di servizio sono una buona scelta ed evitano complicazioni con le norme di Google Workspace che limitano la condivisione.
Quando crei istanze di presentazioni da modelli, utilizza sempre le credenziali dell'utente finale. In questo modo, gli utenti hanno il pieno controllo sulla presentazione risultante e si evitano i problemi di scalabilità relativi ai limiti per utente in Google Drive.
Per creare un modello utilizzando un account di servizio, svolgi i seguenti passaggi con le credenziali dell'applicazione:
- Crea una presentazione utilizzando presentations.create nell'API Slides.
- Aggiorna le autorizzazioni per consentire ai destinatari della presentazione di leggerla utilizzando permissions.create nell'API Drive.
- Aggiorna le autorizzazioni per consentire agli autori del modello di scrivere utilizzando permissions.create nell'API Drive.
- Modifica il modello in base alle esigenze.
Per creare un'istanza della presentazione, svolgi i seguenti passaggi con le credenziali utente:
- Crea una copia del modello utilizzando files.copy nell'API Drive.
- Sostituisci i valori utilizzando presentation.batchUpdate nell'API Presentazioni.