Sommaire

Tutoriel 6: les événements et fonctions javascripts - Expert

Tutoriel 6: les événements et fonctions javascripts - Expert

SynApps est conçu pour construire des applications avec le minimum de connaissances en développement et un rendu adapté est possible sans saisir une seule ligne de javascript. Cependant, comme nous allons le voir, il est parfois nécessaire d’écrire du code pour des usages plus avancés

Dans les précédents tutoriels, nous avons déja utilisé quelques instructions javascripts pour définir des fonctions de transformations en lecture sur des liaisons et ainsi adapter un type de valeur source à un type attendu par l’acteur. Exemple: une valeur booléenne true ou false vers une chaine de caractère

Nous reviendrons dans ce tutoriel sur les fonctions de transformation en lecture et en écriture de liaison, mais au préalable nous allons mettre en oeuvre les Evénements. Dans l’inspecteur d’acteur, nous avons largemment manipulé les Propriétés mais, vous l’avez peut-être aperçu, un autre onglet permet de définir des evénements

inspector_events

Ces événements sont générés dans 2 circonstances liées soit:

au cycle de vie de l’acteur. Exemple: Initialisation, Rendu, Destruction
une intéraction de l’utilisateur: Click, Entrée souris

Tout comme les propriétés, les événements peuvent être classés dans 2 catégories:

Commun à tous les acteurs

Exemple: Entrée souris est généré quand une l’utilisateur entre en survol souris sur un acteur
Spécifiques à un acteur

Exemple: Sélection d’une ressource est généré quand une ressource est sélectionnée par l’utilisateur dans un acteur Etat

Par défaut la définition de ces événements est vide, cad qu’aucune action n’est effectuée. Mais il est possible de définir une action spécifique avec un éditeur de javascript qui donne accès à l’ensembles des objets de SynApps: acteurs, scène, etc, pour les lire mais aussi pour les modifier !

Nous verrons qu’il est également possible de débugger au pas à pas ces fonctions pour résoudre un comportement inattendu par exemple

La maitrise de la définition des événements est un élément important de toute SynApps afin d’effectuer des actions avancées non, ou pas encore, configurables dans l’éditeur SynApps MAKER !

Prerequis

Le paramétrage SynApps_Tutorials.BRY installé sur le REDY. Il contient les profils utilisateurs, Administrateur et Installateur utilisés dans ce tutoriel
Créer une nouvelle SynApp tuto06 avec le MAKER. Modifier le label de la première scène en sceneEvents et le nom avec scène événements puis déployer

Construction de l’ossature de la scène événements

Nous allons construire une scène qui contiendra plusieurs acteurs qui vont générer des événements. Ces derniers seront loggés dans une console de sortie

Remarque: la définition des labels des acteurs est d’autant plus importante avec les événements car ils sont largemment utilisés dans les scripts pour notamment identifier des acteurs

Définir l’acteur principal avec un acteur Empilement
- renommer le Label avec stackRoot
- modifier la propriété Spécifiques > Orientation en Horizontal
Ajouter un acteur enfant de type Empilement qui contiendra les acteurs qui vont générer des événements
- renommer le Label avec stackEvents
- réinitialiser la propriété Gabarit > Largeur avec la taille [vide]
- définir la propriété Position > Align. vertical en Etendre
- définir la propriété Position > Align. horizontal en Etendre
- définir la propriété Aspect > Police > Taille avec la taille 50px
Ajouter un acteur enfant de type texte qui sera le premier acteur à générer des événements
- renommer le Label avec textActorA
- modifier la propriété Spécifiques > Contenu avec le texte Acteur A
- modifier la propriété Aspect > Couleur de fond avec la couleur #009fe3
- modifier la propriété Aspect > Couleur avec la couleur #ffffff
- modifier les 2 propriétés Position > Align. vertical, Position > Align. horizontal en Centré
- modifier les 4 propriétés Gabarit > Marge int. gauche, Marge int. droit, Marge int. haut, Marge int. bas avec la taille 50px
Sélectionner l’acteur stackRoot et ajouter un acteur enfant de type Zone de texte (dans la catégorie Intéractions de l’explorateur d’acteurs) qui jouera le rôle de console de sortie des événements
- renommer le Label avec textareaOutput
- réinitialiser la propriété Spécifiques > Valeur avec le texte [Vide]
- définir la propriété Spécifiques > Texte d’aide avec le texte Console des événements
- définir la propriété Aspect > Couleur de fond avec la couleur #d6d6d6
- définir la propriété Aspect > Police > Style avec la sélection Italic
- définir la propriété Aspect > Police > Taille avec la taille 30px
- définir la propriété Gabarit > Largeur avec la taille 50%
- modifier les 4 propriétés Gabarit > Marge int. gauche, Marge int. droit, Marge int. haut, Marge int. bas avec la taille 50px
Vérifier la liste des acteurs ainsi que la zone de prévisualisation

