SYNTAXE GAS

Les fonctions

Une fonction, ensemble d'actions programmées en Google Script, est contenue dans un fichier. Pour la déclarer, c'est à dire la créer dans le fichier, vous devez respecter la syntaxe suivante :

function MyFunction(){

//Mon code

//Action 1

//Action 2

// Les deux // permettent de créer des commentaires sur une ligne

}

Une fonction peut avoir des paramètres permettant son exécution : une date, un nombre, un email,...

Pour utiliser ces paramètres, vous devez les déclarer dans l'entête de la fonction comme suit :

function MyFunction(parametre1,parametre2){

//Mon code

//Action 1 utilisant le paramètre 1

//Action 2 utilisant le paramètre 2

}

Un fonction peut donc exécuter des actions avec ou sans paramètres. Une fonction issue d'une bibliothèque aura donc le plus souvent des paramètres car elle aura des actions de bases qui devront s'adapter au contexte du document où l'on utilise la bibliothèque.

Une fonction peut exécuter des actions mais également retourner des valeurs :

function MyFunction(parametre1,parametre2){

//Mon code

//Action 1 utilisant le paramètre 1

//Action 2 utilisant le paramètre 2

// La fonction retourne un résultat via la syntaxe Return

return resultat;

}

Places des variables

Une variable est un objet permettant de contenir des données. Une variable pourra donc être utilisée pour exécuter des actions dans un fichier, mais pourra également prendre de nouvelles valeurs au fur et à mesure des actions dans notre fichier.

Nous définirons ici deux places pour les variables :

• Locale

Une variable locale est située à l’intérieur d'une fonction. Cette variable ne pourra être utilisée qu'à l'intérieur de la fonction, c'est à dire localement dans la fonction

function CalculCommission(montant_vendu){

//Déclaration de la variable taux. Cette variable étant déclarée dans la fonction,

//elle n'est utilisable que dans la fonction CalculCommission

var taux=0,1;

//Action calculant et retournant la commission sur le montant vendu

return montant_vendu*taux

}

• Globale

Une variable globale est située à l’extérieur des fonctions. Elle peut être utilisée dans toutes les fonctions, c'est à dire globalement dans le fichier

//Déclaration de la variable mail_admin. Cette variable étant déclarée hors d'une fonction,

//elle est utilisable dans toutes les fonctions du fichier

//--------------------------------------------------------

var mail_admin=ghislain.sanjuan@sango-co.com

//--------------------------------------------------------

function Envoi_Mail(){

//Action d'envoi de mail utilisant la variable mail_admin

MailApp.sendEmail(mail_admin,"Reporting commission","Analyse");

}

Type & déclaration des variables

Comme vous l'avez vu, les variables sont déclarées simplement comme suit :

var nom_variable=valeur_variable

Plusieurs types de variables existent :

• Les nombres

var nombre1=1;

var nombre2=-0.879

// Attention la décimale se fait avec . et nom avec ,

• Les dates

//Création d'une nouvelle date à la date de déclaration

var maintenant=new Date();

• Les booléens (Boolean)

Les booléens sont des types de variables ne pouvant prendre que deux valeurs : false ou true. Il sont utilisés comme "interrupteur" (allumé ou éteint) dans la programmation

var v=true;

var f=false;

• Les classes GAS

Presque l’ensemble des applications Google Workspace possède une classe. Gmail aura donc sa propre classe contenant ses propres fonctions. Une classe Gmail peut être appelée une bibliothèque Gmail. La différence avec une bibliothèque classique, c'est à dire que vous auriez créée, est que la bibliothèque Gmail est déjà intégrée dans GAS. Il suffit donc simplement de la déclarer en variable dans votre code pour l'utiliser. Vous pourrez alors manipuler les fonctions de cette classe via la syntaxe suivante :

//Déclaration de la classe

var mail_classe=GmailApp;

//utilisation d'une fonction de la classe via le .

mail_classe.sendEmail("ghislain.sanjuan@sango-co.com","Reporting","Analyse");

