Differences

This shows you the differences between two versions of the page.

--- blockdashboardconfigoutputfields [2015/11/21 21:06]
admin [Filtres dynamiques]
+++ blockdashboardconfigoutputfields [2024/04/04 15:50] (current)
@@ Line 1: / Line 1: @@
-===== Bloc Dashboard : Element de tableau de bord - Configuration des données de sortie =====
+===== Output configuration =====
+===== Dashboard block =====
-Ce panneau de paramètres détermine les choix des sorties en mode "table de données". Certains paramètres, comme par exemple les paramètres de cache, peuvent affecter d'autres formes de sorties.
+{{ :blocks:dashboard:output_config_en.png?nolink |}}
-La fonction première de ce panneau est de choisir les colonnes de sorties dans le résultat de la requête (colonnes nommées) et d'alimenter un affichage en table de données. Les tables de données peuvent être de trois format :
+====General considerations=====
-   * Pour des enregistements simples, fournissant des données "à plat" vous opterez pour la sortie "Linéaire".
+The output settings for data or graphs will always use the columns aliases to identify the output fields.
-   * Pour des enregistrements présentant une donnée à deux dimensions, vous pouvez choisir la "Table croisée". La table croisée utilise une dimension simple comme colonnes de la table de rendu, mais peut utiliser un enseble de dimensions de sorties pour créer les lignes de la matrice.
-   * Pour des enregsitrements présentant une caractéristique arborescente reconnaissable* alors vous pouvez activer le rendu "hiérarchique".
-==== Paramètres ====
+====Table type====
-> Note : Cette documentation est un draft. Les requêtes proposées en exemple ne sont pas encore vérifiées
+Three table shape can be choosen for output data. Some table types rely on some available attributes:
-Dans toutes les entrées de type "liste", le séparateur entre champ **DOIT ETRE** le point-virgule. Un certain nonmbre de paramètres secondaires admettent un nombre d'éléments de liste en fonction du nombre d'éléments d'un paramètre primaire. Vous trouverez ci-dessous les informations correspondantes.
+**Raw flat data:** Data are presented as the query output, record by record.
-=== Colonnes de sortie ===
+**Cross table:** Data are shown within a bidimensional array. The configuration will tell:
-Les colonnes de sortie permettent de choisir quelles colonnes de la requête seront utiisées pour l'affichage. Ce choix peut être différent suivant les différents modes de rendus. Certaines colonnes "techniques" n'ont pas à participer à l'affichage.
+  * The output column alias that represents the horizontal dimension (one choice possible only)
+  * The output column aliases that provide the vertical dimensions.
+  * The content of the value cell.
-Les colonnes de sortie doivent être désignées par leur nom d'ALIAS. Par exemple, pour une requête :
+**Tree shaped data:** If the output data provide a hierarchical organization (noticed by id,parent), it may be practical to use a tree representation of the output.
-<code>
+====Output columns====
-SELECT
-   id as id,
-   shortname as sn,
-   fullname as fn
-FROM
-   {course}
-</code>
-vous pourrez ne choisir "que" de ne sortir les colonnes sn et fn :
+This setting lists in order the list of output fields that will be shown in the output. It must use the aliased names of the columns and cannot be SQL expressions. The output list uses semi-column (;) as separator.
-   sn;fn
+//E.g. if the query is://
-** Cas particulier : Colonnes sommatives **
+  SELECT
+     YEAR(FROM_UNIXTIME(time)) as year,
+     count(*) as access
+  FROM
+     mdl_log
+  GROUP BY
+  year
-Vous pouvez avoir besoin, par exemple pour piloter des courbes cumulées, d'extraire une forme "sommative" d'une colonne à résultat numérique. Par exmemple si vous voulez compter le nombre de création de nouveaux cours de manière cumulée par mois sur toute l'année.
-Pour cela vous pouvez utiliser la syntaxe suivante, en lieu et place du simple nom aliasé de colonne :
+//Then the output column list could be://
-Soit la requête :
+  year;access
-<code>
+===Formatting output data===
-SELECT
-   DATE_FORMAT('%Y_%m', FROM_UNIXTIME(timecreated)) as month,
-   COUNT(*) as cccount
-FROM
-   {courses}
-GROUP BY
-   month
-</code>
-Vous pouvez invoquer la somme cumulative du nombre de créations par mois comme ceci :
+This setting accepts a data formatting expression on the "sprintf" syntax basis that will post-format the output values. You should provide as may formatters than output columns. The formatters will apply in order of the output description list, and will complete with "ignore format" formatters the missing descriptors. An empty formatter stands also for "ignore format" signal.
-   month;S(cccount)
+In the preceding sample, you would use:
-=== Format des données de sortie ===
+  %d;%s
-Chaque colonne de sortie fournit une donnée qui peut être formattée avant affichage. Il est possible de spécifier des chaines de formattage sous le format de la fonction sprintf(). Certaines syntaxes additionnelles ont été ajoutée pour des effets non prévus par ces syntaxes standard.
+to format first columns as an integer and the second column as a string.
+Second exampe:
-//Paramètre primaire associé :// Colonnes de sorties
+for, say, a popularity ratio, you may want to format the output as a float value with one single digit in the decimal part. You would use the following formatter for a result giving the ratio per month:
-Exemple :
+  month;ratio
+  ;%.1f
-Soit la requête :
+Note here that the first column (month) has no formatter applied.
+[[http://php.net/manual/fr/function.sprintf.php|Read more about formatting syntax]]
-<code>
+===Outputing HTML glue with referenced columns===
-SELECT
-   DATE_FORMAT('%Y_%m', FROM_UNIXTIME(timecreated)) as month,
-   SUM(1) / 12 as meancreation
-FROM
-   {courses}
-</code>
-Il est alors possible de formater de manière précise la donnée de sortie de la colonne meancreation pour ne lui autoriser par exemple qu'une décimale en sortie :
+Say you may want to show course names having links to browse quickly to the corresponding course. The formatting syntax allows using static HTML glue and reference another column in the output result to produce the cell content.
-   %s;%0.1f
+E.g the following syntax will show this formatting:
-(Le premier format concerne la colonne "month" à exprimer sous forme "texte")
+   <a href="/course/view.php?id=%{cid}">%s</a>
-Quelques valeurs spéciales sont traitées en plus des formats sprintf() :
+References to other columns in the output result uses the %{fieldalias} syntax and will be processed befor the "sprintf" applies.
-  * Formats destinés aux sorties SQL sur fichier :
+===Output fields labels====
-    * NUMERIC : donnée numérique dans une syntaxe d'INSERT
-    * TEXT : donnée texte dans une syntaxe d'INSERT
-  * Formats spéciaux :
-    * **%0 :** Ne pas afficher la donnée
-    * **/%**//regexp//**%/ :** Permet l'extraction d'une partie de la donnée de sortie selon les deux règles suivantes :
-      * si //regexp// contient un motif de sous-capture (motif parenthésé) alors la première sous-capture est retenue.
-      * si //regexp// ne contient aucun motif de sous-capture, c'est la capture principale du motif qui est retenue.
-    * **%hms :** Format converti en heures:minutes:secondes si la donnée d'origine est un nombre de secondes entier
-    * **%hm :** Format converti en heures:minutes si la donnée d'origine est un nombre de secondes entier
-    * **%D :** La date au format Moodle si la donnée est un timestamp unix
-//Amplification négative//
+As technical fieldnames in DB may not have full sense to the end user of the dashboard, you may here rename the field names to more comprehensible names.
-en ajoutant un '-' (moins) devant le code de format, on déclenchera une mis een forme spéciale pour dissocier les valeurs négatives (texte rouge).
+Again; use semi-columns (;) to separate labels, and give labels in same order of the output field list.
-//Insertion d'autres colonnes de sortie//
+Example:
-Dans certains cas, par exemple, pour fabriquer des URLs dynamiques réutilisant certaines colonnes de sortie, il est nécessaire d'invoquer des résultats cachés ou provenant de ces colonnes. Une syntaxe spéciale permet de récupérer la valeur de sortie (de la même ligne de résultat) :
+   Category;Subcategory
-   * **%{**//colname//**} :** où //colname// est l'un des alias de sortie de la requête initiale.
+===Paging size===
-=== Nom des colonnes de sortie ===
+If given, this will add a LIMIT,OFFSET clause to the query to paginate the output. Use pagination on queries that may potentially output a lot of rows.
-Les colonnes de sortie peuvent etre "traduites" en libellés intelligibles pour l'affichage aux utilisateurs. Déifnissez une liste de labels utilisés sur les écrans. Vous donnerez autant de libellés que le paramètre primaire associé.
+===Cache results===
-Exemple :
+when cache results is enabled, the query outputs will be cached to save time when accessing back to the same query output. The database will not have to process again the joins and the aggregators.
-   Mois;Nombre de cours créés
+The TTL (Time To Live) delay of the cache can be adjusted.
-//Paramètre primaire associé :// Colonnes de sorties
+The cron task of the dashboard can be used to program caches refresh and provide some fresh results.
-=== Taille de pagination ===
+===Clean the table display===
-Si la requête cible peut conduire à une sortie d'un très grand nombre de résultats, il peut être convenable, pour la performance des consultations de limiter le nombre de sorties. Si ce paramètre n'est pas défini, toutes les données seront affichées, sinon une pagination sera mise en place dans la requête.
+If this option is used, subsequent rows repeating the same value than the row above will not show the value again. This often leads to a cleaner and more readable view of the data, specially for dimensional context columns that are usually displayed first.
-Précaution : Cette limitation peut affecter la cohérence de résultats affichés sous forme de table croisée ou sous forme hiérarchique. Utilisez là avec prudence pour ces formes d'affichage.
+There is visually a trap to clean values in the last (main payload) columns, as this might be misinterpreted as a lack of data (null) rather than undestanding the data has same value as above. You can fix this asking the cleanup filter no to operate further a given column number.
-La pagination des résultats peut être imposée par certains réglages globaux du bloc Dashboard (Protection contre les résultats massifs).
+===Sortable table===
-=== Activation du cache de résultat ===
+If your query has not a structural hardcoded SORT clause in its body, but you may want the end user sort the data as he wants, you may declare the table sortable. the dashboard will add sorting controls and sort SQL clause for you.
-Le cache de résultat stocke en base de données les résultats bruts de la requête "finale" entièrement paramétrée avec ses composantes dynamiques. Les enregistrements produits par la requête sont préservés dans une table à part pour consultation rapide par la suite, pendant une certaine durée de vie. L'utilisation du cache est particulièrement intéressante sur des requêtes complexes avec beaucoup de jointures. Cela revien à stocker une "vue" en cache, sans intervention technique dans la base de données elle-même.
+===Subtotal separation column===
-=== TTL du cache de résultat ===
+Using summators usually provide a single final summed value of some output fields. In case you need having subtotals in some value output subdomains, you may tell which output field will be used to discriminate subtotals. the dashboard will add an additional subtotal row (for declared summators) summing all rows in a subtotal column single modality.
-C'est la durée (en minutes) pendant laquelle les données seront conservées suite à une requête d'alimentation du cache.
+Note that subtotals can only be calculated if the global output result is sorted on the subtotal separation column.
-=== Nettoyer la table ===
+<html><!-- nomoodle --></html>
+-----
-La production de grandes tables avec beaucoup de données similaires peut rendre la lecture difficile lors de la consultation directe sur écran. La fonction de nettoyage supprime l'affchage d'une donnée si la valeur du résultat précédent est identique pour cette colonne.
+====Credits====
-**Attention :** Cette fonction n'est utilisable sans danger que pour des requêtes où toutes les valeurs sont exprimées. Elle ne permettrait pas de différentier par exemple une case "nettoyée" d'une ligne suivante qui ne contiendrait pas de données du tout.
+  * Valéry Frémaux (valery@activeprolearn.com)- Main design and development
+  * Florence Labord (florence@activeprolearn.com) - documentation and testing
-=== Table triable ===
+[[:blocks:dashboard:userguide|Return to the configuration guide index]] - [[:Blocks:Dashboard|Return to the component index]] - [[:Blocks:Dashboard:QueryCatalogue|Generic query catalog]] - [[:Plugins|Return to the plugins index]] - [[:start|Home]]
-Si vous activez cette option, vous n'avez plus besoin de préciser une clause ORDER BY explicite pour ordonner vos résultats. Le bloc Dashboard vous proposera des commutateurs d'ordre de lecture en haut de chaque colonne des tables de sortie.
+<html><!-- /nomoodle --></html>
-=== Colonne de séparation des sous totaux ===
-si vous avez une colonne numérique (données aggrégables, ce qui exclut le cas de colonnes "ordinales" dont la valeur ne sert qu'à indexer ou ordonner les choses), vous désirerez parfois obtenir, en plus des totaliseurs globaux, des sous-totaux aggrégés suivant une dimension particulière de votre table.
-Vous devez entrer dans cette colonne le nom de la colonne pilotant l'aggrégation des sommes. Les sous-totaux affichés sont ceux des totaliseurs globaux qui ont été définis pour ce tableau de bord.
-Contrainte : pour que les sous-totaux soient produits, il faut que les lignes du résultats soient évaluées dans un ordre qui permet l'aggrégation et l'affichage du sous-total à la fin de chaque groupe de valeur d'aggrégation. C'est pour cela que :
-   * La table doit être triable
-   * Le tri actif doit être celui de la colonne pilote de l'aggrégation des sous-totaux
-Exemple :
-Soit la requête :
-<code>
-SELECT
-  ue.id as ueid,
-  c.shortname as sn,
-  c.fullname as fn,
-  cc.name as cat,
-  COUNT(*) as enrols
-FROM
-  {course} c,
-  {course_categories} cc,
-  {enrol} e,
-  {user_enrolments} ue
-WHERE
-  c.category = cc.id AND
-  c.id = e.courseid AND
-  e.id = ue.enrolid AND
-  e.status = 0
-<%%FILTERS%%>
-<%%PARAMS%%>
-GROUP BY
-sn
-</code>
-qui compte le nombre d'inscriptions dans chaque cours, ce dernier qualifié par sa catégorie. Je souhaiterais pouvoir afficher les sous-totaux d'inscription dans chaque catégorie.
-   - Commencer par ajouter un totaliseur sur les inscriptions (//enrol//)
-   - Puis désigner la colonne //cat// comme pilote de sous-totaux
-   - Rendez la table triable
-   - Affichez le résultat et triez sur la colonne "Catégories" (//cat//)
-les sous-totaux vont être affichés
-{{ :block_dashboard:subtotals_fr.png |}}
-=== type de table ===
-Ce sélecteur permet d'activer des fonctions tabulaires upplémentaires suivant la structure des résultats, comme expliqué au début de ce document.
-Lorsque vous changez le type de table, des paneeaux de paramêtres supplémentaires vont apparaître pour configurer des aspects spécifiques de ce type de représentation.
-==== Filtres dynamiques ====
-Les filtres dynamiques permettent de proposer à l'usager des tableaux de bord des fonctions de filtrage sur le résultat de la requête. Cette possiblité démultiplie l'usage du'ne même requête et permet d'explorer les dimensions qu'elle contient.
-=== Filtres ===
-Ce paramètres (primaire) permet de définir des filtres sur les données de sortie. Les filtres sont automatiquement alimentés par les modalités de sortie de la requête complète. Cela veut dire que toutes les données possibles pour la colonne ne sont pas nécessairement exprimées dans le filtre, mais uniquement les valeurs qui sortent effectivement de la requête si elle était exécutée sans les filtres.
-Un filtre est défini par la ligne (exacte) qui définit la colonne de sortie de la requête. Cette définition doit donc comprendre la fomule, champ de données mais également la mention de l'alias de sortie de la colonne.
-Exemple :
-Pour la requête :
-<code>
-SELECT
-   DATE_FORMAT('%Y_%m', FROM_UNIXTIME(timecreated)) as month,
-   SUM(1) / 12 as meancreation
-FROM
-   {courses}
-</code>
-L'identité correcte du filtre sur les mois est :
-   DATE_FORMAT('%Y_%m', FROM_UNIXTIME(timecreated)) as month
-La définition des filtres étant une liste, vous définirez plusieurs filtres séparés par des points-virgules.
-=== Labels des filtres ===
-Comme pour les données de sortie le bloc Tableau de bord vous propose de renommer ces filtres sous une forme intelligible par les utilisateurs finaux. Donnez autant de libellés que vous avez défini de filtres.
-//Paramètre primaire associé :// Filtres
-=== Défaut des filtres ===
-Les valeurs par défaut seront les modalités activées lors du chargement de la vue du tableau de bord. Cette valeur par défaut est utile lorsque vous obligez le filtre à avoir une valuer exprimée (voir ci-après).
-La valeur par défaut peut être soit une des valeurs visibles, soit un parmi les macros suivantes :
-   * FIRST : Prend par défaut la première modalité du filtre
-   * LAST : Prend par défaut la dernière modalité du filtre
-//Paramètre primaire associé :// Filtres
-=== Options pour les filtres ===
-Un certain nombre d'options sont activables pour modifier le comportement des filtres. Ces options sont représentées par une lettre minuscule. Les options sont combinables pour chaque filtre :
-   * **m :** autorise un sélection multiple dans la liste de filtrage
-   * **s :** force la sélection, c'est à dire interidt l'usage de l'option '*' donnant accès à tous les résultats non filtrés sur cette modalité.
-   * **g :** dans le cadre d'un usage de plusieurs tableaux de bord sur la même page, assigne le fitre au niveau global pour synchroniser le filtrage de plusieurs instances.
-   * **x :** Pour certaines requêtes, notamment celles qui utilisent des aggrégateurs comme COUNT(*), la mise en place des filtres peut échouer. Ce commutateur permet de supprimer le traitement avancé des requêtes et permet dans certains de ces cas de faire fonctionner le tableau de bord.
-[[BlockDashboardUse|Revenir à l'index du guide utilisateur]]

Moodle ActiveProLearn Documentation

User Tools

Site Tools

Differences

Page Tools