Implémentation et log d’un événement dans la console

Nous allons définir un premier événement click sur l’acteur A et le logger dans la console

Sélectionner l’acteur textActorA
- cliquer dans l’onglet Evénements de l’inspecteur d’acteur
- cliquer sur commun pour ouvrir la liste des événemnts
- éditer l’événement Ev. “Click souris”
- copier la fonction javascript suivante dans la zone d’édition. Elle sera expliquée ci-après
```
 var evtName = "Click souris";
 var textareaOutput = context.synoStage.findByLabel('textareaOutput');
 var currentOutput = textareaOutput.get('value');
 var newOutput = context.target.get('content') + ' > '+ evtName + "\n" + currentOutput;
 textareaOutput.set("value", newOutput);
```
- sauvegarder la fonction et fermer l’éditeur d’événement
Déployer, éxécuter et cliquer sur Acteur A, la console log l’événement
Revenir sur le MAKER et ouvrir l’événement Ev. “Click souris” défini précédemment
- une zone d’aide est affichée droite de la fenêtre et donne les mots-clefs permettant de récuperer et modifier les objets de la SynApp, acteurs, scènes, etc dans le contexte courant
- ligne 2
```
  var textareaOutput = context.synoStage.findByLabel('textareaOutput');
```
  L’instruction contexte.synotage retourne la scène courante sceneEvents de l’acteur à l’origine de l’événement
  
  La fonction findByLabel(…) retourne l’acteur avec le label textareaOutput dans la scène
  
  la variable textareaOutput contient donc l’acteur du même nom
- ligne 3
```
  var output = textareaOutput.get('value');
```
  La fonction get(…) retourne la valeur de la propriété value de l’acteur textareaOutput
  
  Remarque: la propriété value correspond à la propriété Spécifiques > Valeur dans l’inspecteur d’acteur. En effet, toutes les propriétés ont un nom intelligible pour l’utilisateur du MAKER et un nom interne (en anglais) utilisé dans les scripts. Pour connaître le nom interne d’une propriété, il suffit de survoler le bouton de liaison de la propriété comme ci-dessous
- ligne 4
```
  var newOutput = context.target.get('content') + ' > '+ evtName + "\n" + currentOutput;
```
  L’instruction context.target retourne l’acteur à l’origine de l’événement textActorA
  
  La fonction get(‘content’) retourne la valeur de la propriété Contenu de l’acteur textActorA, soit Actor A
  
  “\n” effectue un retour à la ligne
- ligne 5
```
  textareaOutput.set("value", newOutput);
```
  La fonction set(…) modifie la valeur de la propriété value de l’acteur textareaOutput qui prend la valeur de newOutput, soit Actor A > Click souris\n...

Généralisation du log sur autres événements et acteurs

Nous souhaitons mettre en place le même mécanisme que précédemment mais généralisé à tous les acteurs. Nous pourrions dupliquer le code ci-dessus en modifiant le nom de l’événement dans la ligne 1

var evtName = "XXXX"; // Remplacer XXXX par le nom de l'événement

Mais cela n’est pas vraiment maintenable: la moindre modification devrait être reproduite sur toutes les implémentations des événements

L’objectif est donc de déclarer une fonction log(…) dans l’acteur textareaOutput et appeler cette fonction depuis tous les événements de l’acteur textActorA. Cette fonction prendra 2 paramêtres:

actor: l’acteur à l’origine de l’événement
evtName: le nom de l’événement

A savoir: les fonctions doivent être déclarées dans l’événement initialisation qui est le premier événement à s’éxécuter dans le cycle de vie de l’acteur