Vous retrouver l'ensemble des classes de Google Workspace via ce lien Classes Google Workspace sous le menu Google Workspace Services. Voici un autre exemple avec la classe de Google Sheets :

//Déclaration de la classe & appel d'une fonction de cette classe

//La fonction getActive() récupère le document Google sheet actif,

// c'est à dire celui qui contient le script

var sp=SpreadsheetApp.getActive();

• Les boites de dialogue & menus

Les boites de dialogue permettent d'interagir avec l'utilisateur ou d'ajouter des menus et Sidebar. Pour créer une boite de dialogue ou un menu, il faut utiliser la classe UI qui s'appelle depuis la classe du document :

//Déclaration de la classe de Google Sheets

var sheet_classe=SpreadsheetApp

//Déclaration de la classe UI à partir de la fonction getUi et de la classe SpreadsheetApp

//La fonction getUi retourne la classe UI

ui_classe=sheet_classe.getUi()

Vous trouverez alors l'ensemble des fonctions de la classe UI via ce lien : Classe UI

• Les tableaux

Si vous souhaitez gérer des données de manière organisée et rapidement, vous pouvez utiliser les variables Javascript de type de tableaux . Ce type Tableau est appelé Array en Javascript et représente une classe à part entière.

On appellera un tableau 2D, un tableau à deux dimensions

//Déclaration du tableau

var tableau2D = []

//Population d'un tableau 2D

tableau2D=[[0,1,4],[3,8,98]]

//Ce tableau ressemble alors à :

/*

0 | 1 | 4

3 | 8 | 98

*/

Vous trouverez l'ensemble des fonctions liées à la classe via ce lien : Array-Javascript

Les conditions

Lors de l'écriture de votre code, vous allez surement exécuter des actions sous certaines conditions. Pour déclarer ces conditions, vous aurez alors besoin de la syntaxe suivante du If :

• If

if ( votre_condition_1 ){

//Action 1

}

if ( votre_condition_2 ){

//Action 2

}

else{

//Action 3

}

// Le code ci dessus fonctionne comme suit :

//Si (if) la condition_1 est vrai alors Action_1

//Si (if) la condition_2 est vrai alors Action_2

//Si (else) la condition_2 n'est pas vrai alors Action_3

Attention : Le "else" ne fonctionne qu'avec le précédent if

Si vos conditions concernent la valeur d'une variable , vous avez deux possibilité de créer des conditions par rapport à cette variable :

• Multiple Ifs

var nombre=3

//Si le nombre vaut 1

if(nombre==1){

//Action_1

}

//Si le nombre vaut 2

if(nombre==2){

//Action_2

}

//Si le nombre vaut 1

if(nombre==3){

//Action_3

}

else{

//Action_4

}

• Switch Case

var nombre=3

switch (nombre) {

case 1:

//Action_1

break;

case 2:

//Action_2

case 3:

//Action_3

break;

default:

//Action_4

}

Les "cases" représentent les différents "if". Le "break" permet de sortir du switch case dès qu'une condition est rencontrée. Si on omet une instruction break, le code exécutera les instructions pour le cas correspondant mais aussi celles pour les cas suivants (si la condition est vérifiée) jusqu'à la fin de l'instruction switch ou jusqu'à une instruction break

Les opérateurs et expressions

Les expressions Javascript sont nombreuses. Voici les plus utilisées pour ce cours :

• Décomposition

L'opérateur de décomposition permet d'insérer un tableau (Array) dans un autre

var parts = ['shoulders', 'knees'];

var lyrics = ['head', ...parts, 'and', 'toes'];

• parseInt

Cet opérateur permet de renvoyer un nombre entier à partir d'un nombre décimal ou d'une chaîne de caractères

var entier1= parseInt(5.16); // Renvoie 5

var entier2= parseInt("8.98");// Renvoie 8

• toFixed(n)

Opérateur permettant d'arrondir un nombre ( à l'arrondi supérieur) avec le nombre de décimal voulu

var nb1=5.782

