Guide d'intégration

Document Grid 1.0

Anakeen Labs <labs@anakeen.com>

Table des matières

Chapitre 1 Introduction

1.1 Fonctionnalités

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.

1.2 Paradigme

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.

Chapitre 2 Mode d'emploi

2.1 Dépendances

L'intégration du plugin requiert l'ajout dans la page web des composants suivants :

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.

2.2 Droits

Les utilisateurs devant avoir accès à DocumentGrid et ses actions associées doivent avoir l'ACL : BASIC de l'application DOCUMENT_GRID_UI.

2.3 Initialisation

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>

2.3.1 Options de configuration

Les éléments en gras sont obligatoires.

collection
nom logique d'une collection, elle est la source des données affichées,
type : chaîne de caractères ;
columnsDef
configuration des colonnes (voir le détail dans le paragraphe dédié),
type : objet javascript 
filterable
indique si grille proposera ou pas des filtres
type :booléen,
valeur par défaut : false ;
sortable
indique si la grille proposera ou pas la possibilité de trier les éléments par colonnes
type :booléen,
valeur par défaut : true ;
dataTableOptions 
objet de configuration de la dataTable associée à la documentGrid,
Note : Les options passées par cette entrée ne sont supportées via le contrat de support, il appartient au développeur de tester le comportement et de faire ci-besoin les ajustements nécessaires.
type : objet javascript  ;
withOverlay
indique si le système d'overlay doit être chargé avec la grille, ce système permet d'ouvrir les liens générés par la grille dans une fenêtre modale.
type :booléen,
valeur par défaut : true ;
offlineColumnsDef 
active ou désactive la recherche de la définition des colonnes sur le serveur. Passer ce paramètre à false évite une requête au serveur lors de l'initialisation du widget, mais vous devez alors fournir la définition complète.
type :booléen,
valeur par défaut : false ;
autoload
active ou désactive le chargement de la table lors de l'initialisation. Lorsque ce paramètre est à false, la table est chargée sans requête server et sans données. l'IHM indique alors "aucune données" et "résultats 0 sur 0". À charge du progammeur de customizer l'IHM.
type :booléen,
valeur par défaut : true ;
gridDataSourceUrl
url de récupération des données alimentant la base
type : chaîne de caractères,
valeur par défaut : "?app=DOCUMENT_GRID_UI&action=GETJSONDOCGRIDCONTENT" ;
columnsDefUrl
url de récupération de la définition des colonnes de la tables, inutile si offlineColumnsDef est à false
type : chaîne de caractères,
valeur par défaut : "?app=DOCUMENT_GRID_UI&action=GETCOLUMNSDEFINITION" ;
filterEnumContentUrl
url de récupération des listes déroulantes pour les énumérés
type : chaîne de caractères,
valeur par défaut : "?app=DOCUMENT_GRID_UI&action=GETENUMCONTENT" ;
filterStateContentUrl
url de récupération des listes déroulantes pour les états
type : chaîne de caractères,
valeur par défaut : "?app=DOCUMENT_GRID_UI&action=GETSTATES" ;
criterias
tableau de configuration de critères s'appliquant à la table. Le format des critères est décrit dans le chapitre sur les critères.

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.

2.3.1.1 columnsDef

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.

defaultFam
nom logique de la famille par défaut des attributs des colonnes
type : chaîne de caractères
columns

Tableau de définition des colonnes. Chaque élément est un objet composé des éléments suivants :

id
nom logique de l'attribut/propriété contenu dans cette colonne
type : chaîne de caractères
label
nom de la colonne à afficher
type : chaîne de caractères
famId

famille contenant l'attribut id
type : chaîne de caractères.
Cet élément n'est pas obligatoire dans les cas suivants :

  • defaultFam est défini,
  • l'élément à représenter est une propriété,
  • l'élément à représenter est une colonne virtuelle.
sortable
indique si la colonne est triable.
Cette valeur est calculée automatiquement si l'élément en cours est une propriété ou un attribut, sinon sa valeur par défaut est false
type : booléen
filterable
indique si la colonne est filtrable
Cette valeur est calculée automatiquement si l'élément en cours est une propriété ou un attribut, sinon sa valeur par défaut est false
type : booléen
type

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 :

openTitle
ajoute une colonne permettant d'ouvrir le document en cours avec le titre du document comme lien,
openDoc
ajoute une colonne avec un bouton pour ouvrir le document. Ouvre le document dans un overlay si withOverlay est à true
render
Permet de surcharger le rendu spécifique d'une colonne.
Un render par défaut est fourni sur l'ensemble des colonnes de type attribut/propriété. Il est appelé avec la string "text", et permet d'avoir un rendu textuel de la colonne.
Sinon render doit être une fonction qui retourne une chaine de caractère qui sera parsée en DOM et intégrée dans la cellule en cours de la table. Elle reçoit en entrée la ligne en cours et a pour scope l'objet de configuration de la colonne en cours type : fonction ou string
withIcon

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 :

  • title,
  • openDoc,
  • openTitle,
  • docid,
  • file,
  • image
