Les variables

Jaspersoft Community 'Read-Only' as of July 8, 2022

Transition to New TIBCO Community Just Weeks Away

You can still search, review wiki content, and review discussions in read-only mode. Please email community@tibco.com with questions or issues requiring TIBCO review or response.

Résumé

( portuguese english )

Les variables peuvent être utilisées pour enregistrer des résultats partiels ou effectuer des calculs complexes avec les données extraites de la "data source". Ces valeurs peuvent ensuite être utilisées dans d'autres parties du rapport, ainsi que dans d'autres variables. Ce tutoriel explique comment créer et configurer une variable, et explique les champs qui la définissent

 

Créer une nouvelle variable ou éditer une variable existante

Comme pour plusieurs autres éléments, toutes les variables définies sont visibles dans le "Outline menu", sous le groupe "Variables". Depuis ce groupe, il est possible de créer une nouvelle variable (clic droit sur l'item "Variables", puis "Create Variable"). Une fois selectionnée, il est possible de voir les propriétés d'une variable dans l'onglet "Properties". Il existe des variables par défaut, qui sont présentes pour tous les rapports. Ces variables sont identifiables par leur nom en gris clair au lieu de noir. Leurs propriétés ne peuvent pas être éditées.

Propriétés de base d'une variable

Au minimum, tous les éléments suivants d'une variable doivent être définis :

  • Name : une string utilisée pour faire référence à la variable. Elle est nécéssaire pour utiliser la variable au sein d'autres expressions ( comme la valorisation d'un "Text Field" ou le calcul d'une autre variable). Pour faire référence à une variable il faut utiliser la syntaxe suivante : $V{variable_name}.
  • Type : nécéssaire car une variable est un objet qui va probablement être utilisé dans d'autres expressions. Son type doit donc être connu pour être correctement manipulé.
  • Expression : la fonction utilisée pour définir la variable. Elle peut être composée de plusieurs champs et variables, et peut utiliser des opérateurs logiques, mathématiques ou autres. Pour définir facilement l'expression, un éditeur d'expression est fourni dans Jaspersoft Studio. Il peut être ouvert en utilisant le bouton à droite du champ texte utilisé pour écrire l'expression. L'expression est évaluée à chaque itération, à chaque enregistrement lu depuis la source de données. S'il n'y a pas de fonction de calcul définie (cela sera expliqué ci-dessous) le résultat de l'expression sera assigné à la variable. Il est donc important que le résultat ait un type compatible avec celui de la variable.
  • Initial Value : la valeur par initiale de la variable, avant la première évaluation de l'expression. La valeur initiale n'est pas une expression, elle ne peut donc pas être définie avec l' éditeur d'expressions. Elle n'est pas obligatoire, mais c'est une bonne pratique de la définir. Supposons que nous avons une variable "variable1" contenant l'expression "new Integer(5)". A chaque enregistrement lu, la variable se verra assigner la valeur 5, la valeur initiale n'est donc pas importante dans ce contexte. En revanche, si l'expression est "$V{variable1}+5", cela signifie qu'à chaque itération, la variable sera incrémentée de 5. Dans ce cas, une valeur initiale est nécessaire sinon la variable sera indéfinie à la première itération, ce qui empêchera les évaluations suivantes.

Autres propriétés d'une variable

La plus complexe des propriétés d'une variable est sa valeur temporelle. Puisque l'expression est évaluée à chaque itération, il est important de comprendre quelle valeur a la variable, et à quel moment. Cela peut être compliqué car l'expression de la variable peut contenir d'autres variables. Pour ces raisons, il existe des mécanismes pouvant être utilisés pour simplifier l'évaluation ou la lecture de la valeur de la variable au cours des itérations.

Evaluation Time

L'"evaluation time" n'est pas un attribut de la variable. C'est un des éléments qui peut utiliser des variables dans son expression (comme un Text Field) et définir le "time" où la valeur de la variable doit être lue. Une variable peut potentiellement changer de valeur à chaque itération, une valeur lue à un moment peut donc être différente de celle lue à un autre moment. Pour chaque élément qui peut utiliser une expression, il est donc possible de spécifier quand l'évaluer. Les valeurs possibles sont :

  • Rapport : la valeur de l'expression est évaluée à la fin du rapport.
  • Page : la valeur de l'expression est évaluée à la fin de chaque page du rapport.
  • Column : la valeur de l'expression est évaluée à la fin de chaque colonne (si le rapport est composé d'une seule colonne, c'est un équivalent de "Page").
  • Group : la valeur de l'expression est évaluée à la fin de la bande contenant l'évaluation time. C'est un cas très particulier, utlisé pour attendre que les autres éléments de la bande soient complétement créés. Typiquement, la valeur des variable sont lues au début de la bande.
  • Bande : la valeur de l'expression est évaluée après la fin de la bande où l'élément contenant cet evaluation time est placé. C'est un cas très particulier, introduit pour attendre que les autres éléments de la bande soient complètement créés. Classiquement, les valeurs des variables sont lues au début de la bande, mais imagineons que nous avons un sous-rapport contenant un paramètre de sortie à imprimer dans le rapport principal. Pour imprimer ce paramètre, il doit être lu lorsque le sous-rapport a été calculé pour que la valeur soit lue lorsque la bande est complètement créée. Dans ce cas, l'"evaluation time" "Band" est nécéssaire.
  • Auto : utilisé lorsqu'il n'y a pas de variables ou de champs qui doivent être évalués à des moments différents. Les variables sont évaluées au moment correspondant à leur "Reset Type" (voir plus bas pour plus d'informations) et les champs sont toujours évalués instantanément. Ce paramètre est utile lorsque des éléments du rapport contiennet des expressions qui combienent des valeurs évaluées à différents moments (par exemple le pourcentage d'un total).
  • Now : la valeur de l'expression est évaluée après la lecture de chaque enregistrement, donc à chaque itération. Il s'agit du comportement par défaut.

Calculation Function

Une fonction de calcul est un attribut d'une variable qui définit à quelle moment la variable peut être utilisée en association avec l'expression pour déterminer sa valeur. Lors de l'utilisation d'une fonction de calcul, la valeur de la variable n'est pas déterminée par son expression. A la place, elle est passée à la fonction de calcul, qui va l'utiliser (cela dépend de la fonction) pour calculer la valeur de la variable. Il y a plusieurs fonctions fournies avec Jaspersoft Studio :

  • Sum : à chaque itération, la valeur de l'expression est ajoutée à la valeur de la variable. C'est un des cas pour lesquels la valeur initiale est très importante.
  • Count : à chaque itération, la valeur de la variable est incrémentée de 1. Cela est valable uniquement si l'expression est différente de "null", sinon la valeur de la variable sera inchangée.
  • Distinct Count : à chaque itération, la valeur de la variable est incrémentée de 1 uniquement si la valeur de l'expression n'a jamais été retournée.
  • Average : la valeur de la variable est la moyenne arithmetique de toutes les valeurs calculées de l'expression.
  • Lowest : la variable prend pour valeur le plus petit élément calculé de l'expression.
  • Highest : la variable prend pour valeur le plus grand élément calculé de l'expression.
  • Standard Deviation : l'écart-type de toutes les valeurs calculées par l'expression.
  • First : la première valeur retournée par l'expression.
  • System : aucun calcul n'est effectué et l'expression n'est pas évaluée. La valeur de la variable sera la dernière valeur qui lui est affectée. Cette option est utile pour stocker des résultats partiels ou le résultat final d'un calcul.

Increment Type

Comme dit ci-dessus, lorqu'une fonction de calcul est définie, la valeur de l'expression est passée à la fonction qui va effectuer le calcul pour la variable. Le comportement par défaut est d'effectuer cette opération pour chaque enregistrement lu, mais parfois un comportement différent est souhaité. En utilisant le paramètre de type d'incrément, il est possible de modifier le moment où la fonction de calcul est utilisée. Les valeurs possibles pour cet attribut sont :

  • Report : la fonction de calcul est appellée uniquement à la fin du raport, en transmettant la valeur de l'expression à ce moment.
  • Page : la fonction de calcul est appellée à la fin de chaque page, en transmettant la valeur de l'expression à ce moment.
  • Column : la fontion de calcul est appellée à la fin de chaque colonne (si le rapport est composé uniquement d'une colonne, ce paramètre est équivalent à Page).
  • Group : la fonction de calcul est appellée au début de chaque occurence du group spécifié. Cette option est visible uniquement si au moins un groupe est défini.
  • None : la fonction de calcul est appellée après la lecture de chaque enregistrment, il s'agit du comportement par défaut.

Rappelez-vous que l'expression est évaluée à chaque enregistrement, indépendamment du type d'incrément choisi, mais la fonction de calcul ne sera utilisée qu'au moment en accord avec le type d'incrément 

Reset Type

Le type de réinitialisation définit à quelle moement une variable doit revenir à sa valeur initiale, ou à 0 si aucune valeur initiale n'est définie. Ce paramètre est utile lorsque la variable est utilisée pour calculer un résultat partiel comme une somme ou une moyenne de certains enregistrements. Les valeurs possibles pour cet attribut sont :

  • Report : la variable est initialisée uniquement une fois à la création du rapport.
  • Page : la variable est initialisée à chaque page.
  • Column : la variable est initialisée à chaque nouvelle colonne (si le rapport n'est composé que d'une colonne, cette option est équivalente à Page).
  • Group : la variable est initialisée au début de chaque occurence du groupe spécifié. Cette option n'est disponible que si un groupe au moins est défini.
  • None : la variable ne sera jamais initialisée, l'expression contenue dans "initial value" est ignorée.

Incrementer Factory Class Name

Les fonctions de calcul sont utiles, mais sont également génériques et limitées aux types numériques. Il est possible d'avoir des besoins plus spécifiques., par exemple dans le cas d'un champ String pour lequel la valeur doit être concaténée. Il est possible d'effectuer cette opération en définissant un nouvel Incrementer. Un Incrementer est un code Java qui étend l'interface JRIncrementerFactory, et peut fournir une fonction de calcul personnalisée pour ce besoin. Toute fonction de calcul récupère la valeur de l'expression et la valeur de la variable, et renvoie le résultat de l'incrément, tout est donc réuni pour effectuer le calcul et renvoyer la bonne valeur.

Les variables fournies

Il existe des variables fournies par défaut dans Jaspersoft Studio et qui sont présentes dans chaque rapport. Elles représentent des informations générales. Ces variables sont :

  • PAGE_NUMBER: A chaque itération, cette variable contient le nombre de pages qui composent le rapport. Si cette variable est lue avec l' "evaluation time" "Report", elle contiendra le nombre de toutes les pages du rapport.
  • COLUMN_NUMER: Contient le nombre de colonnes courant.
  • REPORT_COUNT: Contient le nombre total d'enregistrements traités.
  • PAGE_COUNT: Contient le nombre d'enregistrements traités dans la page courante;
  • COLUMN_COUNT: Contient le nombre d'enregistrments traités au cours de la création de la colonne courante.

Trucs et astuces

  1. Faites attention aux types de variables, très souvent un mauvais résultat provient de là. Par exemple, si l'expression renvoie un nombre mais que la variable est de type String (le type par défaut) alors sa valeur sera toujours zéro.
  2. La forme de l'expression est très importante pour le calcul d'une valeur, spécifiquement lorsque l'expression utilise cette valeur. Illustration dans l'exemple suivant :
  • Un champ nommé "Money_Gained", lu depuis la source de données, qui est un entier pouvant être nul.
  • Une variable "Total1" avec l'expression IF(EQUALS($F{Money_Gained}, null), $V{Total1}, $V{Total1}+$F{Money_Gained}),  valeur initiale de 0 et pas de fonction de calcul.
  • Une variable "Total2" avec l'expression $V{Money_Gained} == null ? $V{Total2} : $V{Total2}+$F{Money_Gained}, valeur initiale de 0 et pas de fonction de calcul.

Les deux expressions peuvent paraître équivalentes : elle font toutes deux la somme de l'argent gagné et la stockent dans la variable lorqu'elle n'est pas nulle (souvenez-vous que s'il n'y a pas de fonction de calcul alors la valeur de l'expression est assignée directement à la variable). Le test pour savoir si la variable "Money_Gained" est nulle est nécessaire car la somme d'un nombre avec la valeur null est null. Additionner une valeur nulle à Total1 ou Total2 changera la valeur à null. Mais même avec ce test, lorsque "Money_Gained" sera nulle pour la première fois, Total1 sera null alors que Total2 aura la bonne valeur.

Cela se produit car les deux expressions ont 2 interpreteurs différents. Le premier interpreteur est Groovy, le second est Java. Le comportement de Java est d'évaluer la condition et ensuite de sélectionner la branche correcte. Au contraire, Groovy calcule les deux branches, puis évaue l'expression et finalement renvoie la branche correcte, déjà évaluée. Ce procédé ajoutera la valeur nulle à Total1 avant d'effetuer le test, ce qui rendre Total1 null. Une astuce pour éviter ce comportement est d'utiliser la variable uniquement dans la branche principale, par exemple Total1 pourait être réécrit comme ceci : $V{Total1}  + IF(EQUALS($F{Money_Gained}, null),0,F{Money_Gained}). La syntaxe est toujours interprétée par Groovy, mais manitenant la variable est en dehors de la condition IF. Même si les deux conditions sont évaluées, la variable conserve sa valeur.

Feedback