6. Les listings¶
Sommaire
6.1. Introduction¶
Il est décrit dans ce paragraphe, l’utilisation et la configuration des listings d’enregistrements issus de la base de données présentés sous forme de tableaux.
La gestion des tableaux se base sur la classe table
définie dans le script
core/om_table.class.php
.
Un listing se configure via un script sql/pgsql/<OBJ>.inc.php
. Il permet de
stocker les éléments de la requête à l’affichage du contenu.
6.2. Les éléments tab et soustab¶
L’appel à ces scripts permet d’afficher un tableau d’enregistrements de l’objet passé en paramètre.
6.2.1. tab¶
URL : "".OM_ROUTE_TAB.""
ou "../app/index.php?module=tab"
application::view_tab()
Paramètres :
Paramètre | Requis ? | Description |
---|---|---|
obj | O | Nom de l’objet à afficher |
premier | N | Premier enregistrement a afficher |
recherche | N | Chaine recherchee (recherche simple) |
selectioncol | N | Colonne choisie pour la recherche (recherche simple) |
tricol | N | Colonne choisie pour le tri (+/-) |
valide | N | Valilite des objets a afficher (true/false) |
advs_id | N | Id unique de la recherche avancée |
mode | N | |
contentonly | N |
6.2.2. soustab¶
URL : "".OM_ROUTE_SOUSTAB.""
ou "../app/index.php?module=soustab"
application::view_soustab()
Paramètres :
Paramètre | Requis ? | Description |
---|---|---|
obj | O | Nom de l’objet à afficher |
premier | N | Premier enregistrement a afficher |
recherche | N | Chaine recherchee (recherche simple) |
tricol | N | Colonne choisie pour le tri (+/-) |
valide | N | Valilite des objets a afficher (true/false) |
retourformulaire | N | |
idxformulaire | N | |
contentonly | N |
L’appel à soustab est fait en javascript depuis un formulaire afin d’afficher les informations liées à l’enregistrement en cours d’édition.
6.3. Configuration¶
Un listing se configure via le script sql/pgsql/<OBJ>.inc.php
.
6.3.1. $ent
¶
Titre (fil d’ariane) de la page.
<?php
$ent = _("administration")." -> "._("om_parametre");
?>
6.3.3. $table
¶
Table de référence (il peut y avoir une ou plusieurs jointure). Clause FROM de la requête du listing.
<?php
$table = DB_PREFIXE."om_parametre";
?>
6.3.4. $champAffiche
¶
Liste des champs du tableau
<?php
$champAffiche = array(
'om_parametre',
'libelle',
'valeur',
'om_collectivite',
);
?>
6.3.5. $champRecherche
¶
Champs pour la recherche.
<?php
$champRecherche = array(
'libelle',
'valeur',
);
?>
6.3.9. $tab_title
¶
Titre de l’onglet du listing. Si cette valeur n’est pas définie alors c’est <OBJ> qui est utilisé ou plutôt la traduction de <OBJ>.
<?php
$tab_title = _("paramètre");
?>
6.3.10. $tab_description
¶
Description de la page. Si cette valeur n’est pas définie alors aucune description n’apparaît.
<?php
$tab_description = _("Ce listing présente tous les paramètres spécifiques à l'utilisateur connecté.");
?>
6.3.11. $tab_actions
¶
Voir le paragraphe dédié : Actions des tableaux.
6.4. Actions des tableaux¶
La surcharge des actions de tableaux se fait via les scripts
sql/sgbd/objet.inc.php
.
L’ajout d’actions se présente de cette façon :
<?php // Actions en coin ('corner') : ajouter $tab_actions['corner']['ajouter'] = array( 'lien' => OM_ROUTE_FORM.'&obj='.$obj.'&action=0', 'id' => '&advs_id='.$advs_id.'&tricol='.$tricol.'&valide='.$valide.'&retour=tab', 'lib' => '<span class="om-icon om-icon-16 om-icon-fix add-16" title="'._('Ajouter').'">'._('Ajouter').'</span>', 'rights' => array('list' => array($obj, $obj.'_ajouter'), 'operator' => 'OR'), 'ordre' => 10, ); // Actions à gauche ('left'): consulter $tab_actions['left']['consulter'] = array( 'lien' => OM_ROUTE_FORM.'&obj='.$obj.'&action=3'.'&idx=', 'id' => '&premier='.$premier.'&advs_id='.$advs_id.'&recherche='.$recherche1.'&tricol='.$tricol.'&selectioncol='.$selectioncol.'&valide='.$valide.'&retour=tab', 'lib' => '<span class="om-icon om-icon-16 om-icon-fix consult-16" title="'._('Consulter').'">'._('Consulter').'</span>', 'rights' => array('list' => array($obj, $obj.'_consulter'), 'operator' => 'OR'), 'ordre' => 10, ); // Action sur la cinquième colonne de contenu $tab_actions['specific_content'][4] = array( 'lien' => OM_ROUTE_FORM.'&obj='.$obj.'&action=2'.'&idx=', 'id' => '&premier='.$premier.'&advs_id='.$advs_id.'&recherche='.$recherche1.'&tricol='.$tricol.'&selectioncol='.$selectioncol.'&valide='.$valide.'&retour=tab', 'lib' => '<span class="om-icon om-icon-16 om-icon-fix delete-16" title="'._('Consulter').'">'._('Consulter').'</span>', 'rights' => array('list' => array($obj, $obj.'_consulter'), 'operator' => 'OR'), 'ordre' => 10, ); ?>
Plusieurs emplacements d’actions existent :
- corner : actions dans la première cellule du tableau
- left : action situées dans la première colonne, disponibles pour chaque élément du tableau
- content : action sur le contenu du tableau
- specific_content : action sur une colonne de contenu du tableau
6.4.1. Les actions par défaut¶
Par défaut seules les actions ajouter
et consulter
sont disponibles
depuis les tableaux.
6.4.2. Créer de nouvelles actions¶
La création d’actions pour un tableau particulier se fait depuis le répertoire
sql/sgbd/
.
Les actions doivent se définir dans les fichier objet.inc.php
de la manière
suivante:
<?php
$tab_actions['left']['modifier'] = array(
'lien' => OM_ROUTE_FORM.'&obj='.$obj.'&action=1'.'&idx=',
'id' => '&premier='.$premier.'&advs_id='.$advs_id.'&recherche='.$recherche1.'&tricol='.$tricol.'&selectioncol='.$selectioncol.'&valide='.$valide.'&retour=tab',
'lib' => '<span class="om-icon om-icon-16 om-icon-fix edit-16" title="'._('Modifier').'">'._('Modifier').'</span>',
'rights' => array('list' => array($obj, $obj.'_modifier'), 'operator' => 'OR'),
'ordre' => 20,
);
?>
6.4.2.1. Définition de l’action¶
La première clé de $tab_actions
permet choisir la position d’affichage:
corner
pour les actions en coin;left
pour les actions de gauche.
Note
Depuis la version 4.3.0 d’openMairie, il est désormais possible d’afficher
plusieurs actions dans le coin du tableau (au niveau de l’action
ajouter
).
La seconde clé de $tab_actions
permet de définir la nouvelle action. Cette
clé doit être différente de: ajouter
, consulter
, modifier
et
supprimer
.
Les clés lien
, id
et lib
s’utilise de la même manière qu’avant.
6.4.2.2. Définition du mode d’affichage en sous-tableau¶
La clé ajax
permet d’indiquer si l’action doit être affichée en ajax ou non
dans les sous-tableaux:
true
, l’action utilisera la fonctionajaxIt()
;false
, l’action n’utilisera pas la fonctionajaxIt()
.
6.4.2.3. Définition de l’ordre d’affichage¶
La clé ordre
permet de déterminer l’ordre d’affichage par rapport aux autres
actions.
Chaque action dispose d’une valeur numérique permettant de définir sa place au sein d’une position. L’action numéro 1 s’affichera en premier, l’action numéro 10 s’affichera après les actions de numéro inférieur, etc.
Ordre des actions par défaut d’openMairie:
- ajouter à pour ordre 10 dans la position
corner
; - consulter à pour ordre 10 dans la position
left
.
Si la position corner
est sélectionnée:
- 9, l’action s’affichera avant l’action
ajouter
; - 11, l’action s’affichera après l’action
ajouter
.
Si la position left
est sélectionnée:
- 9, l’action s’affichera avant l’action
consulter
; - 11, l’action s’affichera après l’action
consulter
.
6.4.2.4. Définition des droits d’affichage¶
La clé rights
permet de définir le ou les droits nécessaires à l’utilisateur
pour visualiser cette action. Cette clé est optionnelle. Si rights
n’existe
pas, tous les utilisateurs pourront visualiser cette action s’ils peuvent
visualiser le tableau correspondant.
La clé list
permet de définir le tableau des droits nécessaire.
La clé operator
permet de définir l’opérateur utilisé pour pour vérifier les
droits de la liste list
:
OR
, l’utilisateur doit avoir au moins un droit;AND
, l’utilisateur doit avoir tous les droits.
6.5. Les fonctionnalités¶
- la recherche simple
- la recherche avancée
- la pagination
- le tri
- les éléments archivés
- l’export PDF
- l’export CSV
- les actions
6.5.1. Le tri¶
Par défaut le listing est trié en fonction du critère ORDER BY de la requête paramétrable via la variable $tri dans le script sql/<SGBD>/<OBJ>.inc.php :
<?php
// Critère de tri par défaut
$tri = "";
// Exemple de tri su la colonne libellé de la table om_droit
$tri = " ORDER BY om_droit.libelle ";
?>
Une fois le listing chargé avec le tri par défaut, l’utilisateur peut choisir de trier sur une colonne en particulier en cliquant sur le titre de la colonne.
6.5.1.1. Premier clic pour le tri croissant¶
Marqueur représentant le tri croissant :
<span class="ui-icon ui-icon-triangle-1-s"><!-- --></span>
6.5.1.2. Second clic pour le tri décroissant¶
Marqueur représentant le tri décroissant :
<span class="ui-icon ui-icon-triangle-1-n"><!-- --></span>
6.5.1.3. Troisième clic pour aucun tri particulier¶
Marqueur représentant aucun tri particulier :
<span class="ui-icon ui-icon-triangle-1-e"><!-- --></span>
6.5.2. L’export CSV¶
L’export CSV peut être activé seulement si la recherche avancée est configurée sur le listing. Il suffit donc de rajouter dans le tableau de paramétrage de cette dernière la clé “export” avec la valeur array(“csv”, ) comme le montre l’exemple suivant :
$options [] = array (
'type' => 'search',
'display' => true,
'advanced' => $champs,
'export' => array('csv',),
'default_form' => 'advanced',
'absolute_object' => 'facture'
);
Note
Par défaut l’export CSV reprend la requête SQL d’affichage définie précédemment.
Le script de paramétrage ../sql/pgsql/<OBJ>.export_csv.inc.php
permet
de surcharger ses paramètres.
Exemple d’utilisation : écraser $champAffiche
pour redéfinir les colonnes du CSV exporté.
6.5.3. La recherche avancée¶
6.5.3.1. Les différents types de recherche¶
6.5.3.1.1. Recherche simple¶
Cette recherche est celle disponible par défaut sur les tableaux d’openMairie.
Elle permet de:
- rechercher une valeur dans une colonne parmi toutes celles affichées;
- rechercher une valeur dans toutes les colonnes affichées;
- rechercher des valeurs approximatives.
Note
Il est possible de modifier la liste des colonnes dans laquelle est effectuée
la recherche. Cette liste ne correspond pas forcément aux colonnes
affichées. Elle correspond seulement par défaut, c’est à dire lorsqu’aucune
surcharge ne modifie les fichiers générés dans gen/sql/
.
6.5.3.1.2. Recherche avancée¶
Cette recherche est une fonctionnalité qui peut être activée et configurée manuellement pour un ou plusieurs tableaux donnés.
Elle permet de:
- afficher un formulaire de recherche mono-critère permettant d’effectuer des recherches strictes ou approximatives;
- afficher un formulaire de recherche multi-critères permettant d’effectuer des recherches strictes ou approximatives;
- rechercher des valeurs dans des tables et des colonnes qui ne sont pas affichées.
Le numéro d’action ($maj) consacré à la recherche avancée est le 999.
6.5.3.1.2.1. Recherche avancée mono-critère¶
Le formulaire de recherche mono-critère est un formulaire ne s’affichant que si la recherche avancée est activée. Il permet aux utilisateurs de basculer sur un formulaire similaire à celui de recherche simple lorsque la recherche avancée est activée.
Ce formulaire se comporte de la même manière que celui de recherche simple, avec quelques différences:
- il permet de rechercher des valeurs strictes ou approximatives (par défaut approximatives);
- il recherche dans toutes les colonnes proposées par la recherche simple;
- il conserve les valeurs recherchées après la réalisation d’une action (ajout, modification, etc…);
- il dispose d’un bouton
Vider le formulaire
permettant de vider les champs; - il dispose d’un bouton
+
permettant de basculer sur le formulaire multi-critères.
6.5.3.1.2.2. Recherche avancée multi-critères¶
Le formulaire de recherche multi-critères est un formulaire ne s’affichant que si la recherche avancée est activée. Il permet aux utilisateurs de bénéficier de plusieurs champs, et ainsi effectuer des recherches plus précise qu’avec le formulaire de recherche simple.
Description du formulaire:
- il peut afficher plusieurs champs, de type texte, nombre, date ou liste à choix;
- il permet, pour chaque tableau, de configurer la liste des champs affichés;
- il permet, pour chaque champ, de rechercher des valeurs strictes ou approximatives (par défaut approximatives);
- il permet, pour chaque champ, de rechercher des valeurs dans des tables et des colonnes qui ne sont pas affichées;
- il conserve les valeurs recherchées après la réalisation d’une action (ajout, modification, etc…);
- il dispose d’un bouton
Vider le formulaire
permettant de vider les champs; - il dispose d’un bouton
+
permettant de basculer sur le formulaire mono-critère.
6.5.3.2. Configuration de la recherche avancée¶
6.5.3.2.1. Activation¶
Exemple avec le modèle om_utilisateur
.
Pour activer la recherche avancée, rendez-vous dans le fichier
sql/sgbd/om_utilisateur.inc.php
et ajoutez la configuration suivante au
tableau d’options:
<?php
$options[] = array('type' => 'search',
'display' => true,
'advanced' => $champs,
'default_form' => 'advanced',
'absolute_object' => 'om_utilisateur');
?>
Note
A partir de la version 4.3.0 d’openMairie, le tableau $options
est
disponible dans les fichiers sql/
de l’application. Il n’est plus
nécessaire de le déclarer manuellement.
La clé type
est obligatoire. Elle permet de définir le type de l’option.
Pour une recherche il faut saisir search
.
La clé display
est obligatoire. Elle permet d’afficher ou non la recherche,
tout en conservant sa configuration.
true
permet d’afficher la recherche;false
permet de masquer la recherche.
La clé advanced
est obligatoire (pour la recherche avancée). Elle permet de
préciser que le formulaire de recherche est un formulaire de recherche avancée
et non simple. Cette clé doit contenir le tableau des champs configurés pour la
recherche (voir plus bas pour la configuration des champs).
La clé default_form
est optionnelle. Elle permet de choisir quel formulaire
de recherche est ouvert par défaut. La valeur advanced'
permet d’afficher le
formulaire multi-critères. Les autres valeurs, ou si default_form
n’est pas
configuré, affichent le formulaire mono-critère.
La clé absolute_object
est obligatoire. Elle permet de spécifier à
openMairie le nom du modèle l’objet recherché. Ce nom est celui du fichier dans
obj/
, ici om_utilisateur.class.php
(sans son extension).
6.5.3.2.2. Autres paramètres¶
Wildcard
Le wildcard permet de rendre la recherche stricte ou approximative.
Cette option peut se configurer pour un ou plusieurs modèles particuliers dans
les fichiers correspondants du répertoire sql/
de l’application. Elle peut
également être configurée de manière globale pour l’ensemble dans modèle
à partir du fichier dyn/tab.inc.php
.
Par défaut, il est paramétré de la manière suivante:
<?php
$options[] = array('type' => 'wildcard', 'left' => '%', 'right' => '%');
?>
left
détermine, dans la requête SQL de recherche, le caractère ajouté au début (à gauche) de la valeur recherchée;right
détermine, dans la requête SQL de recherche, le caractère ajouté en fin (à droite) de la valeur recherchée.
Avec cette configuration lorsque le mot « admin » est recherché dans une colonne, toutes les valeurs contenant « admin » sont retournées.
En modifiant la configuration de cette manière:
<?php
$options[] = array('type' => 'wildcard', 'left' => '', 'right' => '%');
?>
Seules les valeurs commençant par « admin » seront retournées.
Enfin avec:
<?php
$options[] = array('type' => 'wildcard', 'left' => '', 'right' => '');
?>
Seules les valeurs égales exactement à « admin » seront retournées.
6.5.3.3. Configuration des critères de recherche¶
La recherche avancée ne fonctionnera pas tant que la liste des champs du formulaire multi-critères n’aura pas été créée. Ces champs sont appelés ici des critères de recherche.
6.5.3.3.1. Configuration simple¶
Un critère de recherche est représenté par un tableau PHP contenant sa configuration.
<?php
$champs['identifiant_utilisateur'] =
array('colonne' => 'om_utilisateur',
'table' => 'om_utilisateur',
'type' => 'text',
'libelle' => _('Identifiant'),
'taille' => 10,
'max' => 8));
?>
La clé identifiant_utilisateur
est le nom du champ HTML qui sera affiché
sur le formulaire.
La clé colonne
est obligatoire. Elle contient le nom de la colonne de la
base de données qui sera interrogée si la variable $_POST
contient la clé
identifiant_utilisateur
.
La clé table
est obligatoire. Elle contient le nom de la table de la base
de données qui sera interrogée si la variable $_POST
contient la clé
identifiant_utilisateur
.
La clé 'type
est obligatoire. Elle contient le type du champ HTML à
afficher. Cela peut être date
, text
, select
, ou tout autre méthode
de la classe formulaire
. Pour les champs de type select
, le nom du champ
HTML doit être le même que le nom de la colonne.
La clé libelle
est obligatoire. Elle contient le libellé qui sera affiché à
côté du champ dans le formulaire de recherche.
La clé taille
est optionnelle. Elle contient la taille du champ HTML
(attribut HTML size
).
La clé max
est optionnelle. Elle contient la longueur maximale de la valeur
du champ HTML (attribut HTML maxlength
).
Une fois tous les critères de recherche configurés, il faudra simplement
vérifier que le tableau des critères est bien utilisé par l’option de type
search
.
Exemple de formulaire pour le tableau du modèle om_utilisateur
:
<?php
$champs = array();
$champs['login'] = array(
'table' => 'om_utilisateur',
'colonne' => 'login',
'type' => 'text',
'libelle' => _('Login'));
$champs['email'] = array(
'table' => 'om_utilisateur',
'colonne' => 'email',
'type' => 'text',
'libelle' => _('E-mail'));
$champs['om_profil'] = array(
'table' => 'om_utilisateur',
'colonne' => 'om_profil',
'type' => 'select',
'libelle' => _('Profil'));
$options[] = array('type' => 'search',
'display' => true,
'advanced' => $champs,
'default_form' => 'advanced',
'absolute_object' => 'om_utilisateur');
?>
6.5.3.3.2. Configuration avancée¶
6.5.3.3.2.1. Créer un intervalle de date¶
Exemple: recherche des utilisateurs crées entre telle et telle date.
<?php
$champs['date_de_creation'] =
array('colonne' => 'creation_date',
'table' => 'user',
'libelle' => _('Date de creation'),
'type' => 'date',
'taille' => 8,
'where' => 'intervaldate');
?>
Cette configuration permet de créer deux champs HTML datepicker
:
date_de_creation_min
: permettra de saisir une date minimaledate_de_creation_max
: permettra de saisir une date maximale
Ces champs permettent de rechercher les utilisateurs dont la date de créations est incluse dans l’intervalle saisi, bornes comprises. Il est possible de ne saisir qu’une seule date afin de rechercher les utilisateurs ayant été créés avant ou après une date particulière.
6.5.3.3.2.3. Tester si une donnée est présente ou non dans un groupe de données¶
Exemple: recherche des utilisateurs administrateurs.
Dans cet exemple, l’information se trouve non pas dans la table utilisateur mais
dans la table administrateur disposant d’une colonne user_id
(clé
étrangère). Il nous faut utiliser une sous-requête pour récupérer l’ensemble des
identifiants de la table administrateur afin de tester si un identifiant
utilisateur est effectivement présent dans cette liste.
<?php
// soit 'user' une table contenant pas la colonne 'is_admin'
// soit 'admin' une table contenant une colonne 'user_id'
$args = array();
$args[0] = array('', 'true', 'false');
$args[1] = array(_('Tous'),
_('Administrateurs'),
_('Utilisateurs simples'));
$subquery = 'SELECT user_id FROM admin';
$champs['administrator'] =
array('colonne' => 'id',
'table' => 'user',
'libelle' => _('Administrateur'),
'type' => 'select',
'subtype' => 'manualselect',
'where' => 'insubquery',
'args' => $args,
'subquery' => $subquery);
?>
Cette configuration permet de créer un champ HTML de type select
avec
trois choix:
- Tous (valeur “”);
- Administrateurs (valeur
true
); - Utilisateurs simples (valeur
false
).
Le tableau $args[0]
contient les valeurs associées aux choix. La valeur
true
indique que les identifiants des utilisateurs doivent se
trouver dans la sous-requête. La valeur false
indique qu’ils ne
doivent pas se trouver dans la sous-requête. Contrairement à l’exemple
« Créer un champ de recherche avec menu déroulant personnalisé », les valeurs ne
seront pas recherchées telles quelles dans la base de données et ne doivent
surtout pas être modifiées.
En sélectionnant « Administrateurs », la requête SQL de recherche sera construite comme suit:
WHERE user.id IN (SELECT user_id FROM admin)
6.6. Les composants¶
Les composants du framework qui gèrent les listings sont :
OM_ROUTE_TAB
OM_ROUTE_SOUSTAB
application::view_tab()
application::view_soustab()
application::get_inst__om_table()
core/om_table.class.php