withColor
indique si la couleur doit accompagner le rendu de l'état. Cette option est valide pour les colonnes de type state
type : booléen,
valeur par défaut : false
docTitle
indique le nom de l'attribut docTitle. Cette option est valide pour les colonnes de type relation sur lesquel un filtre est prévu. Elle est calculée automatiquement si la grille n'est pas en mode offlineColumnsDef.
type : chaîne de caractères

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.

2.4 Méthodes associées

Plusieurs méthodes sont associées à l'objet documentGrid :

destroy
Permet de détruire la table.
La table ne peut pas être détruite avant son initialisation, toutefois dans ce cas l'ordre de destruction est enregistré et appliqué à la fin du chargement. La table est alors supprimée (la balise reste en place, mais son contenu est vidé),
refresh
Permet de rafraîchir la table. Celle-ci conserve son état courant (page en cours, tri, filtre), mais recharge ses données en effectuant une requête serveur.
getFilters
Permet de récupérer les filtres actuellement en cours sur la grille, sous la forme d'un tableau d'objets JavaScript.
setFilters

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 :

  • id : identifiant du filtre (attrid de l'attribut correspondant à la colonne),
  • value : valeur,
  • text : texte à afficher valable pour les filtres d'attributs enum et state.
resetFilters
Remet les filtres à leur valeur initiale. C'est à dire sans valeur.

Ces méthodes sont appelées avec la syntaxe suivante :

$("#mydocGrid").docGrid("<fonction_name>");

2.5 Événement associés

error
déclenché à chaque erreur détectée par la dataTable.
Il fournit un objet event et un objet erreur (tableau de messages d'erreurs),
change
déclenché à chaque rechargement de la table (filtrage, changement de page, etc). Il fournit un objet event et un objet contenant les informations qui vont être transmises à la dataTable. La modification de cet objet est déconseillée car elle peut avoir comme effet de bord de modifier le contenu de la table.
redraw
déclenché après la mise à jour de la table et son ajout dans la page web.

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);}};

Chapitre 3 Critères

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 :

id
attribut ou propriété sur lequel la collection est filtrée.
Seules les propriété state et title sont utilisables, les attributs de type time et color ne sont pas pris en compte.
type : chaîne de caractères
type
type de l'attribut/propriété en cours. La propriété title doit avoir un type text
type : chaîne de caractères
multiplicity
multiplicité de l'attribut/propriété en cours.
type : chaîne de caractères
Deux valeurs sont possibles : "simple", "multiple". Les propriétés doivent être de multiplicité "simple"
value

valeur du critère de recherche.
type : La valeur peut être sous différents formats suivant le type, la multiplicité et l'opérateur :

  • objet javascript : objet js contenant deux clefs valueMin et valueMax contenant chacune une chaîne de caractères pour les critères ayant un opérateur between,
  • tableau javascript : chaque item est soit un id, soit une clef pour les attributs de type enum, docid multiples,
  • chaîne de caractère : pour tous les autres types d'attributs et d'opérateurs qui ne sont pas mentionnés ci-dessus
operator

l'opérateur est une chaîne de caractères décrivant le type de recherche qui sera appliqué, la liste est la suivante :

dc:na
applicable à tous les types d'attributs/propriété indique que le critère ne sera pas pris en compte,
dc:empty

applicable à tous les types d'attributs/propriété indique que seuls les élements vide seront retenu.
SQL suivant la multiplicité :

  • simple : %1$s is NULL,
  • multiple : replace(%1$s, '<BR\>', E'\\n') ~ E'^\\\\n+$' or %1$s is NULL'
dc:not empty 

applicable à tous les types d'attributs/propriété indique que seuls les élements vide seront retenus.
SQL suivant la multiplicité :

  • simple* : %1$s is not NULL,
  • multiple* : replace(%1$s, '<BR>', E'\n') !~ E'^\\n+$'
dc:equal

applicable aux types : "int", "double", "money", "date", "timestamp", "state", "enum", "docid", "account".
SQL suivant la multiplicité :

  • simple : %1$s = '%2$s',
  • multiple : replace(%1$s, '<BR\>', E'\\n') = '%2$s'
dc:not equal

applicable aux types : "int", "double", "money", "date", "timestamp", "state", "enum", "docid", "account".
SQL suivant la multiplicité :

  • simple : %1$s <> '%2$s' or %1$s is NULL',
  • multiple : replace(%1$s, '<BR>', E'\n') <> '%2$s' or %1$s is NULL
dc:inferior

applicable aux types : "int", "double", "money", "date", "timestamp".
SQL suivant la multiplicité :

  • simple : %1$s < '%2$s',
  • multiple : non applicable
dc:superior

applicable aux types : "int", "double", "money", "date", "timestamp".
SQL suivant la multiplicité :

  • simple : %1$s > '%2$s',
  • multiple : non applicable
dc:between

applicable aux types : "int", "double", "money", "date", "timestamp".
SQL suivant la multiplicité :

  • simple : %1$s >= '%2$s' and %1$s <= '%3$s',
  • multiple : non applicable
