Création de documents
Dans la deuxième partie du cours, nous explorerons comment créer et modifier des documents, ainsi que diviser le code en plusieurs fonctions.
Parcourez la page dans l’ordre si vous apprenez, ou utilisez les liens ci-dessous pour accéder à des éléments spécifiques :
Dépannage du code Apps Script
Maintenant que vous avez effectué des exercices et essayé le premier projet, vous avez peut-être commencé à remarquer certaines des erreurs courantes dans Apps Script. Ne vous inquiétez pas, cela arrive à tout le monde ! Les messages d’erreur et la résolution des problèmes expliquant pourquoi votre code Apps Script n’a pas fonctionné comme prévu font tous partie du processus.
Voici quelques conseils utiles pour résoudre les problèmes liés à votre code Apps Script :
- Lire les messages d’erreur – Si votre script ne fonctionne pas et qu’il y a un message d’erreur dans l’éditeur ou dans le journal d’exécution, lisez-le ! Il peut y avoir des informations utiles sur le type d’erreur qui s’est produite et sur quelle ligne l’ordinateur pense qu’elle s’est produite (mais gardez à l’esprit que parfois, c’est le symptôme que la véritable erreur se trouve sur une ligne antérieure, décomposant quelque chose plus bas).
- Vérifiez votre syntaxe : l’orthographe et la ponctuation sont indispensables dans Apps Script. Les erreurs courantes incluent l’utilisation d’une ponctuation incorrecte, des commandes ou des noms de variables mal orthographiés et l’absence de crochets si nécessaire. Demander à quelqu’un d’autre de jeter un œil à votre code s’il connaît également Apps Script peut être utile pour repérer de petites erreurs comme celle-ci.
- Obtenez le bon ordre : les ordinateurs lisent le code de haut en bas. Des erreurs peuvent donc parfois se produire car votre code est dans le mauvais ordre. Par exemple, vous ne pouvez pas utiliser des variables que vous n’avez pas déjà créées, alors assurez-vous de les créer avant de les utiliser !
Vous souhaiterez probablement rechercher de l’aide en ligne lorsque vous rencontrez des problèmes avec Apps Script. La référence du développeur Apps Script est un point de départ utile pour vérifier ce que font des commandes Apps Script particulières. Lors d’une recherche en ligne, essayez d’utiliser le texte du message d’erreur ou la syntaxe de la commande que vous essayez d’utiliser dans votre recherche. Même si vous ne comprenez pas chaque mot des suggestions des gens, vous pourriez trouver quelque chose à essayer ou avoir une nouvelle idée sur ce qu’il faut modifier dans votre code.
Introduction aux documents et dossiers
Dans cette section, nous allons travailler avec des documents Google Docs, mais pour ce faire, nous devons examiner la différence entre un document et un fichier dans le monde d’Apps Script.
Dans Apps Script, nous pouvons utiliser document et fichier pour désigner des choses spécifiques. Parfois, avec des éléments Google tels que des feuilles de calcul, des documents et des présentations, vous devez accéder à des commandes spécifiques liées au type de contenu dont il s’agit, comme nous l’avons vu dans la section précédente concernant l’utilisation de feuilles de calcul. Pour ce faire, nous devons utiliser l’application spécifique intégrée à Apps Script pour travailler avec ce contenu, comme SpreadsheetApp ou DocumentApp. Ainsi, si nous travaillons avec un document , nous travaillons avec DocumentApp pour accéder à des fonctionnalités telles que le corps du document, la police, le formatage et d’autres éléments.
En revanche, nous pouvons travailler avec n’importe quel type d’élément sur Google Drive et utiliser uniquement des fonctionnalités qui pourraient être réalisées avec n’importe quel type d’élément (donc peu importe qu’il s’agisse d’une feuille de calcul, d’un document, etc.). Par exemple, si vous souhaitez copier un fichier ou modifier les autorisations de partage, cela peut être fait via Google Drive et peu importe le type d’élément dont il s’agit. Dans ce cas, nous pouvons utiliser DriveApp et nous pouvons désigner l’élément comme un fichier , car le type de fichier n’a pas d’importance.
Cela peut sembler une distinction arbitraire, mais cela nous aide à savoir quelle application nous devons utiliser dans Apps Script et quelles commandes nous pourrions trouver. Nous utiliserons des fichiers et des documents (ainsi que DriveApp et DocumentApp) dans cette section du cours.
Appeler une autre fonction
Un code Apps Script très long dans une seule fonction peut être difficile à utiliser, car il y a beaucoup de code qui fait toute une série de choses différentes à la fois, et ce code doit être répété si vous devez effectuer la même action à différents endroits dans le code. C’est là que diviser votre projet Apps Script en plusieurs fonctions peut être utile.
Par défaut, votre code Apps Script se trouve dans une seule fonction. La création de plusieurs fonctions distinctes vous permet de réutiliser plus facilement des parties de votre code à différents endroits de votre projet, ainsi que de faciliter grandement la lecture et la modification de parties spécifiques de votre projet. Par exemple, vous pourriez avoir une fonction qui crée un document à partir d’un modèle et qui pourrait être utilisée pour créer un seul document à un moment donné du projet et plusieurs documents à partir d’un ensemble de données à un autre moment.
Lorsque vous avez plusieurs fonctions, vous avez besoin d’une fonction principale qui s’exécutera lorsque vous appuierez sur le bouton Exécuter (ou utiliserez un élément de menu ou un déclencheur), et toutes les autres fonctions seront appelées dans la fonction principale, ce qui signifie que vous écrivez le nom de la fonction dans le code et elle s’exécutera à ce stade.
Lorsque vous appelez une autre fonction, vous pouvez lui transmettre des valeurs, comme des variables, afin qu’une autre fonction puisse utiliser ces valeurs selon ses besoins. Les valeurs créées dans cette autre fonction peuvent être renvoyées à la fonction principale, vous pouvez donc créer un document dans une autre fonction, puis transmettre l’URL ou l’ID à la fonction principale.
Dans le diagramme d’exemple ci-dessous, la fonction principale est getSpreadsheetData() . Il récupère les données d’une feuille de calcul et obtient un ID de fichier stocké dans ces données. Il transmet l’ID du fichier à une autre fonction createDocument() qui fait une copie de ce fichier et renvoie l’URL de cette nouvelle copie à la fonction getSpreadsheetData(). Le code dans getSpreadsheetData() pourrait alors faire des choses avec ce document, comme changer son contenu.
Copie de fichiers
Dans Apps Script, il peut être très utile de pouvoir faire des copies de documents modèles que vous pouvez placer dans des dossiers particuliers, pré-remplir avec des informations et/ou partager avec certaines personnes. C’est plus facile que de créer des documents à partir de zéro et de les formater avec Apps Script, car vous pouvez utiliser Google Docs pour configurer la structure de votre document plutôt que d’avoir à essayer de tout faire à l’aide de code. Vous pouvez également ajouter des espaces réservés pour tout contenu que vous souhaitez remplacer par des données à l’aide d’Apps Script.
Lorsque vous effectuez des copies, vous travaillez avec un fichier , car la copie est quelque chose que vous pouvez faire à partir de Google Drive, utilisez donc DriveApp . Cela signifie que vous pouvez faire des copies d’autres types de fichiers, pas seulement des documents Google Docs.
Obtenir des fichiers et des dossiers par ID
Pour copier un fichier, vous avez besoin de son identifiant, ainsi que de l’ID d’un dossier de destination. Vous devez ensuite récupérer le fichier et le dossier, puis faire une copie du fichier. Voyons comment procéder.
Une fois que vous avez copié l’ID d’un fichier ou d’un dossier, vous pouvez le coller soit directement dans une commande, soit l’enregistrer en tant que variable avec un nom sensé comme « modeleID » ou « dossierID » d’abord, puis utiliser la variable comme nécessaire. Cette dernière méthode peut être utile car vous pouvez placer l’ID en haut de votre code, ce qui facilite sa modification si vous modifiez le dossier ou le fichier modèle. N’oubliez pas qu’il s’agit d’une chaîne, l’ID devra donc être entouré de guillemets simples ou doubles.
var fichierID = '1RtVtXhHXVOvmJ6d0B073BFGhEcXPlZSFQPKc5a0Ocnc';Pour obtenir un fichier ou un dossier maintenant que nous avons l’ID, nous utilisons DriveApp pour accéder aux commandes getFileById et getFolderById . Faites attention aux majuscules : cela ne fonctionnera pas si vous écrivez « ID » au lieu de « Id ».
var modele = DriveApp.getFileById(id_du_modele_fichier);
var destinationDossier = DriveApp.getFolderById(id_du_dossier);Copier un fichier
Une fois que vous avez le fichier modèle et le dossier stockés dans des variables, vous pouvez copier le modèle à l’aide de la commande makeCopy . À ce stade, vous devrez également donner un nom au fichier, que vous pourrez soit créer entre crochets, soit stocker au préalable dans une variable.
modele.makeCopy("Mon nom de fichier", destinationDossier);
// Option alternative
var nomFichier = "Mon nom de fichier";
modele.makeCopy(nomFichier, destinationDossier);
Vous aurez généralement besoin de l’URL ou de l’ID du nouveau document, donc généralement ce que vous voudriez faire à la place du code ci-dessus est d’utiliser le code suivant et de stocker le résultat dans une variable :
// Version pour récupérer l'URL
var newDocUrl = modele.makeCopy(nomFichier, destinationDossier).getUrl();
// Version pour récupérer l'ID
var newDocId = modele.makeCopy(nomFichier, destinationDossier).getId();Bien que cet exemple montre l’obtention à la fois de l’URL et de l’ID lors de la copie d’un fichier, n’utilisez pas les deux versions à la fois comme ceci, car vous feriez deux copies différentes de votre fichier !
Modification de documents
Pour modifier des documents Google Docs à l’aide d’Apps Script, vous devez d’abord ouvrir le fichier à l’aide d’une commande telle que openById ou openByUrl , puis cibler les parties du document à modifier.
Un document est composé de plusieurs parties. Une fois que vous avez ouvert un document à l’aide d’Apps Script, vous pouvez obtenir le body , contenant la majeure partie du contenu du document, ainsi que des éléments tels que l’ en-tête , les signets , les notes de bas de page et le pied de page . Si vous souhaitez pouvoir ajouter ou modifier du texte dans un document ou créer d’autres éléments comme des tableaux, vous devrez d’abord récupérer le corps du document à l’aide de getBody , puis utiliser des commandes telles que appendParagraph et replaceText pour travailler avec le contenu du texte. dans le document.
Examinons plus en profondeur ces méthodes d’édition de documents.
Ouvrir un document
Pour ouvrir un document existant (soit celui que vous venez de créer, soit celui qui existait déjà avant l’exécution du code), vous pouvez utiliser son ID ou son URL (comme nous l’avons vu sous Obtenir des fichiers et des dossiers par ID). Vous utilisez l’application correspondante pour le type de fichier dont il s’agit, donc pour les documents, vous utilisez DocumentApp puis la commande openById() ou openByUrl() . Ces deux éléments fonctionnent de manière identique, cela dépend donc de ce que vous avez déjà stocké dans votre code (ou non) quant à savoir si vous utilisez l’option ID ou URL.
Vous stockerez généralement le fichier dans une variable une fois ouvert, votre code ressemblera donc à :
var document = DocumentApp.openById(docID);
var autreDocument = DocumentApp.openByUrl(autreDocUrl);N’oubliez pas que vous devez ouvrir et stocker dans une variable n’importe quel document, feuille de calcul ou autre fichier pour pouvoir l’utiliser dans Apps Script, car vous pouvez ensuite utiliser la variable pour accéder aux commandes relatives à cette application.
Obtenir le corps du document
Une fois que vous ouvrez un document, vous devez obtenir que le corps du document puisse le modifier ou y ajouter du contenu à l’aide de la commande getBody() avec le document que vous avez déjà ouvert. Cela signifie généralement que vous stockerez le corps du document dans sa propre variable.
var documentCorps = document.getBody();Ajout de texte
Si vous souhaitez simplement ajouter plus de contenu au bas d’un document, vous pouvez utiliser appendParagraph() pour ajouter des paragraphes sous le dernier élément du corps du document.
Vous pouvez inclure le contenu que vous souhaitez ajouter entre parenthèses de l’expression, mais il peut être plus facile de le configurer d’abord en tant que variable, puis de l’utiliser.
var paragraphContent = 'Little Miss Muffet sat on her tuffet';
documentBody.appendParagraph(paragraphContent);
document.appendParagraph('Eating her curds and whey');Remplacement de texte (rechercher et remplacer)
Lorsque vous travaillez avec des documents dans Apps Script, la modification du texte dans le corps peut être effectuée à l’aide de replaceText() , qui recherche un texte particulier dans le document et le remplace par une chaîne donnée. Ceci est particulièrement utile pour les modèles, car vous pouvez créer des espaces réservés, puis les remplacer par des données, par exemple à partir d’une feuille de calcul ou d’un formulaire.
Assurez-vous que vos espaces réservés sont uniques (s’ils doivent l’être) et distinctifs. Une option consiste à utiliser des symboles tels que << >> autour de vos mots d’espace réservé afin que vous sachiez qu’ils ne seront pas ailleurs dans le document et qu’ils ne seront pas non plus remplacés accidentellement !
replaceText() a besoin de deux informations : le texte à rechercher (sous forme de chaîne) et le texte par lequel le remplacer (sous forme de chaîne). Vous pouvez les mettre directement dans la commande ou utiliser des variables. Une utilisation courante consiste à remplacer les valeurs d’un ensemble de données. Vous pourriez donc avoir un ‘<>’ qui est remplacé par un nom provenant d’un ensemble de données stocké dans une variable.
documentBody.replaceText('<<name>>', 'Mickey');
documentBody.replaceText('<<name>>', studentName);