Sélectionner l’acteur textareaOutput pour déclarer la fonction log(…)
- Editer l’événement Commun > Ev. “initialisation”
- copier la fonction javascript suivante dans la zone d’édition
```
 context.target.log = function (actor, evtName) {
  var textareaOutput = context.target;
  var currentOutput = textareaOutput.get('value');
  var newOutput = actor.get('label') + ' > '+ evtName + "\n" + currentOutput;
  textareaOutput.set("value", newOutput);
 }
```
- ligne 1
```
  context.target.log = function (actor, evtName) {
      ...
  }
```
  L’instruction context.target.log = function … permet de définir une fonction log(…) qui est définie sur l’acteur courant, context.target, textareaOutput
  
  La fonction a été adaptée par rapport à la définition précédente et prend en paramêtre actor et evtName respectivement l’acteur à l’origine de l’événement et le nom de l’événement
Sélectionner l’acteur textActorA pour modifier l’événement Clic souris et appeler la fonction log()
- Editer l’événement Commun > Ev. “Click souris” et remplacer avec le javascript suivant
```
  var textareaOutput = context.synoStage.findByLabel('textareaOutput');
  textareaOutput.log(context.target, "Click souris");
```
- ligne 2
```
  textareaOutput.log(context.target, "Click souris");
```
  La fonction log(…) ,que nous avons implémenté précédemment, est appelée avec l’acteur à l’origine de l’événement context.target et le nom de l’événement
Déployer, éxécuter et cliquer sur Acteur A, pour vérifier que la console log toujours l’événement
Sélectionner l’acteur textActorA pour implémenter les autres événements
- copier le javascript suivant
```
  var textareaOutput = context.synoStage.findByLabel('textareaOutput');
  textareaOutput.log(context.target, "XXX");
```
- éditer l’événement Commun > Ev. “Rendu” et coller le javascript copier ci-dessus en remplaçant la chaine de caractère XXX par Rendu
- reproduire l’opération ci-dessus pour les événements Ev. “Entrée souris”, Ev. “Sortie souris”, Ev. “Clic enfoncé”, Ev. “Clic relaché”
Cloner l’acteur textActorA
- renommer le Label avec textActorB
- modifier la propriété Spécifiques > Contenu avec le texte Actor B
- modifier la propriété Aspect > Couleur de fond avec la couleur #9400d3
Cloner l’acteur textActorB
- renommer le Label avec textActorC
- modifier la propriété Spécifiques > Contenu avec le texte Actor C
- modifier la propriété Aspect > Couleur de fond avec la couleur #ff8000
Déployer, éxécuter et intéragir avec les acteurs Acteur A, B et C, pour vérifier que la console log tous les événements implémentés: Rendu, Entrée souris, Sortie souris, Clic enfoncé, Clic relaché et Clic souris

Remarques:
- l’événement Rendu apparait en premier car il est éxécuté au moment du rendu des 3 acteurs sur la scène
- l’événement Clic enfoncé est généré au moment même ou l’utilisateur clique sur la souris, idem pour Clic relaché au moment du relachement. Ces 2 événements sont toujours suivi de l’événement _Clic souris__. La pluspart du temps, seul ce dernier doit être implémenté

Ajout d’un bouton de nettoyage de la console

La console de log est vite remplie des événements générés. Nous allons ajouter un bouton de nettoyage qui videra le contenu de la console

Revenir sur le MAKER et sélectionner l’acteur stackRoot
Ajouter un acteur Bouton poussoir
- renommer le Label avec buttonPushClear
- modifier la propriété Spécifiques > Contenu avec le HTML
```
 
```
 Remarque: ce code restitue une image de type gomme provenant de la librairie bootstrap
- modifier la propriété Spécifiques > Couleur model avec la sélection Danger
- modifier la propriété Aspect > Police > Taille avec la taille 50px
- modifier la propriété Position > Align. vertical avec la position Haut
- éditer l’événement Commun > Ev. “Clic souris” avec le javascript
```
 var textareaOutput = context.synoStage.findByLabel('textareaOutput');
 textareaOutput.set('value', '');
```
- ligne 2: textareaOutput.set(‘value’, ‘‘) remplace le contenu de la console de log par une chaine vide
Déployer, éxécuter et vérifier que le bouton de nettoyage est opérationnel

Debugging sous Chrome