dc:contain

applicable aux types : "text", "htmltext", "longtext".
SQL suivant la multiplicité :

  • simple : %1$s ~* '%2$s',
  • multiple : non applicable
dc:not contain

applicable aux types : "text", "htmltext", "longtext".
SQL suivant la multiplicité :

  • simple : %1$s !~* '%2$s' or %1$s is NULL,
  • multiple : non applicable
dc:one contain

applicable aux types : "text", "htmltext", "longtext".
SQL suivant la multiplicité :

  • simple: non applicable,
  • multiple : %1$s ~* '%2$s'
dc:no one contain

applicable aux types : "text", "htmltext", "longtext".
SQL suivant la multiplicité :

  • simple : non applicable,
  • multiple : %1$s !~* '%2$s' or %1$s is NULL
dc:one equal

applicable aux types : "int", "double", "money", "date", "timestamp".
SQL suivant la multiplicité :

  • simple : non applicable,
  • multiple : '%2$s' = ANY (regexp_split_to_array(replace(%1$s, '<BR\>', E'\\n'), E'\\n' ))
dc:no one equal

applicable aux types : "int", "double", "money", "date", "timestamp".
SQL suivant la multiplicité :

  • simple : non applicable,
  • multiple : '%2$s' <> ALL (regexp_split_to_array(replace(%1$s, '<BR\>', E'\\n'), E'\\n' )) or %1$s is NULL
dc:with

applicable aux types : "state", "enum", "docid", "account".
SQL suivant la multiplicité :

  • simple : non applicable,
  • multiple : ARRAY[%2$s] && (regexp_split_to_array(replace(%1$s, '<BR\>', E'\\n'), E'\\n' ))
dc:without

applicable aux types : "state", "enum", "docid", "account".
SQL suivant la multiplicité :

  • simple : non applicable,
  • multiple : 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.

Chapitre 4 Intégration avec le module criterias

Voir le § Intégration avec le module docGrid de la documentation du module Dynacase Search Criteria.

Chapitre 5 Syle (CSS)

Le plugin docGrid utilise plusieurs éléments de CSS :

Chapitre 6 Backend PHP

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>

Chapitre 7 Fonctionnement

La documentGrid fonctionne en lien avec le serveur Dynacase, le principe de fonctionnement est le suivant :

  1. Déclaration de la documentGrid côté client,
  2. Si nécessaire (présence de colonnes liées à des attributs ou des propriétés), la documentGrid fait un appel serveur pour récupérer l'intégralité de la définition des colonnes (colonne triable, filtrable, label de la colonne, type de la colonne),
  3. La documentGrid utilise la définition des colonnes pour construire un objet de configuration adapté à la dataGrid (objet aoColumsDef),
  4. Si la documentGrid est filtrable alors elle construit le footer de la balise table en y ajoutant les filtres nécessaires suivant les colonnes filtrables,
  5. La documentGrid initie la dataTable,
  6. La dataTable effectue le premier chargement de ses données,
  7. La dataTable effectue le rendu des lignes en fonction des données reçues,
  8. Si la documentGrid doit initier le système d'overlay, elle l'attache à la dataTable nouvellement générée,
  9. À chaque opération effectuée sur la table (changement de page, filtre, tri), la dataTable va chercher sur le serveur les données nécessaire à son rafraîchissement et se reconstruit.

Chapitre 8 Test

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.

Liste des illustrations

Licence

Ce document est publié sous licence CC http://creativecommons.org/licenses/by-nc-sa/2.0/fr/

Vous êtes libres :

Selon les conditions suivantes :

Édition

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.

Anakeen

Créé en 1998, Anakeen est un éditeur expert dans l'amélioration de la gestion des processus et de l'information avec pour objectif principal : valoriser les fonctions support en les libérant des tâches à faible valeur ajoutée. Le résultat opérationnel a toujours été recherché par toutes les entreprises et particulièrement aujourd'hui où le moindre détail peut faire la différence afin d'être ou de rester compétitif sur son marché. Pour chaque fonction support, être en situation de valoriser sa contribution au résultat global de l’entreprise est plus que jamais devenu une nécessité.

Impliqué depuis 1998 dans le logiciel libre, Anakeen est un acteur majeur de la gestion de l'information. Nos contributions pour l'utilisation des standards ouverts, la garantie de l'accès au code source et la grande diversité de nos partenaires vous assure pérennité et réversibilité.

L'ensemble du code PHP de Dynacase Platform est disponible sous licence Open Source, le modèle de données est documenté et public. Mais plus que ça, le code source est commenté dans l'objectif de faciliter sa compréhension pour la réutilisation ou la modification. Aussi toute la documentation concernant le produit est mise en ligne sur www.dynacase.org.

En choisissant un logiciel Open Source, vous faites le choix de la sécurité, car vous avez l'assurance de vérifier le fonctionnement du logiciel et la qualité du code.

Nos offres et services, nous permettent d'assurer le financement du développement produit mais aussi de contribuer chaque jour à l'adoption du business model Open Source.