Un'applicazione utile dell'API Presentazioni Google è l'unione di informazioni da una o più origini dati in una presentazione basata su modelli.
Questa pagina illustra come inserire dati da un'origine esterna in una presentazione di modello esistente. Il concetto è simile a quello di unione dinamica che utilizza un elaboratore di testi e un foglio di lavoro.
Questo approccio risulta utile per diversi motivi:
L'editor di Presentazioni Google consente ai designer di perfezionare facilmente il design della presentazione. È molto più semplice che regolare i parametri nell'app per impostare il rendering della slide.
Separare i contenuti dalla presentazione è un noto principio di progettazione con molti vantaggi.
Una ricetta base
Ecco un esempio di come puoi utilizzare l'API Presentazioni per unire i dati in una presentazione:
Crea la presentazione così come vuoi che appaia utilizzando i contenuti segnaposto per la progettazione.
Per ogni elemento di contenuto da inserire, 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 presentano normalmente. Ad esempio,
{{account-holder-name}}
potrebbe essere un buon tag.Nel tuo codice, utilizza l'API Google Drive per creare una copia della presentazione.
Nel codice, utilizza il metodo
batchUpdate
dell'API Presentazioni, con un insieme di richiestereplaceAllText
, per eseguire tutte le sostituzioni del testo durante la presentazione. Utilizza le richiestereplaceAllShapesWithImage
per sostituire le immagini in tutta la presentazione.
Dopo aver creato una presentazione contenente tag, assicurati di crearne una e di usare l'API Presentazioni per manipolare la copia. Non utilizzare l'API Presentazioni per manipolare la copia principale del "modello".
Le seguenti sezioni includono snippet di codice che illustrano parte di questa procedura. Puoi anche guardare il video sopra per vedere un esempio completo (Python) che combina diversi concetti delle singole sezioni seguenti.
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, è più semplice
che trovare e sostituire singolarmente ogni istanza di testo. Uno dei motivi per cui questo è l'approccio più sofisticato è che gli ID degli elementi di pagina sono difficili da prevedere, soprattutto perché i collaboratori perfezionano e gestiscono la presentazione del modello.
Esempio
In questo esempio viene utilizzata l'API Drive per copiare un modello di presentazione, creando una nuova istanza della presentazione. Quindi utilizza l'API Fogli Google per leggere i dati da un foglio di lavoro di Fogli e infine utilizza 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. Sostituisce quindi questi dati nella presentazione ovunque si verifichino
le stringhe {{customer-name}}
,
{{case-description}}
o
{{total-portfolio}}
.
Apps Script
Go
Java
JavaScript
Node.js
PHP
Python
Ruby
Unisci immagini
Puoi anche unire immagini nella 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 per adattarla ai limiti della forma del tag, mantenendo le proporzioni dell'immagine.
Esempio
In questo esempio viene utilizzata l'API Google Drive per copiare un modello di presentazione, creando una nuova istanza della presentazione. Quindi utilizza l'API Presentazioni per trovare
qualsiasi forma con il testo {{company-logo}}
e sostituirla con l'immagine del logo dell'azienda. La richiesta sostituisce inoltre qualsiasi forma con il testo {{customer-graphic}}
con un'immagine diversa.
Apps Script
Go
Java
JavaScript
Node.js
PHP
Python
Ruby
Sostituisci caselle di testo o istanze di immagini specifiche
Le richieste replaceAllText
e replaceAllShapesWithImage
sono utili per sostituire i tag in una presentazione, ma a volte basta sostituire gli elementi in base ad altri criteri, ad esempio essere posizionati in una slide specifica.
In questi casi, devi recuperare gli ID delle forme di tag che vuoi sostituire. Per la sostituzione del testo, elimina il testo esistente in quelle forme e poi inserisci il nuovo testo (vedi l'esempio di Modificare il testo in una forma specificata).
La sostituzione delle immagini è più complessa. Per unire un'immagine, devi:
- Recuperare l'ID della forma del tag.
- Copia la dimensione e trasforma le informazioni dal tag.
- Aggiungi l'immagine alla pagina, utilizzando le dimensioni e le informazioni trasformate.
- Elimina la forma del tag.
Conservare le proporzioni dell'immagine e ridimensionarla alla dimensione desiderata potrebbe richiedere un po' di attenzione, come descritto nella sezione seguente. Vedi anche questo esempio: Sostituire un tag di forma con un'immagine.
Mantieni proporzioni
Quando crei immagini utilizzando l'API Presentazioni, l'aspetto si adatta solo alle dimensioni dell'immagine, non alle dimensioni e alla trasformazione dei dati. I dati sulle dimensioni forniti
nella richiesta createImage
sono considerate 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, ne mantieni le proporzioni, impostandone le dimensioni e il ridimensionamento come segue:
- width: impostato sul prodotto di
width
escaleX
del tag - height: impostato sul prodotto dei valori
height
escaleY
del tag - scale_x: impostato su
1
- scale_y: impostato su
1
Questo fa sì che l'API Presentazioni si adatti all'immagine in base alle dimensioni visive del tag, anziché alle sue dimensioni non in scala (consulta Sostituire un tag di forma con un'immagine).
L'impostazione dei parametri di scalabilità su 1
impedisce che l'immagine venga ridimensionata
due volte.
Questa disposizione garantisce che le proporzioni dell'immagine vengano mantenute e impedisce che l'immagine superi le dimensioni della forma del tag. L'immagine ha lo stesso punto centrale della forma del tag.
Gestisci modelli
Per le presentazioni di modelli che l'applicazione definisce e possiede, crea il modello utilizzando un account dedicato che rappresenta l'applicazione. Gli account di servizio sono una buona scelta ed evita complicazioni con i criteri 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 controllo completo sulla presentazione risultante e impediscono problemi di scalabilità legati ai limiti per utente su Google Drive.
Per creare un modello utilizzando un account di servizio, esegui questi passaggi con le credenziali dell'applicazione:
- Crea una presentazione utilizzando presentations.create nell'API Presentazioni.
- Aggiorna le autorizzazioni per consentire ai destinatari della presentazione di leggerla utilizzando permissions.create nell'API Drive.
- Aggiorna le autorizzazioni per consentire agli autori dei modelli di scrivere utilizzando permissions.create nell'API Drive.
- Modifica il modello come richiesto.
Per creare un'istanza della presentazione, esegui questi 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.