Il est parfois trés utile de pouvoir débugger une fonction javascript pour résoudre un dysfonctionnement ou une erreur. SynApp une application qui s’éxécute dans le navigateur et nous pouvons donc utiliser ses fonctionnalités avancés pour débugger le code éxécuté dans SynApp ! La plupart des navigateurs modernes possèdent des fonctions de débugging. Nous utiliserons ici Chrome pour les besoins de ce tutoriel

Exécuter la SynApp et appuyer sur F12 pour ouvrir la console Developer Tools

Remarque: dans la mesure du possible, il est préferrable d’utiliser 2 écrans: le premier pour la SynApp, le second pour la console Developer Tools. Configurer le Dock side pour choisir le mode d’affichage
Sélectionner l’onglet Sources > Network de la console
Pour info, le dossier appria.wit.fr contient le RUNTIME du SynApps qui ne peut pas être exploité
Ouvrir le second dossier synapps-scripts. Celui-ci nous intéresse car il contient tous les événements implémenté dans la SynApp ! Ils sont classés par nom relativement explicites: onClick, onInit, onMouseDown, onMouseEnter, onMouseLeave, onMouseUp, onRender
Ouvrir le dossier des événements onInit qui contien la fonction javascript implémenté par l’événement Ev. “Initialisation” de l’acteur textareaOutput

Remarque: une SynApp peut avoir beaucoup de scripts définis dans plusieurs acteurs et scènes. Un formalisme est donc défini afin d’identifier rapidement le script recherché:

Dans actor-textarea-textareaOutput-sceneEvents.js
- actor signifie que le script est associé à un objet de type acteur
- textarea correspond au type zone de texte de l’acteur (en anglais)
- textareaOutput correspond au label de l’objet
- sceneEvents correspond à la scène de l’objet
Ouvrir le dossier des événements onClick qui contien les 4 fonctions javascript implémenté par l’événement Ev. “Clic souris” dans la scène

Le formalisme de nommage des évènements permet d’identifier aisemment les 4 fonctions et les acteurs auquelles elles se rapportent
Sélectionner la fonction javascript actor-buttonPush-buttonPushClear-sceneEvents.js. Son contenu s’affiche dans la zone centrale
Ajouter un point d’arret sur la ligne 4 en cliquant sur celle-ci
Cliquer sur le bouton de nettoyage de la SynApp pour éxécuter l’événement Ev “Clic souris”. Le code javascript est alors éxécuté jusqu’au point d’arrêt et le navigateur indique Paused in debugger
Ouvrir la console si pas encore ouverte
copier le javascript suivant dans la console + entrée
```
textareaOutput.get('value')
```
Le contenu de la propriété Valeur est alors affichée dans la console !
- La totalité des propriétés de l’acteur peuvent être évaluées de la même manière. Pour connaitre la couleur de fond, copier dans la console:
```
  textareaOutput.get('backgroundColor')
```
- Vous pouvez également modifier les valeurs des propriétés. Pour modifier la couleur de fond de l’acteur en jaune, copier dans la console
```
  textareaOutput.set('backgroundColor', 'yellow')
```
  puis appuyer sur F8 pour sortir du point d’arrêt, la couleur de fond a changé !
  
  Remarque: la couleur d’origine configurée dans la SynApp revient après rechargement
Cliquer sur le bouton de nettoyage pour rentrer de nouveau en debug et copier le javascript suivant dans la console + entrée
```
textareaOutput.inspect()
```
La fonction inspect() permet de visualiser la totalité des valeurs des propriétés d’un objet de SynApps. Ici l’acteur textareaOutput
Inspecter tous les types d’objets pour connaitre leurs propriétés
- host: informations systèmes du REDY
```
  context.host.inspect()
```
- synoStage: scène courante
```
  context.synoStage.inspect()
```
- synapp: synApp courante
```
  context.synapp.inspect()
```
- session: session utilisateur courant
```
  context.session.inspect()
```
  Remarque: l’objet session contient une fonction logOff() qui déconnecte l’utilisateur courant. Nous allons utiliser cette fonctionnalité dans la partie suivante pour construire un composite affichant l’utilisateur courant et un bouton de déconnection

Vous avez vu comment débugger les événements SynApps avec le navigateur Chrome, afficher et modifier les propriétés des objets SynApps

Mise en pratique avec composite session utilisateur