var var_arrondi= nb1.toFixed(1) // Renvoie 5.8

var var_arrondi2= nb1.toFixed(2) // Renvoie 5.78

• toString()

Il permet de transformer une variable en une variable de type chaîne de caractère. Ceci est utile pour forcer le format en chaîne de caractères et éviter des problème lors de comparaison de variable

var nb1=5.78

var var_caractere= nb1.toString() // Renvoie "5.8"

Les opérateurs Javascript permettent de comparer, d'affecter ou d'appliquer des conditions logiques :

• Opérateurs unaires

  • typeof a : renvoie le type de la variable a

  • a instanceof Type : permet de tester si a possède le même type qu'un type prédéfini

    • Exemple : Si a est une date alors a instance Date renvoie true

• Opérateurs de comparaison

  • a == b : Si la valeur de a égal à la valeur de b , l'opérateur renvoie true, sinon false

  • a != b : Si la valeur de a égal à la valeur de b , l'opérateur renvoie false, sinon true

  • a === b : Si la valeur et le type de a sont égaux à la valeur et au type de b , l'opérateur renvoie true, sinon false

  • a !== b : Si la valeur et le type de a sont différents de la valeur et du type de b , l'opérateur renvoie true, sinon false

  • a <= b : Si a inférieur ou égal à b , l'opérateur renvoie true, sinon false

  • a >= b : Si a supérieur ou égal à b , l'opérateur renvoie false, sinon true

  • a < b : Si a inférieur à b , l'opérateur renvoie true, sinon false

  • a > b : Si a supérieur à b , l'opérateur renvoie false, sinon true

• Opérateurs arithmétiques

  • a++ : incrémentation de 1 de la valeur de a

  • a-- : décrémentation de 1 de la valeur de a

• Opérateurs logiques

  • condition_1 && condition_2 : renvoie true si condition_1 et condition_2 sont vérifiées, false sinon

  • condition_1 || condition_2 : renvoie true si condition_1 ou condition_2 sont vérifiées, false si les deux conditions ne sont pas vérifiées

• Opérateur/fonction de chaines de caractères

  • text.includes(a) : Si la valeur de la variable a est contenue dans la valeur de la variable text alors true est renvoyé , sinon false est renvoyé

  • text.indexOf(a) : La fonction indexOf() renvoie l'index de la première occurrence de la valeur de la variable a au sein de la chaîne de caractères de la variable text. Elle renvoie -1 si la valeur cherchée n'est pas trouvée.

"LOREM IPSUM".indexOf("R")

// renvoie 2 car le premier caractère est à l'index 0

Plus d'informations via ces liens :

• Expressions & opérateurs Javascript

• Includes Javascript

• IndexOf

Les boucles

Pour parcourir des tableaux de données ou simplement répéter des actions jusqu'à ce qu'une condition ne soit plus vérifiée, vous pouvez utiliser les boucles For & While :

• Boucle For

for ( var i=1 ; i<=10; i++){

//Mes actions

}

//1-La valeur de i démarre à 1 (var i=1)

//2- Exécution de mes_actions

//3- La valeur de i est incrémenté de 1 (i++)

// Si i est inférieure ou égale à 10 (i<=10) répétition des étapes 1 , 2 & 3

// Sinon arrêt

• Boucle While

var i=1

while (i<=10){

// mes_actions

i++

}

//1-La valeur de i démarre à 1 (var i=1)

// 2- Si i est inférieure ou égale à 10 (i<=10) étape suivante

// Sinon arrêt

// 3- Exécution de mes_actions

// 4- La valeur de i est incrémenté de 1 (i++)

Les tableaux 2D Array

Nous avons vu comment déclarer un tableau 2D (Array). Nous allons voir quelques fonctions utiles de cette classe :

• Accès

Pour accéder à une case d'un tableau. Attention : la ligne 0 & la colonne 0 correspondent respectivement à la 1ère ligne et 1ère colonne du tableau

var tableau=[[0,8,7],[13,5,33]]

