Document Grid est un plugin Dynacase permettant de construire une interface de consultation de documents sous la forme d'une table HTML dynamique. Ce plugin est bas niveau et est destiné à être intégré dans une page web.
La documentGrid est construite sur le pattern widget de jquery-ui et se comporte donc comme un widget jquery-ui (initialisation, options, évènements, etc.) et est basée sur le plugin datatable de jQuery.
Lors de la création d'une documentGrid le plugin génère un objet d'options approprié pour une dataTable et injecte ensuite cette dataTable dans la page courante.
L'intégration du plugin requiert l'ajout dans la page web des composants suivants :
lib/data/json2.js
JSON
.lib/jquery/jquery.js
lib/jquery-ui/js/jquery-ui-1.8.21.custom.min.js
& lib/jquery-ui/css/smoothness/jquery-ui-1.8.21.custom.css
lib/jquery-dataTables/js/jquery.dataTables.min.js
& lib/jquery-dataTables/css/jquery.dataTables_themeroller.css
DOCUMENT_GRID_UI/Layout/jquery.docGrid-code.js
& DOCUMENT_GRID_UI/Layout/jquery.docGrid.css
Les adresses des éléments sont données à titre indicatif et sont valables dans l'optique d'une intégration au sein d'une application/action.
Les utilisateurs devant avoir accès à DocumentGrid et ses actions associées doivent avoir l'ACL : BASIC de l'application DOCUMENT_GRID_UI.
Idéalement l'initialisation du plugin doit avoir lieu sur l'évènement ready de la page en cours pour permettre à la DOM et aux dépendances d'être chargées au préalable.
L'initialisation de la documentGrid se fait sur une balise <table>
, celle-ci
doit être pré-existante à l'initialisation. On doit ensuite la sélectionner à
l'aide de jQuery et l'initialiser.
Exemple d'initialisation de documentGrid contenant le titre et un bouton permettant d'ouvrir le document :
<html> <head> <title>DocumentGrid</title> <link href="lib/jquery-ui/css/smoothness/jquery-ui.css" rel="stylesheet" type="text/css"/> <link href="lib/jquery-dataTables/css/jquery.dataTables_themeroller.css" rel="stylesheet" type="text/css" /> <link href="DOCUMENT_GRID_UI/Layout/jquery.docGrid.css" rel="stylesheet" type="text/css" /> <script type="text/javascript" src="lib/jquery/jquery.js"></script> <script type="text/javascript" src="lib/jquery-ui/js/jquery-ui.js"></script> <script type="text/javascript" src="lib/jquery-dataTables/js/jquery.dataTables.min.js"></script> <script type="text/javascript" src="DOCUMENT_GRID_UI/Layout/jquery.docGrid-code.js"></script> <script type="text/javascript"> $(document).on("ready", function () { $("#mydocGrid").docGrid({ collection : "MY_COLLECTION", columnsDef : { "defaultFam" : "MYDEFAULTFAM", "columns" : [ {type : "openDoc"}, {id : "title"} ] } }); }); </script> </head> <body> <table id="mydocGrid"></table> </body> </html>
Les éléments en gras sont obligatoires.
false
;true
;true
;false
;true
;"?app=DOCUMENT_GRID_UI&action=GETJSONDOCGRIDCONTENT"
;false
"?app=DOCUMENT_GRID_UI&action=GETCOLUMNSDEFINITION"
;"?app=DOCUMENT_GRID_UI&action=GETENUMCONTENT"
;"?app=DOCUMENT_GRID_UI&action=GETSTATES"
;Pour mettre à jour une option après l'initialisation, on utilise la syntaxe suivante :
$("#mydocGrid").docGrid("option", "<option_name>", "<value>");
note : seules les options collection et criterias peuvent changées une fois la grille initialisée.
Cet objet de configuration donne les éléments permettant d'établir la
configuration des colonnes de la dataTable. Pour ce faire, il possède les
propriétés defaultFam
et columns
.
Tableau de définition des colonnes. Chaque élément est un objet composé des éléments suivants :
famille contenant l'attribut id
type : chaîne de caractères.
Cet élément n'est pas obligatoire dans les cas suivants :
indique le type de la colonne.
Il est utilisé pour définir le type de rendu de la colonne ou pour définir des colonnes virtuelles.
Dans ce cas, il faut utiliser le type "void"
Cette valeur est calculée automatiquement si l'élément en cours est une propriété ou un attribut, sinon sa valeur est obligatoire.
type : chaîne de caractères.
Les types virtuels pré-définis sont :
indique si une icône doit accompagner le rendu de la colonne en cours.
type : booléen
Cette option est valide pour les colonnes de type :
false
Lors de la définition d'une colonne doivent être présent a minima soit l'id, soit le type.
Note : Vous pouvez utiliser d'autres options propres aux colonnes de la datatable mais dans ce cas le fonctionnement n'est pas garanti et il appartient au développeur de faire les ajustements nécessaires.
Plusieurs méthodes sont associées à l'objet documentGrid :
Permet de définir les filtres actuellement en cours sur la grille. Cette fonction prend comme argument un array contenant des objets de la forme suivantes :
enum
et state
.Ces méthodes sont appelées avec la syntaxe suivante :
$("#mydocGrid").docGrid("<fonction_name>");
Les évènements peuvent être écoutés de deux manières différentes :
$("#mydocGrid").on("docgriderror", function(e, ui) { console.log(ui);});
$("#mydocGrid").docGrid({ error : function(e, ui) { console.log(ui);}};
La table peut aussi accepter en entrées un ensemble de critères, ceux-ci sont appliqués à la collection associées à la table (ou le searchDoc, le cas échéant) et seuls les éléments satisfaisant à ces critères sont présentés dans la table et apparaissent dans les décomptes.
Les critères se présentent sous la forme d'un array JavaScript dont chaque ligne est un objet avec le formalisme suivant :
"simple"
, "multiple"
. Les propriétés doivent être de multiplicité "simple"
valeur du critère de recherche.
type : La valeur peut être sous différents formats suivant le type, la multiplicité et l'opérateur :
l'opérateur est une chaîne de caractères décrivant le type de recherche qui sera appliqué, la liste est la suivante :
applicable à tous les types d'attributs/propriété indique que seuls les élements vide seront retenu.
SQL suivant la multiplicité :
%1$s is NULL
,replace(%1$s, '<BR\>', E'\\n') ~ E'^\\\\n+$' or %1$s is NULL'
applicable à tous les types d'attributs/propriété indique que seuls les élements vide seront retenus.
SQL suivant la multiplicité :
applicable aux types : "int", "double", "money", "date", "timestamp", "state", "enum", "docid", "account".
SQL suivant la multiplicité :
%1$s = '%2$s'
,replace(%1$s, '<BR\>', E'\\n') = '%2$s'
applicable aux types : "int", "double", "money", "date", "timestamp", "state", "enum", "docid", "account".
SQL suivant la multiplicité :
applicable aux types : "int", "double", "money", "date", "timestamp".
SQL suivant la multiplicité :
%1$s < '%2$s'
,applicable aux types : "int", "double", "money", "date", "timestamp".
SQL suivant la multiplicité :
%1$s > '%2$s'
,applicable aux types : "int", "double", "money", "date", "timestamp".
SQL suivant la multiplicité :
%1$s >= '%2$s' and %1$s <= '%3$s'
,applicable aux types : "text", "htmltext", "longtext".
SQL suivant la multiplicité :
%1$s ~* '%2$s'
,applicable aux types : "text", "htmltext", "longtext".
SQL suivant la multiplicité :
%1$s !~* '%2$s' or %1$s is NULL
,applicable aux types : "text", "htmltext", "longtext".
SQL suivant la multiplicité :
%1$s ~* '%2$s'
applicable aux types : "text", "htmltext", "longtext".
SQL suivant la multiplicité :
%1$s !~* '%2$s' or %1$s is NULL
applicable aux types : "int", "double", "money", "date", "timestamp".
SQL suivant la multiplicité :
'%2$s' = ANY (regexp_split_to_array(replace(%1$s, '<BR\>', E'\\n'), E'\\n' ))
applicable aux types : "int", "double", "money", "date", "timestamp".
SQL suivant la multiplicité :
'%2$s' <> ALL (regexp_split_to_array(replace(%1$s, '<BR\>', E'\\n'), E'\\n' )) or %1$s is NULL
applicable aux types : "state", "enum", "docid", "account".
SQL suivant la multiplicité :
ARRAY[%2$s] && (regexp_split_to_array(replace(%1$s, '<BR\>', E'\\n'), E'\\n' ))
applicable aux types : "state", "enum", "docid", "account".
SQL suivant la multiplicité :
not(ARRAY[%2$s] && (regexp_split_to_array(replace(%1$s, '<BR\>', E'\\n'), E'\\n' ))) or %1$s is NULL
Note : dans la documentation %1$s
correspond à l'id en cours et %2$s
,
%3$s
aux valeurs en cours.
Voir le § Intégration avec le module docGrid de la documentation du module Dynacase Search Criteria.
Le plugin docGrid utilise plusieurs éléments de CSS :
overlay
est appliquée à l'ensemble des éléments <a>
qui sont destinés à être ouvert dans un overlay,openDoc
,<div class="colorElement"/>
,<span class="multiple firstLevel"/>
,<span class="multiple secondLevel"/>
,<input class="filter"/>
, ceux de type textuel et relation ont de surcroit la classe textFilter (ce qui donne <input class="filter textFilter"/>
), ceux de type énuméré ont la classe enumFilter (ce qui donne <input class="filter enumFilter"/>
)Les parties cliente et serveur communiquent via des requêtes ajax, et le contenu est formaté en JSON.
Le backend par défaut est défini dans le fichier DOCUMENT_GRID_UI/getdocgridcontent.php
et est porté par la fonction getdocgridcontent
, dont le résultat est ensuite encodé en JSON.
Il est possible de créer un backend PHP spécialisé en se basant sur celui par défaut. Pour ce faire le plus simple, et d'intégrer le backend par défaut dans le nouveau.
Un des backend les plus simple que l'on peut créer est celui par défaut qui se présente de la manière suivante :
<?php require_once 'DOCUMENT_GRID_UI/getdocgridcontent.php'; function getjsondocgridcontent(Action &$action) { $content = getdocgridcontent($action); $action->lay->template = json_encode($content); $action->lay->noparse = true; header('Content-type: application/json'); } ?>
Il intègre le backend par défaut en faisant un require du fichier PHP et ensuite appelle la méthode getdocgridcontent en renvoyant son retour en json.
Il est à noter que getdocgridcontent peut prendre en deuxième paramètre un objet SearchDoc et que dans ce cas il n'utilise pas de collection.
Pour pouvoir utiliser un nouveau backend, il faut le déclarer lors de l'initialisation de la docGrid de la manière suivante :
<html> <head> <title>DocGrid</title> <link href="lib/jquery-ui/css/smoothness/jquery-ui-1.8.21.custom.css" rel="stylesheet" type="text/css" /> <link href="lib/jquery-dataTables/css/jquery.dataTables_themeroller.css" rel="stylesheet" type="text/css" /> <link href="DOCUMENT_GRID_UI/Layout/jquery.docGrid.css" rel="stylesheet" type="text/css" /> <script type="text/javascript" src="lib/jquery/jquery.js"></script> <script type="text/javascript" src="lib/jquery-ui/js/jquery-ui-1.8.21.custom.min.js"></script> <script type="text/javascript" src="lib/jquery-dataTables/js/jquery.dataTables.min.js"></script> <script type="text/javascript" src="DOCUMENT_GRID_UI/Layout/jquery.docGrid.js"></script> <script type="text/javascript"> $(document).on("ready", function () { $("#mydocGrid").docGrid({ columnsDef : { "defaultFam" : "MYDEFAULTFAM", "columns" : [ {type : "openDoc"}, {id : "title"} ] } dataTableOptions: { sAjaxSource: "?app=MYAPP&action=MYBACKEND" } }); }); </script> </head> <body> <table id="mydocGrid"></table> </body> </html>
La documentGrid fonctionne en lien avec le serveur Dynacase, le principe de fonctionnement est le suivant :
Le plugin documentGrid est fourni avec une application permettant de la tester sans faire l'ensemble de l'intégration.
Cette application est accessible aux utilisateurs ayant le droit TEST de
l'application DOCUMENT_GRID_TEST à l'adresse :
http://host?app=DOCUMENT_GRID_TEST.
Elle permet de piloter la documentGrid en bas de la page à l'aide de la zone de saisie "objet de configuration". De plus, il est possible de sauvegarder un objet de configuration en cliquant sur le bouton "[save]", celui-ci est alors sauvé dans le localstorage de la page en cours et peut être retrouvé à l'aide du menu déroulant sélectionner un exemple.
De plus, en bas de la page est présenté une balise <pre/>
qui contient le
compte rendu des erreurs relevées par la table lors de son fonctionnement.
** Note: ** l'objet de configuration fourni par défaut est un exemple et ne fonctionne pas sur une installation basique, il vous faut définir votre collection et choisir une famille par défaut existant sur votre contexte.
Ce document est publié sous licence CC http://creativecommons.org/licenses/by-nc-sa/2.0/fr/
Vous êtes libres :
Selon les conditions suivantes :
Guide d'intégration
© Anakeen, Anakeen Labs <labs@anakeen.com>
Module Document Grid, version 1.0
Édition 2
Publié le 03/08/2018
Ce livre a été produit avec easybook 4.8, logiciel libre et open source développé par Javier Eguiluz à l'aide de différents composants Symfony.