Nous allons construire un composite affichant le nom de l’utilisateur connecté et un bouton de déconnection.

Sélectionner l’onglet Composites et créer un nouveau composite
- modifier le label du composite en sessionLogger et le nom avec Session utilisateur
- modifier la description du composite en Affiche l'utilisateur connecté et permet la déconnexion
- modifier la catégorie du composite avec la sélection Métier
- Récupérer l’image ci-dessous
- Glisser/déplacer l’image dans la zone hachurée de la propriété Logo
- modifier la propriété Aspect > Police > Taille en 40px
- modifier la propriété Position > Align. vertical en Auto
Définir l’acteur principal avec un acteur Empilement
- renommer le label en stackRoot
- modifier la propriété Spécifiques > Orientation en Horizontal
- modifier la propriété Position > Align. vertical en Auto
Ajouter un acteur enfant de type html
- renommer le Label avec htmlSession
- modifier la propriété Spécifiques > Contenu en
```
 {{user}}
```
- compléter le contenu en créant la propriété additionnelle user. Vous pouvez également donner des informations additionnelles sur la propriété, comme le nom et la description, dans Additionnelles > Gestion des propriétés additionnelles
- lier la propriété en interne à l’objet Session > Utilisateur > Nom complet
- modifier la propriété Position > Align. vertical en Centré
- modifier la propriété Gabarit > Marge > Marge int. droit en 20px
Sélectionner l’acteur stackRoot et ajouter un acteur enfant de type Bouton poussoir
- renommer le Label avec buttonLogOff
- modifier la propriété Spécifiques > Contenu en
```
 
```
- modifier la propriété Position > Align. horizontal en Droite
- définir l’événement Commun > Ev. “Clic souris”
```
 context.session.logOff();
```
 Comme nous l’avons vu précédemment, la fonction logOff sur l’objet SynApp session permet de forcer la déconnection de l’utilisateur
Vérifier le composite Session utilisateur dans la zone de prévisualisation
Sélectionner la scène Scène événements
Sélectionner l’acteur stackEvents
Ajouter l’acteur composite créé Session utilisateur
- modifier la propriété Position > Align. horizontal en Centré
- réinitialiser la propriété Gabarit > Hauteur à [Vide]
- définir l’événement Commun > Ev. “Clic souris”
```
 var textareaOutput = context.synoStage.findByLabel('textareaOutput');
 textareaOutput.log(context.target, "Déconnection");
```
Remarque: ce script, identique que pour les acteurs A, B et C, log dans la console l’événement de déconnection
Déplacer l’acteur Session utilisateur en première position sous stackEvents
Déployer et éxécuter la SynApp
- cliquer sur le bouton de déconnection, l’utilisateur est déconnecté et l’événement Déconnection est loggé dans la console
Le composite Session utilisateur est opérationnel mais nous allons le faire évoluer par afficher un “toolTip” contenant le mail et le niveau de l’utilisateur connecté: administrateur, installateur, exploitant connecté
Revenir dans le MAKER et sélectionner le composite Session utilisateur
Sélectionner l’acteur stackRoot et ajouter un acteur modal
- renommer le Label avec modalTooltip
- déselectionner la propriété Spécifiques > Griser
- déselectionner la propriété Spécifiques > Fermer sur clique en dehors
- sélectionner la propriété Spécifiques > Position horizontale sur Gauche
- sélectionner la propriété Spécifiques > Position verticale sur Haut
- définir la propriété Spécifiques > Acteur attaché sur htmlSession
- sélectionner la propriété Spécifiques > Attachement horizontale sur Gauche
- sélectionner la propriété Spécifiques > Attachement verticale sur Bas
- lier la propriété Aspect > Police > Taille à la propriété taille du composite
- définir les 4 propriétés Gabarit > Marge > Marge int. gauche, Marge int. droit, Marge int. haut, Marge int. bas avec 50px
- tester le placement correcte de la modale en sélectionnant la propriété Spécifiques > Test modale
Ajouter un acteur enfant Texte
- renommer le Label avec textTooltip
- définir la propriété Spécifiques > Contenu
```
{{level}} {{mail}}
```
- compléter le contenu en créant les propriétés additionnelles proposées level et mail. Vous pouvez également donner des informations additionnelles sur ces propriétés, comme les noms et descriptions, dans Additionnelles > Gestion des propriétés additionnelles
- lier la propriété user en interne à l’objet Session > Niveau
- éditer le script de lecture de la liaison
- définir le script de transormation en lecture suivant
```
 var level = context.value;
 switch(level) {
 case 4:
 return "Administrateur";
 case 3:
 return "Installateur";
 case 2:
 return "Exploitant";
 case 1:
 return "Visiteur";
 default:
 return "?";
 }
```
 Remarque: la fonction transform le niveau 1, 2, 3 ou 4 de l’utilisateur en texte explicite