//Récupération de la valeur dans la 2ème ligne & 3ème colonne

var valeur=tableau[1][2] // Renvoie 33

//Récupération de la valeur dans la 1ère ligne & 1ère colonne

var valeur=tableau[0][0] // Renvoie 0

//Récupération de la valeur dans la 1ère ligne & 2ème colonne

var valeur=tableau[0][1] // Renvoie 8

//Récupération de la valeur dans la 2ème ligne & 2ème colonne

var valeur=tableau[1][1] // Renvoie 5

• Length

Elle indique longueur de la dimension courante du tableau

var tableau=[[0,8,7],[8,5,33]]

var longueur_lignes=tableau.length // renvoie 2 car 2 lignes

var longueur_col=tableau[0].length // renvoie 3 car 3 colonnes

• Filter :

Cette fonction permet de filtrer le tableau suivant un critère et de renvoyer le tableau filtré

var tableau=[[0,88,7],[8,5,33], [9,66,3]]

var new_tableau=tableau.filter(x=>x[1]>6)

// La fonction filter vient filtrer les lignes du tableau

// pour lesquelles les valeurs de la 2ème colonne (index 1 >> x[1]) sont strictement supérieures à 6

// x=>x[i] permet d'indiquer que le filtre est appliquer sur l'objet courant , c'est à dire le tableau

// --------------------------------------------

// la variable new_tableau sera alors égal à

// [[0,88,7], [9,66,3]]

• ForEach:

Cette fonction permet de parcourir un tableau

var tableau=[[0,88,7],[8,5,33], [9,66,3]]

tableau.forEach( x=> Logger.log(x[0]))

//x renvoie sur l'élément lié au ForEach ici c'est la ligne du tableau qui est parcouru grâce au forEach

// Retourne dans le journal l'élément à l 'index 0 pour chaque ligne : 0 puis 8 puis 9

• Concat :

Utile pour les tableau 2D, la fonction concat permet, comme la décomposition, de fusionner des tableaux

var array1 = [['a', 'b'], ['z','c']];

var array2 = [[1, 2], [3,4]];

var array3= array1.concat(array2);

// Valeur de array3

//[['a', 'b'], ['z','c'],[1, 2], [3,4]]

• Push :

Cette fonction permet d'ajouter une ligne dans un tableau

var array1 = [['a', 'b'], ['z','c']];

array1.push([[1,7]])

//Les doubles accolades permettent de définir que les données

//passées en paramètres du push sont de type array 2D

// Valeur de array1

//[['a', 'b'], ['z','c'],[1, 7]]

• Map :

Cette fonction permet de créer un nouveau tableau à partir d'un existant. Pour un tableau 2D, la fonction Map permet d'extraire une colonne du tableau

var array1 = [['a', 'b','R'], ['H','z','c']];

var array2=array1.map(x=>x[1])

//On indique à la fonction map de renvoyer la colonne à l'index 1 du tableau , le tout dans array2

// Valeur de array2

console.log(array2)

//Renvoie ['b','z']

Appel de fonction

Nous avons vu comment déclarer une fonction et comment l'appeler depuis une classe ou une bibliothèque. Voici comment appeler une fonction depuis une autre fonction au sein d'un même script :

// Fonction d'envoi d'email avec un paramètre qui retourne resultat

function EnvoiEmail(mail){

//Code fonction EnvoiEmail

var resultat = "KO"

GmailApp.sendEmail(mail,'Votre facture', "Voici votre facture du mois de Juin")

resultat="OK"

return resultat

}

//Fonction qui envoie un mail après une commande

function EnvoiEmail_apresCmde(){

// Déclaration de la variable mail

var mail=ghislain.sanjuan@sango-co.com

// Appel de la fonction EnvoiEmail avec le paramètre mail

// Et récupération de la valeur retournée par la fonction dans la variable mail_ok

var mailok=EnvoiEmail(mail)

// Affichage du resultat

Browser.msgBox(mailok)

}

Une fonction peut donc être appelée depuis plusieurs sources :