������
������������
����������
���������������������
Les bases du développement Notes/Domino
© Tsoft et Groupe Eyrolles, 2004, ISBN : 2-212-11396-X
Module 5 : Programmer avec les formules
Objectifs
− Ecrire des formules simples
− Programmer des événements de champs
− Masquer des champs et paragraphes
− Utiliser les fonctions @, les commandes @
− Créer des boutons de masques et de vues
− Outils de mise au point
Progression
Présentation du langage Le modèle événementiel Eléments de syntaxe Les fonctions @ Formatage automatique Valeur par défaut Conversion d’entrée Validation d’entrée
Atelier 5-1, QCM Valeur
Ordre d’évaluation des formules Protection des formules
Calculer avec des dates Les événements du masque Le titre de fenêtre
Atelier 5-2, Atelier 5-3 QCM
Masquer un champ
Les commandes @ Actions système
Créer un bouton dans un masque Masquer un bouton
Atelier 5-4, QCM
Actions comme cases à cocher Menus hiérarchisés d’actions Propriétés de la barre d’actions Formule de sélection d’une vue Formule de colonne calculée Formule de masquage de colonne Programmation des couleurs de lignes Créer un bouton d’action dans une vue Créer une action partagée
Atelier 5-5, QCM Outils de déboguage Récapitulatif syntaxique
Atelier 5-6
• Commande @
• Conversion d’entrée
• Evénements
• Fonction @
• Masquer
• Valeur
• Valeur par défaut
• Validation d’entrée
Présentation du langage
Présentation du langage
Langage central intégré à Domino/Notes depuis les premières versions
Avantages
Exécution performante
Langage simple et peu structurant
Utilisé dans des événements, des boutons, des agents
Traitements itératifs – For, While, DoWhile – depuis la version 6 Limites
Pas de bibliothèques de sous-programmes Ne gère pas les événements de curseur Outils de débogage non disponibles
Le langage de formules est disponible depuis les toutes premières versions de
Domino/Notes. Il a été conçu dès le départ pour effectuer des traitements très simples.
Au fil des versions, les applications Notes sont devenues complexes car plus ambitieuses et le langage de formules a évolué en conséquence. Il n’en demeure pas moins qu’il a les avantages de ses limites et inversement.
Ce module introduit les notions indispensables pour utiliser le langage de formules. La présentation de la syntaxe a été placée en fin de module parce qu’une présentation en début est habituellement fastidieuse et puis parce que ce n’est pas réellement la syntaxe qui peut poser des difficultés mais l’esprit du langage.
Avantages
Le langage de formules s’utilise dans les événements attachés à un champ, à un masque, pour effectuer des calculs de colonnes, sélectionner des documents pour une vue. C’est parfois le seul langage disponible : le titre d’une fenêtre Notes, la valeur par défaut d’un champ, le contenu d’une colonne calculée s’évaluent à l’aide d’une formule. La programmation de ce type d’événement requiert précisément un langage simple et peu structurant. Une bibliothèque importante de fonctions – les fonctions @ – apporte une solution simple et performante à la plupart des traitements requis. La version 6 a introduit des instructions de traitements itératifs : For, While, DoWhile.
Limites
Le langage de formules est utilisable également pour écrire des traitements appliqués à un ensemble de documents. Ses limites apparaissent alors : la programmation
structurée reste limitée, il ne sait pas gérer des bibliothèques de fonctions et de sous- programmes et ignore même l’existence de la programmation orientée objet.
Lorsqu’il s’agit de gérer des événements de curseur à l’écran – entrée dans un champ, sortie d’un champ, passage au-dessus d’un champ –, le langage de formules n’apporte pas de solutions.
Le modèle événementiel
Le modèle événementiel
Une note de conception est un conteneur d’objets
Masque contient l’objet masque, des objets champs, images, actions…
Vue contient l’objet vue, des objets colonnes et actions Des événements sont associés aux objets
Contiennent des instructions en formules, JavaScript, LotusScript Un événement résulte souvent d’une action utilisateur
Ouverture d’un masque pour création de document Enregistrement d’un document
Copier/coller Autres actions
Les notes de conception sont représentées comme des objets dans Designer : un masque, une vue, un agent… sont des objets. Chacun a des caractéristiques :
− Son nom qui permet de l’identifier de façon unique dans la base
− Son type : masque, vue, agent…
− Des propriétés : couleur d’arrière-plan, couleur de lignes…
− D’autres objets dépendants qui sont contenus dans l’objet : un bouton, un champ, une image… dans un masque ou encore une colonne dans une vue
− Des traitements rattachés sous forme d’événements : initialisation, déchargement, clic, ouverture…
Les événements sont des conteneurs de programmes écrits en formules, LotusScript, JavaScript et Java. La plupart des événements supportent un seul type de langage, les autres supportant aussi bien les formules que LotusScript ou Java. Le programme s’initialise et se termine à chaque appel de l’événement.
Les événements sont déclenchés par des actions de l’utilisateur – ouverture d’un masque, clic sur un bouton, enregistrement d’un document, fermeture d’un
document… – ou du système – lancement d’un agent… Le client Notes et le serveur Domino enchaînent l’appel à un ou à des événements et les opérations de lecture et écriture sur disque.
Le concepteur a la possibilité de capturer les événements par de la programmation objet avec LotusScript en définissant des méthodes portant le même nom que les événements. Cette solution est complexe à mettre en œuvre et la technique de
programmation la plus répandue consiste à adhérer au modèle événementiel proposé et à ajuster l’application en conséquence. Ce choix est sensible essentiellement pour l’interface utilisateur pour les applications tournant sur le client Lotus Notes. Une maquette d’écran de saisie ou de visualisation qui accompagne les cas d’utilisation permet de déterminer les choix liés à la technologie utilisée, ici Lotus Domino/Notes.
Les événements étudiés dans ce module sont rattachés aux champs et au masque. La bonne compréhension du moment où ils sont activés est nécessaire pour une
conception saine de l’application.
Eléments de syntaxe
Eléments de syntaxe
Langage faiblement typé
Initialisation automatique d’une variable comme texte vide Type de variable déterminé par une affectation
Noms de variables non sensibles à la casse Instructions séparées par un point-virgule ( ; ) Particularités
:= est l’opérateur d’affectation tva := 19.6;
= est l’opérateur de comparaison pour égalité Form = "masOj"
Opérateurs arithmétiques et de comparaisons : + - * / = <> != < >
Délimiteurs de chaîne de caractères : "chaîne" ou {chaîne}
Le langage de formules manipule des variables et des constantes à l’aide d’opérateurs.
Les instructions et les fonctions utilisent des caractères séparateurs.
Variables
Un champ dans un masque est identifié dans une formule par une variable qui porte son nom. Par exemple, le contenu du champ Statut est testé dans la formule qui suit :
@if ( Statut = ″1″ ; FIELD Etat := ″OK″ ; FIELD Rel := ″Oui″) ; Des variables temporaires peuvent aussi servir à enregistrer des valeurs intermédiaires.
Par exemple, la variable de travail nom contient successivement une chaîne de caractères en majuscules, en minuscules, puis en minuscules sauf la première lettre :
nom := ″DUPONT″ ;
nom := @LowerCase(nom) ; nom := @ProperCase(nom) ;
Le langage de formules étant faiblement typé, c’est la valeur assignée à une variable qui en détermine le type. Dans une même formule, ce qui suit est parfaitement licite :
tmp := 24;
REM {Des instructions utilisant la valeur numérique tmp};
…..
tmp := "Dupont & Co";
REM {Des instructions utilisant la valeur texte tmp};
tmp:= @True;
REM {Des instructions utilisant la valeur booléenne tmp};
Les performances d’exécution restent comparables avec ou sans variables temporaires du fait que le moteur de formules procède à l’évaluation au dernier moment.
Une variable non initialisée contient une chaîne de caractères vide (""). La fonction
@IsNull teste le contenu d’une variable et retourne Vrai si elle est vide.
Constantes
Les constantes servent à déterminer des valeurs par défaut, et interviennent dans des calculs, des comparaisons logiques.
Type de constante Notation
Texte Texte entre apostrophes doubles ou simples : ″Tests Durée″
Ou entre accolades { }
titre := ″Tests Durée″ ; titre := ′Tests Durée′ ; titre := {Tests Durée} ; Nombre Entier : -24 ou 24
Décimal : -1,3 ou 1,3 Scientifique : 1,3E3 tva := 19,6 ; Date/heure Valeur entre crochets
[01/10/1999]
[10:12] ou [10:12:00]
[01/10/1999 10:12:00]
SELECT DateReunion > [01/01/2000]
Lorsqu’une constante de type texte contient une apostrophe simple ou double, deux solutions sont possibles :
− Encadrer la constante avec des accolades { } : {Test d’une durée}
− Taper le caractère d’échappement \ devant l’apostrophe : ″Test d\’une durée″
Opérateurs
Le tableau liste les opérateurs utilisés en langage de formules sur des scalaires – valeurs simples – ou des listes. Les opérateurs de type produit cartésien ( **, *+, …= ) applicables aux listes ont été omis.
Opérateur arithmétique
Opération
:= Affectation tva := 19,6 ;
: Concaténation d’éléments d’une liste
couleurs := ″rouge″ : ″vert″ : ″bleu″
+ -
Valeur numérique positive Valeur numérique négative pas := -10 ;
* /
Multiplication Division +
-
Addition, concaténation quantite + 10
″La variable contient ″ +
@Text(HeureDebut) Soustraction
Remarques
L’opérateur d’affectation est constitué des deux caractères deux-points suivi de égal (:= ) : le caractère égal ( = ) est l’opérateur de comparaison.
L’opérateur + appliqué à des scalaires (valeurs simples) de type texte produit un scalaire de type texte.
L’opérateur : appliqué à des scalaires (valeurs simples) de type texte produit une liste (valeurs multiples) de type texte.
Les opérateurs arithmétiques ne peuvent manipuler que des variables numériques : il n’y a pas de conversion automatique.
Opérateur logique
Opération
=
<>
!=
=!
><
<
>
<=
>=
Egalité Inégalité Inégalité Inégalité Inégalité Plus petit que Plus grand que Plus petit ou égal à Plus grand ou égal à
!
&
|
NON logique
@If ( HeureDebut != NULL ; ……..) ET logique
@If ( HeureDebut != NULL & HeureFin !=
NULL ; …….) OU logique
Caractères séparateurs
Instructions
Lorsqu’une formule comprend plusieurs instructions, elles sont séparées par le point-virgule ( ; ).
trav := @ProperCase( ObjetReunion ) ;
@Trim( trav ) ;
Arguments d’une fonction @ et d’une commande @
Les arguments d’une fonction @ ou d’une commande @ sont séparés par le point-virgule ( ; ).
@Name( [CN] ; @UserName)
@Command( [Compose] ; ″masOJ″ )
Eléments d’une liste
Lorsqu’une liste est créée par formule, ses éléments sont séparés par un caractère deux-points ( : ). Ce caractère est également répertorié comme opérateur de
concaténation des éléments d’une liste. Il apparaît notamment dans les arguments de fonctions @ : il est alors bien difficile de faire la différence entre le caractère séparateur entre arguments et le caractère séparateur des éléments d’une liste qui est elle-même un argument. Ouvrez les yeux et lisez l’aide…
Les fonctions @
Les fonctions @
@Fonction(argument 1 ; argument 2 ; … ; argument n) Retourne une valeur texte, numérique, date/heure, booléen Arguments séparés par un point-virgule ( ; )
Utilisation
Manipuler les chaînes de caractères : recherche...
Manipuler les dates : décalage, conversions ...
Traiter les listes : modifier l’élément n ...
Tester : est-ce un nouveau document ?
Traiter des informations : prénom et nom de l’utilisateur ...
Obtenir des informations d’environnement : base active ...
Les fonctions @ sont fournies en standard avec Designer et permettent d’accomplir simplement des traitements pouvant être complexes. La syntaxe générale des fonctions @ est abordée ici. La liste des principales fonctions @ classées par thèmes donne une idée des fonctions accomplies. Ces fonctions sont détaillées par la suite.
Syntaxe
Une fonction @ est appelée simplement par son nom ou avec des paramètres en nombre variable mis entre parenthèses et séparés par un point-virgule ( ; ) :
− des variables : des noms de champs,
− des constantes : numériques, textuelles, date/heure,
− des mots-clés entre crochets : qui dépendent de la fonction,
− une autre fonction @.
Elle retourne une valeur dont le type dépend de la fonction : texte, nombre, date/heure.
@UserName Retourne le nom de l’utilisateur courant sous forme d’une chaîne de caractères.
Hélène ROUQUIE/STD/TSOFT
@Name([CN] ; @UserName) @Name extrait une partie du nom. [CN] signifie Common Name, donc prénom et nom.
Hélène ROUQUIE
@Text(Quantite) Retourne une valeur numérique ou date/heure sous forme d’une chaîne de caractères.
Si Quantite=800, alors 800 en caractères est retourné.
@Text(Ventes ; ″C,2 ″) Le deuxième paramètre est optionnel et précise le format de sortie. C,2 signifie : format monétaire et deux décimales ;
Si Ventes=800, alors 800,00 F est retourné.
Les fonctions @ sont accessibles depuis le panneau de programmation de Designer.
• Cliquer sur l’onglet (Référence)
• Sélectionner Fonctions @
• Taper la première lettre du nom d’une fonction pour se positionner dans la liste
• Cliquer (Aide) ou appuyer sur la touche
Table des matières – Langage de formules – Langage de formules – Fonctions @ de A à Z.
Dans cet ouvrage se reporter à l’annexe Fonctions @.
Manipulation de chaînes de caractères
Ces fonctions permettent de modifier une chaîne, de faire des recherches, des remplacements de caractères.
Fonction @ Description
@UpperCase(chaine) Transforme le contenu de chaine en majuscules.
″aZerTy″ donne ″AZERTY″.
@LowerCase(chaine) Transforme le contenu de chaine en minuscules.
″aZerTy″ donne ″azerty″.
@ProperCase(chaine) Transforme le contenu de chaine en minuscules sauf le premier caractère de chaque mot.
″jeaN fRançOis roUQuie″ donne
″Jean François Rouquie″.
@Trim(chaine) Elimine les espaces superflus : les espaces en début et en fin sont éliminés. Les espaces entre deux mots sont réduits à un seul. : ″ paul le roux ″ donne ″paul le roux″.
@Left(chaine ; 4) Retourne les quatre premiers caractères (en partant de la gauche) de chaine : ″azerty″ donne ″azer″.
@Right(chaine ; 4) Retourne les quatre derniers caractères (en partant de la droite) de chaine : ″azerty″ donne ″erty″.
@NewLine Insère un caractère de retour à la ligne.
Par exemple : Nom + @NewLine + Adresse.
Référence Fonctions @
Aide et Coller
Ces fonctions @ seront utilisées principalement dans ce module pour convertir le contenu d’un champ de saisie. Par exemple, le contenu du champ NomProjet est standardisé – élimination des espaces superflus, mise en minuscules avec une capitale pour la première lettre de chaque mot – avec la formule :
@ProperCase ( @Trim ( NomProjet ) )
Manipulation de dates
Ces fonctions permettent de récupérer des valeurs système et d’opérer des décalages dans le temps.
Fonction @ Description
@Today Retourne la date du jour au format date/heure.
@Tomorrow Retourne la date de demain au format date/heure.
@Yesterday Retourne la date d’hier au format date/heure.
@Now Retourne la date et l’heure actuelle au format date/heure.
@Month(date) Retourne le mois au format nombre de la variable date qui est au format date/heure.
@Month(@Today) retourne le mois en cours.
@Day(date) Retourne le jour au format nombre de la variable date qui est au format date/heure.
@Day(@Today) retourne le jour pour aujourd’hui.
@Year(date) Retourne l’année au format nombre de la variable date qui est au format date/heure.
@Year(@Today) retourne l’année en cours.
@Weekday(date) Retourne le numéro du jour dans la semaine – à partir de dimanche – de la variable date qui est au format date/heure.
@Created Date et heure de création du document.
@Modified Date et heure de dernière modification du document.
@Adjust(date ;aa ;mm ;
jj ;hh ;mm ;ss)
Décalage dans le temps à partir de la date
contenue dans la variable date en année (aa), mois (mm), jour (jj), heure (hh), minute (mm) et seconde (ss).
@TextToTime(chaine) Conversion du contenu d’une variable chaine de type texte en date/heure.
″25/12/2000 00:00:10″ est valide et sera converti.
@Date(aa ;mm ;jj) Retourne au format date/heure la date dont les composants année (aa), mois (mm), jour (jj), heure, minute et seconde ont été fournis en nombres entiers.
@Date(25 ;12 ;2000) retourne 25/12/2000.
Ces fonctions sont utilisées dans ce module pour afficher la date de création d’un document, la date du jour, calculer des valeurs par défaut dans les champs de saisie.
Traitement de listes
Les listes sont des tableaux à une dimension. Les fonctions @ décrites ici sont applicables dans ce module aux champs pour lesquels des valeurs multiples sont autorisées. Dans la suite du cours, d’autres utilisations plus sophistiquées seront détaillées. Voir le module Fonctions avancées du masque.
Fonction @ Description
@Explode(chaine ; sep) Transforme une chaîne de caractères en une liste – chaine –, chaque élément de la liste étant un mot de la chaîne de caractères. Le caractère séparateur des mots est contenu dans sep.
@Implode(liste ; sep) Concatène tous les éléments d’une liste – liste – séparés par le caractère – sep – en une chaîne de caractères.
@Subset(liste ; nbr) Retourne une sous-liste contenant les nbr premiers éléments de liste (si nbr est positif) ou les nbr derniers éléments de liste (si nbr est négatif).
@Sum(liste) Effectue la somme arithmétique de tous les éléments – des nombres – de liste.
@Elements(liste) Retourne le nombre d’éléments de liste.
Il est nécessaire de transformer une liste en une chaîne de caractères – @Explode – lorsqu’un traitement ne doit pas distinguer les éléments.
Tests logiques
Les tests logiques retournent un booléen qui est vrai – @True – ou faux – @False –.
Dans ce module, ils sont utilisés principalement pour valider la saisie d’un utilisateur, sélectionner les documents affichés dans une vue, effectuer un calcul dans une colonne. D’autres utilisations seront détaillées dans les modules suivants.
Fonction @ Description
@If (condition ; expression si vrai ;
expression si faux)
La condition est une expression logique retournant un booléen qui conditionne l’exécution d’une expression si VRAI ou si FAUX.
@Success Retourne 1 VRAI.
@Failure(″message″
) Retourne 0 FAUX en l’accompagnant d’un message.
Arrête le déroulement de la procédure.
@IsError(variable) Teste le contenu d’une variable et retourne 1 VRAI si le contenu de variable est @Error.
Autoriser entrées multiples
Fonction @ Description
@IsMember(valeur ;
liste) Retourne 1 VRAI si le contenu de valeur correspond à un élément de la liste.
@IsNumber(valeur) Retourne 1 si valeur contient un nombre.
@IsTime(valeur) Retourne 1 si valeur contient une date/heure.
@IsNewDoc Retourne 1 si le document est en cours de création et n’a pas encore été enregistré.
@If, @Success et @Failure vont servir pour tester la validité d’une saisie utilisateur.
@If sert également à effectuer des traitements conditionnés comme l’affichage d’une icône dans une colonne de vue d’après le contenu d’un champ.
Fonctions spéciales
Ces fonctions retournent des informations ou exécutent des tâches qui ne se rattachent pas aux types précédents. C’est un groupe très important en quantité et en qualité. La liste qui suit est très partielle.
Fonction @ Description
@UserName Retourne le nom de l’utilisateur courant sous forme d’une chaîne de caractères.
Hélène ROUQUIE/STD/TSOFT
@Name([CN] ; nom) @Name extrait une partie du nom. [CN] signifie Common Name, donc prénom et nom.
Hélène ROUQUIE
@Author Retourne la liste des utilisateurs ayant modifié le document.
@AttachmentLengths Retourne la place occupée – en octets – par les fichiers rattachés dans un document.
@Attachments Retourne le nombre de fichiers rattachés dans un document Notes.
@AttachmentNames Retourne la liste des noms de fichiers rattachés dans un document Notes.
@ClientType Retourne ″Notes″ si le client connecté à l’application utilise le logiciel Notes et ″Web″ s’il utilise un navigateur.
@DbName Retourne le nom de la base actuelle avec son chemin complet incluant les noms de dossiers et le nom du serveur.
@DbColumn(…) Retourne le contenu d’une colonne d’une vue – c’est une liste – dans une base et un serveur donnés.
@DialogBox(…) Affiche un dialogue à l’utilisateur comprenant des champs de saisie et de visualisation.
@DocumentUniqueID Récupère l’identifiant unique d’un document Notes dans une base. Elle sert à établir des liens entre documents.
La plupart de ces fonctions @ seront abordées en détail dans les modules Fonctions avancées du masque et Programmation avancée avec les formules.
Formatage automatique
Formule
HTML LotusScript
Formatage automatique
Le formatage automatique est une aide de saisie qui propose des listes de fonctions, de mots-clés, de classes d’objets… selon le contexte : formules, HTML, LotusScript.
Le formatage est paramétrable dans les propriétés du panneau de programmation.
Formules
La frappe du caractère @ affiche la liste des fonctions @ et des commandes @.
Le choix de @Command propose la liste des commandes @.
Taper jusqu’à ce que la fonction recherchée soit mise en évidence
Appuyer sur la touche pour sélectionner la fonction
La frappe du nom d’une @fonction ou d’une commande @ affiche la liste des paramètres.
HTML
La liste des éléments HTML est proposée dans le panneau de programmation HTML.
Cette fonction est développée séparément Programmation HTML.
LotusScript
Les listes affichées correspondent au modèle objet Domino et ne comprennent pas les instructions du langage.
Designer est capable d’afficher les listes des propriétés et des attributs d’une classe en fonction du type de la variable concernée.
Paramétrage
• Clic droit dans le panneau de programmation, puis commande Propriétés du panneau de programmation…
Cliquer sur l’onglet (Formatage automatique).
• Cocher ⌧Affichage automatique des membres pour voir la liste – Formules : des fonctions @ et commandes @
– HTML : des éléments HTML
– LotusScript : la liste des classes, des attributs et des méthodes
• Cocher ⌧Incrustation automatique des paramètres pour voir les paramètres des fonctions @ et des commandes @
• <Différée> : taper la temporisation entre la frappe d’un caractère et la mise à jour de la liste
Appuyer sur pour faire défiler les listes de paramètres possibles
s est de la classe NotesSession
Membres de NotesSession
Champ : valeur par défaut
Champ modifiable : valeur par défaut
Valeur initiale d’un champ modifiable Codée dans un événement
Exécuté une seule fois à la création du champ L’expression retourne une valeur
stockée par Notes dans le champ
Valeur par défaut
Champ
La valeur par défaut fixe la valeur initiale d’un champ modifiable :
− C’est une expression codée dans l’événement Valeur par défaut du champ modifiable,
− Cette expression ne s’exécute qu’une seule fois à la création du document et avant que l’utilisateur puisse commencer la saisie,
− L’expression retourne une valeur que Notes se charge de stocker dans le champ.
Remarque
Il n’y a pas de mécanisme standard qui permette à l’utilisateur de demander à Notes de remettre la valeur par défaut dès qu’il a commencé à saisir et à modifier les champs.
• Cliquer sur le champ dans le panneau de travail
• Cliquer sur l’onglet (Objets), puis sur Valeur par défaut et saisir l’expression Expressions valides :
Champ de type nombre 24 Champ de type date/heure @ToDay
30 jours à partir d’aujourd’hui :
@Adjust(@ToDay ;0 ;0 ;30 ;0 ;0 ;0 Champ de type Noms @UserName
Champ de type texte, liste dialogue…
″Europe″
Champ : conversion d’entrée
Modification de la valeur saisie dans un champ modifiable Codée dans un événement
Exécuté à chaque enregistrement du document Expression construite avec le champ
L’expression retourne une valeur stockée par Notes dans le champ Fonctions @UpperCase, @LowerCase
@ProperCase, @Trim, @ThisValue
Champ modifiable : conversion d’entrée
Conversion d’entrée
Champ
La conversion d’entrée modifie la valeur saisie dans un champ modifiable :
− L’expression est dans l’événement Conversion d’entrée du champ modifiable,
− L’expression référence la valeur du champ par son nom ou par @ThisValue,
− Cette expression s’exécute à l’enregistrement du document (commande
Fichier/Enregistrer…) et lorsque les calculs de champs sont demandés (commande Vue/Mettre à jour ou touche F9),
− L’expression retourne une valeur que Notes se charge de stocker dans le champ.
• Cliquer sur le champ dans le panneau de travail, puis sur l’onglet (Objets)
• Cliquer Conversion d’entrée et saisir une expression contenant le nom du champ Expressions valides :
@ThisValue Utiliser cette fonction @ de préférence au nom du champ. Elle retourne la valeur du champ.
@Trim(ObjetReunion) ObjetReunion : élimination des espaces superflus.
@ProperCase(@ThisValue) ObjetReunion : combinaison d’une fonction
@Trim et d’une fonction @ProperCase.
@ProperCase(MotsCles) MotsCles : le texte dans le champ est mis en minuscules, la première lettre de chaque mot en majuscule.
@UpperCase(CodeProduit) CodeProduit : mise en majuscule.
@LowerCase(CodeProduit) CodeProduit : mise en minuscule.
Champ : validation d’entrée
Champ modifiable : validation d’entrée
Validation d’entrée Faux : @Failure OK : @Success
Validation de la saisie dans un champ modifiable Codée dans un événement
Exécuté à chaque enregistrement du document après la conversion d’entrée
Expression construite avec le champ L’expression retourne un booléen Vrai ou Faux et un message d’erreur Fonctions @IF, @Success, @Failure,
@IsNull, @ThisValue
La validation d’entrée bloque l’enregistrement du document si la valeur saisie dans un champ modifiable est reconnue fausse.
− L’expression est dans l’événement Validation d’entrée du champ modifiable,
− L’expression référence la valeur du champ par son nom ou par @ThisValue, et éventuellement celui d’autres champs corrélés,
− Cette expression s’exécute à l’enregistrement du document (commande
Fichier/Enregistrer…) et lorsque les calculs de champs sont demandés (commande Vue/Mettre à jour ou touche F9),
− L’expression retourne un booléen – VRAI ou FAUX – que Notes interprète pour autoriser ou interdire l’enregistrement du document,
− @IsNull teste une valeur vide ″″ – du texte, un nombre ou une date/heure –.
• Cliquer sur le champ dans le panneau de travail, puis sur l’onglet (Objets)
• Cliquer Validation d’entrée et saisir une expression contenant le nom du champ Expressions valides :
Le champ ObjetReunion (@This) est-il renseigné ?
@IF( @IsNull(@ThisValue) ; @Failure(″Objet de la réunion : ce champ doit être renseigné″) ; @Success) Si le champ Marche contient ″Velo″, alors le champ TypeVelo (@This) est requis :
@IF ( Marche = ″Velo″ & @IsNull(@ThisValue) ;
@Failure(″Type de vélo : ce champ doit être renseigné lorsque le marché cible est Vélo″) ; @Success)
Champ calculé : valeur
Champ calculé : valeur
Valeur Champ
Valeur d’un champ calculé, calculé à la création, calculé à l’affichage
Codée dans un événement
Exécuté à chaque enregistrement du document et au chargement si calculé à l’affichage Expression construite avec des champs L’expression retourne une valeur stockée par Notes dans le champ Fonctions : arithmétiques, @IF...
Le contenu d’un champ calculé est déterminé par une formule et il n’est pas modifiable par l’utilisateur.
Il existe trois types de champs calculés, chacun ayant un style de codage des formules qui lui est propre. Notes effectue les calculs dans un ordre déterminé qui influe sur la disposition des champs et le résultat de l’évaluation.
Les trois types de champs calculés
Calculé Le champ est physiquement présent dans le document.
Son contenu est calculé à chaque fois que le document est enregistré (commande Fichier/Enregistrer…) et calculé (commande Vue/Mettre à jour ou touche F9).
Calculé à la création Le champ est physiquement présent dans le document.
Son contenu est calculé une seule fois par le masque à la création du document et avant que l’utilisateur voie le document.
Calculé à l’affichage Le champ est physiquement absent dans le document et n’existe qu’en mémoire et à l’écran.
Son contenu est calculé à chaque fois que le document est enregistré (commande Fichier/Enregistrer…) et calculé (commande Vue/Mettre à jour ou touche F9).
Principe général de codage
La valeur du champ est déterminée comme suit :
− C’est une expression codée dans l’événement Valeur du champ calculé,
− L’expression contient habituellement le ou les noms d’autres champs comme variables,
− Lorsque le contenu du champ est déterminé en dehors de son événement valeur – dans un bouton – l’expression est le nom du champ lui-même. Cette situation est développée ultérieurement,
− Cette expression s’exécute à chaque enregistrement (commande
Fichier/Enregistrer…) et calcul (commande Vue/Mettre à jour ou touche F9) du document lorsque le champ est calculé ou calculé à l’affichage,
− Cette expression s’exécute au chargement du document lorsque le champ est calculé à l’affichage,
− L’expression retourne une valeur que Notes se charge de stocker dans le champ.
Cliquer sur cette icône, ou commande Création/Champ...
• <Nom> : taper le nom du champ qui doit être unique dans le masque
• <Type> : sélectionner – Calculé à l’affichage – Calculé à la création – Calculé
• Puis choisir un type – Texte
– Date/Heure – Nombre – Noms – Auteurs – Lecteurs
• Saisir une expression dans le panneau de programmation
Champ calculé à la création
Lorsqu’un champ est défini comme calculé à la création, cela signifie que le masque s’engage à effectuer le calcul une seule fois, à la création du document et avant même que l’utilisateur ait pu saisir quelque chose. L’événement valeur d’un tel champ pourra donc contenir des expressions du type :
@Today Date du jour. Ceci permet de conserver dans un champ la date de création du document (sans l’heure) pour effectuer des
catégorisations dans une vue.
@UserName Nom de l’utilisateur ayant créé le document. Cette valeur est figée et ne sera plus réévaluée par la suite.
Calculé à l’affichage, Calculé à la création, Calculé
Valeur Expression
Remarque
Le contenu d’un champ calculé à la création peut être modifié par une formule de calcul déclenchée depuis un bouton, ou dans un événement de masque ou encore par un agent. La formule qui est inscrite dans l’événement valeur qui lui est attaché ne sera exécutée qu’une seule fois.
Il est recommandé de définir un champ dont le contenu est modifié par des boutons ou d’autres moyens, comme calculé à la création pour des raisons de performances : la formule contenue dans l’événement Valeur n’est pas évaluée inutilement lorsque le document est enregistré ou que les calculs du masque s’exécutent.
Champ calculé
Un champ calculé est évalué à chaque fois qu’un document est modifié. La formule inscrite dans l’événement valeur qui lui est attaché fait référence à d’autres champs et utilise des fonctions @.
Champ calculé à l’affichage
Le contenu d’un champ calculé à l’affichage est simplement présent en mémoire et n’est pas enregistré dans le document. La formule de calcul du champ doit être protégée en cas de besoin. L’une des utilisations de ce type de champ est l’affichage de valeurs obtenues par fonctions @ ou du contenu de champs du document qui ne doivent pas être modifiés.
@Created La date/heure de création
@Modified La date/heure de dernière modification
@Accessed La date/heure de dernière consultation
@Today La date du jour
@Name([CN] ;@Username) Le nom de l’utilisateur courant Categories Le contenu du champ Categories
Recommandation
Les champs calculés sollicitent le client Notes ou le serveur Domino si le client est un navigateur. Un grand nombre de champs calculés – une centaine – correspondent à autant de formules d’événements valeur dont l’exécution consomme des ressources.
Quelques précautions permettent d’optimiser aisément les calculs.
− Définir comme Calculé à la création les champs pour lesquels l’évaluation de la formule ne doit avoir lieu qu’une fois, ou dont le contenu est modifié par d’autres moyens.
− Définir comme Calculé à l’affichage les champs dont le contenu peut être créé à partir d’autres champs et qui n’ont pas besoin d’être sauvegardés dans le document.
− Lorsque deux champs partagent des formules complexes d’accès à des données sur le serveur – vues, documents –, mutualiser le code commun dans un champ calculé à l’affichage.
− Effectuer des tests avant d’exécuter une formule si elle accède à des données sur le serveur : exécuter la formule seulement si c’est nécessaire.
Ces recommandations seront répétées dans les situations correspondantes. Le choix du type de champ doit toujours être réfléchi.
Séquence d’exécution des formules
Ordre d’évaluation des formules
Calculs effectués comme dans un tableur De gauche à droite
De haut en bas Deux passages
Conversion d’entrée et valeur Validation d’entrée
Notes évalue les expressions dans les événements des champs modifiables et calculés en deux passes et à la façon d’un tableur : de gauche à droite et de haut en bas.
− Première passe : événements conversion d’entrée des champs modifiables et valeurs des champs calculé et calculé à l’affichage,
− Deuxième passe : événements validation d’entrée des champs modifiables.
Designer 6.0 Démonstrations/Masques/
Masque\Séquence des calculs
La figure montre l’ordre dans lequel se fera l’évaluation : – Conversion d’entrée de Saisie,
– Valeur de Calcul_1, – Valeur de Calcul_2,
– Conversion d’entrée de SaisieAutre, – Valeur de Calcul_3,
– Validation d’entrée de Saisie,
– Validation d’entrée de SaisieAutre.
Cette logique détermine quelques règles pour disposer les champs sur le masque :
− L’événement valeur de Calcul_2 peut utiliser les champs Saisie et Calcul_1,
− La formule de l’événement valeur de Calcul_2 ne devrait pas faire référence aux champs qui suivent : SaisieAutre et Calcul_3. Cela “marchera” probablement mais le résultat peut être difficile à interpréter,
− Si un calcul utilise la valeur saisie dans un champ, par exemple Saisie sur la figure, et que le champ est vide – l’utilisateur n’a rien saisi –, cela peut provoquer une erreur dans la formule Protection des formules.
Le mécanisme complet des événements de masque est décrit dans un paragraphe séparé. L’explication qui est donnée ici montre que la disposition des champs doit tenir compte des impératifs de présentation et aussi de la séquence de calcul.
Une pratique courante de programmation consiste à grouper les champs calculés à l’affichage contenant des valeurs utilisées par d’autres formules en tête du masque.
Protection des formules
Protection des formules
Des erreurs dans les formules se produisent si
Un champ n’est pas renseigné : il contient un texte vide ""
Ce champ est utilisé dans une formule arithmétique, une fonction
@ requérant un type Date ou Nombre
Le masque exécute toutes les formules au chargement L’utilisateur n’a encore rien saisi
Une erreur arrête le chargement Solution
@IsNull : tester si les champs requis sont vides
@Return : sortir de la formule en retournant une valeur vide
La formule d’un événement valeur doit être protégée si elle manipule des valeurs numériques ou de type Date/Heure. En effet, lorsqu’un champ ne contient rien, qu’il soit de type texte, nombre ou date/heure, il s’évalue comme une chaîne de caractères vide "" qui est souvent notée par convention avec l’expression NULL. Si on mélange dans une expression du caractère et du numérique, une erreur se produira.
Designer 6.0 Démonstrations/Masques/
Formules\Protection des formules
Un masque de saisie contient une série de trois champs modifiables de type numérique à renseigner par l’utilisateur : Prix_1, Prix_2 et Prix_3. Ces champs sont sommés dans un quatrième champ calculé de type numérique – Total – qui s’évalue comme étant la somme des trois champs précédents :
Prix_1 + Prix_2 + Prix_3
Lorsque l’utilisateur affiche le masque, il n’y a pas d’erreur : les trois champs modifiables numériques sont vides ("") et le champ numérique calculé Total s’évalue comme vide ("") : la somme de "" avec "" donne "". En revanche, si l’utilisateur saisit un seul prix et que le calcul s’exécute – par enregistrement du document ou en appuyant sur la touche F9 –, le champ Total ne s’évalue pas
correctement : la formule combine une valeur numérique et deux valeurs vides (""). Un message d’erreur est affiché dans le champ Total.
Il faut donc protéger l’exécution de la formule.
Dans certains cas, le masque ne peut même pas s’afficher. Par exemple, si la formule du champ Total est ( Prix_1 + Prix_2 + Prix_3 ) / 1000 ,ce dialogue s’affiche à la création du document :
Solution recommandée
Le test d’un champ non renseigné se fait par @IsNull : cette fonction @ retourne VRAI si le champ n’est pas renseigné. Elle évite également de connaître la représentation d’un champ non renseigné par une chaîne vide.
La fonction @IF retourne zéro si le champ est vide, sinon, elle retourne le contenu du champ.
@If(@IsNull(Prix_1) ; 0 ; Prix_1) +
@If(@IsNull(Prix_2) ; 0 ; Prix_2) +
@If(@IsNull(Prix_3) ; 0 ; Prix_3)
Solution dans les versions précédentes de Designer
La fonction @IsNull étant une nouveauté de la version 6, la solution adoptée dans les versions précédentes est de comparer le contenu du champ avec la chaîne vide "" ou d’utiliser la variable NULL qui contient une chaîne vide. NULL est une convention d’écriture : ce n’est pas un mot réservé du langage comme c’est le cas avec
LotusScript.
@If( Prix_1 = NULL ; 0 ; Prix_1 ) +
@If( Prix_2 = NULL ; 0 ; Prix_2 ) +
@If( Prix_3 = NULL ; 0 ; Prix_3 ) ou
@If( Prix_1 = "" ; 0 ; Prix_1 ) +
@If( Prix_2 = "" ; 0 ; Prix_2 ) +
@If( Prix_3 = "" ; 0 ; Prix_3 )
Numérique Vide = NULL Message
Calculer avec des dates
Décalage dans le temps
@Adjust(DateOrigine ; AA ; MMM ; JJ ; HH ; MM ; SS) Date du jour, hier, demain
@Today, @Yesterday, @Tomorrow Conversion en date
@TextToTime(DateHeureCaractere) Extraction d’une partie de la date
@Year, @Month, @Day, @Hour, @Minute, @Second Extraction d’une date/heure
@Date(AA ; MMM ; JJ ), @Time(AA ; MMM ; JJ ; HH ; MM ; SS) Calcul de l’âge en jours
@BusinessDays
Calculer avec des dates
L’utilisation de dates dans des calculs a déjà été abordée dans des exemples simples.
Ce paragraphe fait une synthèse des méthodes utilisables avec le langage de formules : décalage dans le temps, valeurs de référence, conversion en date/heure, extraction d’une partie de la date/heure, calcul de l’âge.
Décalage dans le temps
@Adjust ( DateOrigine ; AA ; MMM ; JJ ; HH ; MM ; SS ) Le décalage se calcule à partir d’une valeur d’origine de type date/heure en années, mois, jours, heures, minutes et secondes. Tous les paramètres doivent être présents. Le résultat est une valeur de type date/heure postérieure ou antérieure à la valeur de référence :
− Date/heure postérieure à la valeur de référence : décalage positif,
− Date/heure antérieure à la valeur de référence : décalage négatif.
Exemples
Type de champ Résultat attendu Formule Calculé à la
création
Date de paiement : 30 jours à partir de la date de création du document.
@Adjust ( @Today ; 0 ; 0 ; 30 ; 0 ; 0 ; 0 ) Calculé Date de purge : 90 jours
après la date de dernière modification.
@Adjust ( @Today ; 0 ; 0 ; 90 ; 0 ; 0 ; 0) Calculé Date de début de semaine
(le lundi est le deuxième jour de la semaine) qui précède la date
d’échéance.
@Adjust( DateEcheance ; 0 ; 0 ;
-(@Weekday(DateEcheance) -2 );
0 ; 0 ; 0 )
Protection de la formule
Le premier paramètre doit être de type date/heure et les paramètres suivants de type nombre. Si les types ne sont pas corrects, un message d’erreur apparaît :
La formule doit être protégée si l’un des paramètres peut être non renseigné parce que c’est un champ de saisie du masque : il n’y a pas de valeur par défaut et l’utilisateur peut toujours sciemment ou non effacer le contenu du champ de saisie.
Par exemple :
@Adjust( DateFacture ; 0 ; 0 ; 60 ; 0 ; 0 ; 0 )
envoie un message d’erreur si le champ DateFacture est vide, ce qui est le cas à la création du document. Pour protéger l’instruction, on écrit :
@If (@IsNull(DateFacture); @Adjust( DateFacture ; 0 ; 0 ; 60 ; 0 ; 0 ; 0 ) ; NULL )
@If protège l’exécution de @Adjust en retournant NULL (du vide) si DateFacture n’est pas renseignée et contient NULL (du vide).
En reprenant le même exemple, si on suppose que l’utilisateur saisit dans un champ Echeance le nombre de jours entre la date de la facture et l’échéance de règlement, la formule s’écrira alors :
@If ( !@IsNull(DateFacture) & !@IsNull(Echeance) ;
@Adjust(DateFacture ; 0 ; 0 ;Echeance; 0 ; 0 ; 0 ) ; NULL )
Si toutes les variables comprises dans @Adjust sont renseignées ( !@IsNull ) alors le calcul est effectué, sinon NULL est retourné.
Remarques
Deux éléments syntaxiques d’expressions logiques apparaissent :
− l’inégalité logique s’écrit != ou <> : ! @IsNull(DateFacture),
− la combinaison d’expressions logiques par la relation AND (notée &). La relation OR est notée | (AltGr + 6).
NULL est la convention d’écriture désignant une variable – par exemple, un champ – dont le contenu est vide. On peut écrire aussi bien DateFacture = ″″. Il vaut mieux adhérer à la convention et écrire DateFacture = NULL.
Valeurs de référence
Fonction @ Description
@Today Retourne la date du jour au format date/heure.
@Tomorrow Retourne la date de demain au format date/heure.
@Yesterday Retourne la date d’hier au format date/heure.
@Now Retourne la date et l’heure actuelle au format date/heure.
Ces valeurs s’utilisent pour le calcul de valeurs par défaut, dans des agents qui déterminent quels sont les documents à archiver, etc.
Pour positionner la valeur par défaut d’une date à trente jours de la date actuelle, on écrit dans l’événement Valeur par défaut :
@Adjust( @Today ; 0 ; 0 ; 30 ; 0 ; 0 ; 0).
Conversion en date
Les deux fonctions @TextToTime et @Date transforment respectivement une chaîne de caractères et des nombres en date/heure.
@TextToTime
@TextToTime(variableTexte) retourne une date/heure si le contenu de variableTexte est une date/heure valide :
Paramètre Valeur retournée
une date seule 02/02/99 02/02/99
une heure seule 15:34 15:34:00
une date et une heure 2/8/00 15:34 02/08/2000 15:34:00 une plage de dates 1/2/00 - 1/2/01 01/02/2000 - 01/02/2001
@Date
@Date( AA ; MMM ; JJ ) retourne une date à partir de paramètres de type nombre.
@Date( 93 ; 02 ; 15 ) retourne 15/02/93.
Cette expression doit être protégée.
Extraction
Une valeur de type date/heure étant donnée, on peut extraire l’année, le mois, le jour, etc., sous forme de nombre. Il s’agit en fait de l’opération inverse de la conversion de nombre en date.
@Year(date), @Month(date), @Day(date) retournent respectivement au format nombre l’année, le mois et le jour d’une variable date au format date/heure.
@Hour(date), @Minute(date) et @Second(date) retournent respectivement au format nombre l’heure, les minutes, les secondes d’une variable date au format date/heure.
Il n’existe pas de fonction extrayant depuis une date le numéro de semaine dans l’année.
Calcul de l’âge : @BusinessDays
@BusinessDays(dateDebut;dateFin;joursExclus;datesExclues) Cette fonction @ retourne un nombre de jours entre deux dates. Les paramètres joursExclus et datesExclues sont optionnels et représentent respectivement les jours de la semaine à exclure – samedi, dimanche – et les jours calendaires à exclure – 1er mai, 25 décembre… – .
Dans les versions précédentes, il fallait faire la différence entre deux dates qui retournent des secondes, puis diviser le résultat par le nombre de secondes dans un jour – 3600 x 24 = 86400 – pour obtenir un âge en jours. Par exemple :
( DateEvaluee – DateReference ) / 86400.
Les événements du masque
onLoad (PostOpen)
Les événements du masque
Valeur par défaut Titre de fenêtre
QueryOpen
Calculé à la création Calculé à l’affichage Calculé : Valeur
onSubmit (QuerySave) Conversion d’entrée Calculé à l’affichage
Calculé : Valeur
Validation d’entrée PostSave
Titre de fenêtre Conversion d’entrée
Calculé à l’affichage Calculé : Valeur Validation d’entrée
PostRecalc
onUnLoad (QueryClose)
Titre de fenêtre QueryOpen
Calculé à l’affichage Valeur
PostOpen
Les événements de champs programmés en langage de formules – Valeur par défaut, Conversion d’entrée et Validation d’entrée – sont appelés suite à une action utilisateur au niveau du masque : l’utilisateur rafraîchit les formules en appuyant sur la touche F9 ou un bouton, et sauvegarde le document en création ou en modification. Les
événements de masque et de champs s’enchaînent. Des événements de masque et de champ ont deux noms du fait de l’adoption des standards de programmation actuels.
Designer 6.0 Démonstrations/Masques/
Masque\Evenements
Action utilisateur Séquence des événements Création du
document
Titre de fenêtre (masque), puis QueryOpen (masque) Valeur par défaut (champ modifiable)
Valeur (champ calculé à la création, calculé, calculé à l’affichage)
onLoad ou PostOpen (masque) Ouverture du
document
Titre de fenêtre (masque), puis QueryOpen (masque) Valeur (champ calculé à l’affichage)
onLoad ou PostOpen (masque) Rafraîchissement
par F9
Conversion d’entrée (champ modifiable) Valeur (champ calculé, calculé à l’affichage) Validation d’entrée (champ modifiable) PostRecalc (masque)
Enregistrement OnSubmit ou QuerySave (masque) Conversion d’entrée (champ modifiable) Valeur (champ calculé, calculé à l’affichage) Validation d’entrée (champ modifiable) PostSave (masque)
onUnLoad ou QueryClose (masque si fermeture fenêtre) Titre de fenêtre (masque si enregistrement simple)
Le titre de fenêtre
Le titre de fenêtre
Le titre de fenêtre est aussi le titre du bouton de tâche Facilité de navigation pour l’utilisateur
Le Titre de fenêtre est un événement de masque qui détermine le texte apparaissant dans la partie supérieure gauche de la fenêtre Notes. Ce texte identifie également les boutons de tâches lorsque plusieurs fenêtres sont ouvertes. Il est recommandé de créer un texte explicite tout en restant court pour faciliter la navigation.
Cet événement s’exécute à la création, à l’affichage et à l’enregistrement d’un document Les événements du masque.
La formule de calcul de l’événement prend en compte les deux situations :
− le document est en cours de création : aucun champ n’est renseigné,
− le document a déjà été enregistré sur disque : les champs sont renseignés.
Les deux principales fonctions @ utilisées sont @IsNewDoc et @If.
Fonction @ Utilisation
@IsNewDoc Booléen :
– retourne 1 (VRAI) si le document en cours de création n’a pas encore été enregistré sur disque,
– retourne 0 (FAUX) s’il a déjà été enregistré.
@If( @IsNewDoc ; expression
nouveau ; expression existant )
@If teste @IsNewDoc et retourne une chaîne de caractères :
– expression nouveau : retourne une chaîne de caractères lorsque le document n’a pas encore été enregistré, par exemple ″Nouveau produit″, – expression existant : retourne une chaîne de caractères lorsque le document a été enregistré, associant une constante et le contenu d’un champ, par exemple ″Fiche ″ + NomProduit
retourne ″Fiche Aspirateur″ si NomProduit contient ″Aspirateur″.
Masquer un champ
Masquer un champ
Visualisation Création, modification
Les formats de saisie sont masqués en visualisation
L’affichage d’un champ avec les interfaces de saisie boutons radio et cases à cocher ne doit être utilisé que si le document est en mode modification. En mode de
visualisation simple, l’affichage du contenu du champ est suffisant.
Ce paragraphe indique comment masquer ou montrer un paragraphe – contenant un champ – selon l’état du document : visualisation ou modification. Des règles plus élaborées prenant en compte notamment la valeur d’un champ du document ou les droits de l’utilisateur courant sont vues dans le module Fonctions avancées du masque et dans le module Mettre en œuvre un workflow.
Définition du paragraphe
Le masque Notes fonctionne selon le paradigme du traitement de texte. Une ligne du masque ou une ligne dans une cellule de tableau représente donc un paragraphe. Il suffit de masquer un élément – un mot, un champ – d’un paragraphe pour que tout le paragraphe soit masqué. L’utilisation de tableaux sans bordures permet de gérer l’affichage ou le masquage d’éléments sur une même ligne de l’écran.
Contrôle de l’interface de saisie d’un champ
L’interface de saisie – boutons radio, cases à cocher… – n’est affichée que lorsque le document est en mode de modification. Par exemple :
Le masque est ouvert dans Designer.
Interface de saisie et de modification
Interface de visualisation et d’impression
• Créer le champ modifiable, par exemple paysCible avec une interface de type case à cocher
• Créer un champ calculé à l’affichage dont la valeur est le contenu du champ modifiable, par exemple paysCible_1 dont l’événement valeur contient la formule paysCible
Les deux champs sont dans des paragraphes séparés, par exemple sur deux lignes successives à l’intérieur d’une cellule de tableau.
• Afficher le dialogue des propriétés du champ modifiable Cliquer sur l’onglet (Masquer le paragraphe quand).
• Cocher les options de masquage en lecture
• Afficher le dialogue des propriétés du champ calculé à l’affichage Cliquer sur l’onglet (Masquer le paragraphe quand).
• Cocher les options de masquage en modification – ⌧Prévisualisé pour modif.
– ⌧Ouvert pour modification – ⌧Copié dans le Presse-papiers
Notes affiche soit le champ modifiable, soit le champ calculé à l’affichage selon l’état du document sans qu’il y ait de perte de place. Les deux champs sont définis sur deux lignes successives dans Designer, Notes calculant la place nécessaire à l’exécution.
L’étiquette Pays ciblés est dans une cellule séparée du tableau et est affichée quel que soit l’état du document.
Nom du
champ modifiable
Masquer le ou les paragraphes si le document est
⌧Prévisualisé pour lecture
⌧Ouvert pour lecture
⌧Imprimé
Les commandes @
@Command([nomcommande] ; argument 1 ; … ; argument n) Exécute une commande de menu
Arguments séparés par un point-virgule ( ; ) Utilisation : exécuter des commandes
Boutons dans les vues Boutons dans les documents Depuis des agents
Enchaînement de commandes : Sauvegarder document
Fermer fenêtre
Les commandes @
Les menus de l’interface utilisateur Notes ont une équivalence en commandes @. Ceci permet, par formule, de déclencher une action normalement effectuée depuis un menu.
Les commandes @ sont très utilisées dans des boutons de masques et de vues.
Syntaxe
@Command( [nomcommande] ; arg1 ; arg2 ; … ; argn )
− nomcommande : rappelle l’enchaînement des menus en anglais,
− arg1, arg2, …, argn : un nombre variable d’arguments, propres à la commande, séparés par des points-virgules ( ; ).
Les commandes @ sont accessibles depuis le panneau de programmation de Designer.
• Cliquer sur l’onglet (Référence)
• Sélectionner Commandes @
• Taper la première lettre du nom d’une commande pour se positionner dans la liste
• Cliquer (Aide) ou appuyer sur la touche
Table des matières – Langage de formules – Langage de formules - Commandes @ de A à Z. Dans cet ouvrage se reporter à l’annexe Commandes @.
Référence Commandes @
Aide et Coller
Actions système
Actions système absentes par défaut Ajout des actions système par menu Suppression en option
Personnalisation Libellé par formule Image ressource
Incorporation dans un menu Ne fonctionnent pas sur le Web
Les actions système sont des actions courantes : modifier un document, l’envoyer...
Elles sont absentes par défaut et il est possible de n’en sélectionner qu’une partie. Les actions système ne sont pas traduites pour le Web : il faut créer une action avec la commande @ correspondante.
• Commande Création/Action/Insérer actions système…
Toutes les actions système sont insérées.
Pour retirer une action système :
• Clic droit sur l’action, puis commande Supprimer…
Pour personnaliser l’action système :
• Double clic sur l’action pour afficher ses propriétés
Libellé calculé par formule
Icône personnalisée
Créer un bouton dans un masque
Créer un bouton dans un masque
Ressource image Panneau d’actions
@Command([FileSave])
@Command([EditDocument])
@Command([FileCloseWindow])
@Command([ToolsSpellCheck])
@Command([FilePrint])
Les boutons définis dans les masques apparaissent dans la barre de boutons dans la partie supérieure du document immédiatement en dessous de la barre de tâches.
L’utilisation de boutons dans les masques offre plusieurs avantages :
− l’utilisateur n’a pas besoin de connaître les menus de Notes,
− les boutons peuvent s’afficher selon le contexte du document (visualisation, modification…) et selon les droits de l’utilisateur,
− l’application n’a pas besoin de tenir compte du logiciel client – Notes ou navigateur – d’autant plus qu’un navigateur n’a pas accès aux menus de Notes.
Ce paragraphe aborde la création d’un bouton dans un masque et l’utilisation des commandes système. Le masquage d’un bouton d’après le contexte est vu dans le paragraphe suivant et aussi dans le module Fonctions avancées du masque. Les commandes @ les plus courantes sont présentées.
Procédure de création d’un bouton
Le masque est en mode modification dans Designer.
Cliquer sur cette icône ou commande Vue/Panneau d’actions.
• Commande Création/Action/Action…
• <Nom> : taper un nom court devant apparaître dans le bouton
• Cliquer ⌧Inclure dans la barre de boutons
• Cliquer ⌧Inclure dans le menu Actions en option
• <Icône> : sélectionner une option
– Aucune : le bouton apparaît avec le texte inscrit dans <Nom>
– Notes : l’icône fait partie du jeu standard Notes
– Perso. : l’icône a été créée comme ressource au format GIF ou JPG
Icône personnalisée
• Cliquer Personnalisée
Cliquer sur ce bouton pour afficher la liste des ressources images.
• Sélectionner une ressource image Remarques
Les images GIF et JPG permettent d’utiliser des images personnalisées dans
l’application, notamment en choisissant leur taille. Elles sont transmises en l’état à un navigateur sans aucune conversion. Il est conseillé d’utiliser ce type d’images en récupérant les images des modèles de bases Notes.
Pour voir la formule correspondant à la ressource image : Cliquer sur ce bouton.
Nom
Inclure dans la barre de boutons Inclure dans le menu Actions
Icône
Appuyer sur les touches de défilement pour prévisualiser les images
Type de l’image
La formule est une expression retournant le nom de la ressource image. L’expression pourrait être plus élaborée et tenir compte de la valeur de champs dans un document pour déterminer l’affichage d’un bouton ou d’un autre. Cette méthode est bien adaptée à une application de workflow.
Icône Notes
• Cliquer Notes
• <Image> : cliquer sur la flèche d’affichage de la liste des images
• Sélectionner une image dans la palette d’images Notes Remarque
Il n’est pas possible d’ajouter des images à cette palette. Par ailleurs, ces images seront converties pour un affichage dans un navigateur. Cette méthode a été conservée d’abord pour des raisons de compatibilité.
Choix de commandes @
La procédure est décrite dans le paragraphe Commandes @.
La formule associée à un bouton d’action peut être autre chose qu’une simple
commande @ et effectuer un traitement complexe : Mettre en œuvre un workflow.
Image
Action
Commande @
Lorsque deux commandes @ s’enchaînent, il faut les séparer par un point-virgule ( ; ).
Par exemple, pour enchaîner l’enregistrement du document et la fermeture de la fenêtre :
@Command([FileSave]) ;
@Command([FilmeCloseWindow]) Disposer les boutons d’actions
• Double clic sur l’action dans le panneau d’actions pour afficher le dialogue des propriétés
• <Position> : choisir la position
Commandes @ courantes
Les commandes listées ici ont un sens dans le contexte d’un masque pour l’affichage ou la création/modification d’un document.
AttachmentDetachALL Détacher tous les fichiers rattachés dans le document.
Compose Création d’un document avec le masque indiqué.
EditBottom Envoyer le curseur sur le dernier champ modifiable.
EditClear Marquer le document pour suppression.
EditDocument Mettre le document visualisé en mode modification.
FileCloseWindow Fermer la fenêtre Notes courante.
FilePrint Imprimer le document.
FileSave Enregistrer le document dans la base.
ToolsSpellCheck Vérifier l’orthographe.
ViewRefreshFields Exécuter les formules de calcul.
Certaines commandes @ exécutées depuis un bouton devraient être cachées selon l’état du document.
Caché si ouvert en lecture Caché si ouvert en écriture
EditBottom Oui EditDocument Oui FileSave Oui ToolsSpellCheck Oui
ViewRefreshFields Oui Position
Masquer un bouton
Masquer un bouton
Visualisation Création, modification
Un bouton est affiché selon le contexte. Par exemple Document en modification : bouton (Enregistrer) Document en visualisation : bouton (Modifier) Eviter les messages d’erreur
Tenir compte des droits de l’utilisateur
Un bouton d’action exécutant la commande @ de fermeture de fenêtre a un sens quel que soit l’état du document, visualisation simple ou modification. Le bouton exécutant la commande @ d’enregistrement du document dans la base n’a de sens que si le document est en mode édition. Il faut donc le cacher si le document est en mode de visualisation simple.
Ce paragraphe indique comment masquer ou montrer un bouton selon l’état du
document : visualisation ou modification. Des règles plus élaborées prenant en compte notamment la valeur d’un champ du document ou les droits de l’utilisateur courant sont vues dans le module Fonctions avancées du masque et dans le module Mettre en œuvre un workflow.
La procédure est semblable à celle utilisée pour un champ, la seule différence étant que le bouton d’action se trouve dans la barre d’actions et non dans un paragraphe.
• Afficher le dialogue des propriétés de l’action Cliquer sur l’onglet (Masquer).
• Cocher les options de masquage selon l’action et l’état du document (lecture ou modification)
Masquer l’action lorsque le document est …
Action case à cocher
La case est cochée d’après la valeur d’un champ Indication de l’état d’une action
Non cochée : à faire ou disponible Cochée : action effectuée
Libellé construit par formule
Voici une nouveauté de la version 6 particulièrement bien adaptée aux applications de workflow dans lesquelles un document change d’état dans le courant du processus : la case à cocher est un moyen simple de signaler ce qui doit être fait et ce qui a été fait.
Cette fonction jointe au calcul du libellé du bouton rend ce dernier porteur de plus d’informations.
Cette fonction est illustrée par un scénario dans lequel le bouton sert à valider un document dont l’état est enregistré dans un champ Etat. Le libellé de ce bouton affiche l’état du document une fois approuvé.
• Créer l’action
• <Nom> : ce champ n’est pas utilisé si le libellé est renseigné
• <Libellé> : taper une formule, par exemple
@If(@IsNull(Etat) ; "Attente d'approbation" ; Etat )
Le libellé calculé invite l’utilisateur à décider du statut du document lorsque le champ Etat est vide, sinon il affiche le contenu de Etat.
• <Type> : sélectionner Case à cocher
• <Valeur> : taper une formule qui indique quand la case doit être cochée.
Dans l’exemple, lorsque Etat est renseigné
! @IsNull(Etat) La formule de l’action est :
@If(@IsNull(Etat); @Success ; @Return(Null));
listeEtat := "Approuve" : "Refuse" : "Suspendu";
@Command([EditDocument]);
FIELD
Etat:=@Prompt([OkCancelList];"Approbation";"Donnez votre avis";Etat;listeEtat);
@Command([EditDocument]);
@Command([ViewRefreshFields])