- lier la propriété mail en interne à l’objet Session > User > Mail
- définir le script de transormation en lecture suivant
```
 return context.value === null ? '@ -': context.value;
```
 La fonction retourne ‘@ -‘ si le mail n’est pas défini
 
 Remarque: les fonctions de transformations ont dans leurs contextes une propriété supplémentaire value par rapport aux événements. Dans le cas d’un script de transformation en:
 - lecture: context.value correspond à la valeur de la propriété de l’objet source. ici le mail
 - écriture: context.value correspond à la valeur de la propriété de l’acteur. Ici, elle n’est pas définie car on ne fait que lire la source
Sélectionner l’acteur htmlSession pour définir les événements qui vont afficher et cacher la modale
- définir l’événement Ev. “Entrée souris” avec la fonction javascript
```
  var modalTooltip = context.synoStage.findByLabel("modalTooltip");
  modalTooltip.set('isShown', true);
```
  Remarque: la propriété isShown est le nom interne de la propriété Afficher
- définir l’événement Ev. “Sortie souris” avec la fonction javascript
```
  var modalTooltip = context.synoStage.findByLabel("modalTooltip");
  modalTooltip.set('isShown', false);
```
  Remarque: les fonctions ci-dessus sur les 2 événements Entrée souris et Sortie souris sont sensiblement identiques, dans un cas on défini la valeur true et dans l’autre false. Nous aurions également pu définir une fonction commune displayModal(value) déclarée dans l’événement initialisation comme pour la fonction log() de textareaOutput et l’appeler depuis les 2 fonctions
Déployer et éxécuter la SynApp
- survoler le nom de l’utilisateur connecté, niveau et mail sont affichés dans le tooltip
- cliquer sur le bouton de déconnection et connectez-vous avec un compte installateur, login: install et mot de passe: .

Que retenir

Vous avez mis en oeuvre les événements et fonctions javascripts qui sont un usage avancé de SynApps

Ils permettent de réaliser des actions impossibles à définir avec l’interface d’édition du MAKER. Cela nécessite quelques connaissances de fonctions javascripts, mais vous l’aurez constaté, avec quelques instructions de base, il est rapidement possible de définir des comportements évolués

Le javacript peut être défini dans deux éléments distinctes de SynApps:

Les événements des acteurs
Les scripts de transformation en lecture et écriture des liaisons

Remarque: pour ces dernierr, lorsqu’une liaison est définie en lecture ET écriture, vers une source de donnée par exemple, toute fonction de transformation en lecture doit avoir son équivalent en écriture

Vous avez utilisé les Developer Tools du navigateur Chrome pour:

débugger les scripts définis dans SynApps MAKER,
placer des points d’arrêts et entrer en mode pas à pas
inspecter et interragir avec des objets: session, acteur, scène, etc

Enfin, vous avez réalisé un composite métier réutilisable: gérant les sessions utilisateur. Pour cela, nous avons mis en oeuvre plusieurs types d’événements et scripts au coeur du composite. L’intégration dans la scène est alors extrêmement simple et peut même être réalisé par un utilisateur sans connaissances avancées dans SynApps notamment sur les événements: principe de la boite noir et de la modularité des composites !

Conclusion

Le tutoriel 6 sur les événements et fonctions javascripts est terminé. Ils sont un usage avancé de SynApps mais pour construire des applications évoluées leurs maitrises devient rapidement indispensable !

Vous pouvez remonter les bugs & remarques concernant ce tutoriel, SynApps RUNTIME & MAKER sur GitHub

Tutoriel suivant sur les acteurs métiers du REDY

✔️ FR IT

❔ Posez une Question 💡 Proposez une Suggestion 💬 Venez discuter

made by