Guide d'intégration

Search Criteria UI 1.0

Anakeen Labs <labs@anakeen.com>

Table des matières

Chapitre 1 Introduction
1.1 Fonctionnalités
1.2 Paradigme
Chapitre 2 Mode d'emploi
2.1 Dépendances
2.2 Droits
2.3 Initialisation
2.4 Méthodes associées
2.5 Évènements associés
Chapitre 3 Intégration avec le module docGrid
Chapitre 4 Test

Chapitre 1 Introduction

1.1 Fonctionnalités

Search Criteria UI est un plugin permettant de générer un ensemble de critères de recherche en se basant sur la définition d'un ensemble d'éléments appartenant à une ou plusieurs familles.

1.2 Paradigme

Search Criteria est construit sur le 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 divers plugins de jQueryUI.

Lors de la création d'un criteria le plugin génère la DOM et injecte les différents éléments de recherche.

Chapitre 2 Mode d'emploi

2.1 Dépendances

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

json2 : lib/data/json2.js
cet élément est nécessaire pour faire fonctionner le plugin sur les navigateurs ne possédant pas l'objet JSON.
jquery : lib/jquery/jquery.js
jquery-ui : lib/jquery-ui/js/jquery-ui-1.8.21.custom.min.js & lib/jquery-ui/css/smoothness/jquery-ui-1.8.21.custom.css
widget criterias : SEARCH_CRITERIA_UI/Layout/jquery.criterias-prod.js & SEARCH_CRITERIA_UI/Layout/jquery.criterias.css

json2 : cet élément est nécessaire pour faire fonctionner le plugin sur les navigateurs ne possédant pas l'objet JSON.

Les adresses des éléments sont données à titre indicatif et sont valable dans l'optique d'une intégration au sein d'une action/application.

note: Dans la version finale du produit les dépendances à criteria seront fournies dans un seul fichier js.

2.2 Droits

Les utilisateurs devant avoir accès à Search Criteria et ses actions associées doivent avoir l'ACL : BASIC de l'application SEARCH_CRITERIA_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.

L'initialisation de la Search Criteria 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 des criterias en utilisant une table pour les présenter sur deux colonnes :

<html>
    <head>
        <title>CriteriasUI</title>
 
        <link href="lib/jquery-ui/css/smoothness/jquery-ui.css" rel="stylesheet" type="text/css"/>
        <link href="SEARCH_CRITERIA_UI/Layout/jquery.criterias.css" rel="stylesheet" type="text/css"/>
 
        <script type="text/javascript" src="lib/jquery/jquery-debug.js"></script>
        <script type="text/javascript" src="lib/jquery-ui/js/jquery-ui.js"></script>
        <script type="text/javascript" src="SEARCH_CRITERIA_UI/Layout/jquery.criterias-prod.js"></script>
 
        <script type="text/javascript">
        $("#criterias").criterias({
            criteriasDef : {
            defaultFam : "TST_FMTCOL",
            criterias : [
                    {"id" : "title"},
                    {"id" : "tst_rellatest"},
                    {"id" : "tst_enum"},
                    {"id" : "tst_rellatests"},
                    {"id" : "tst_doubles"}
                ]
            },
            preDefaultInsertRender : function(nb, ct) {
                var pre = "";
 
                if ((nb % 2) == 0) {
                    pre = "<tr style='width : 50%;'><td>"; 
                }else {
                    pre = "<td>";
                }
                return pre;
            },
            postDefaultInsertRender : function(nb, ct) {
                var pre = "";
                if ((nb % 2) == 1) {
                    pre = "</td></tr>"; 
                }else {
                    pre = "</td>";
                }
                return pre;
            }
        });
 
        $("#result").on("click", function() {
            console.log($("#criterias").criterias("getValue"));
        });
        </script>
    </head>
 
    <body>
    <table id="criterias" class="ui-widget" style="width : 100%; table-layout: fixed;">
    </table>
    <button id="result">Get Me Some Results</button>
    </body>
 
</html>

2.3.1 Options de configuration

Les éléments en gras sont obligatoires.

criteriasDef

configuration des critères
type : objet javascript,

preDefaultInsertRender

fonction ou chaîne de caractères qui est insérée devant chaque critère :

fonction : la fonction prend en entrée le numéro d'insertion du critère (0 pour le 1er, 2 pour le second…) et la définition du critère,
et qui doit retourner une chaîne de caractères, qui sera inséré avant le critère lui-même
chaîne de caractères : la chaîne est insérée avant le critère lui-même,

postDefaultInsertRender

fonction ou chaîne de caractères qui est insérée après chaque critère :

fonction : la fonction prend en entrée le numéro d'insertion du critère (0 pour le 1er, 2 pour le second...) et la définition du critère,
et doit retourner une chaîne de caractères, qui sera inséré avant le critère lui-même,
chaîne de caractères : la chaîne est insérée avant le critère lui-même,

note : aucune option ne peut être modifiée après la création des critères.

2.3.1.1 Détail de la configuration :

criteriasDef

cet objet de configuration donne les éléments permettant d'établir la configuration des critères.
Pour ce faire, il possède deux propriétés :

defaultFam

nom logique de la famille par défaut des critères
type :chaîne de caractères

criterias

tableau de définition de critères.
Chaque élément est un objet composé des éléments suivants :

id: nom logique de l'attribut/propriété (les propriétés utilisables sont title et state) contenu dans cette colonne
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 si defaultFam est défini ou pour le titre,
label: label affiché devant le critère
type :chaîne de caractères,
preInsertRender: fonction ou chaîne de caractères qui est insérée devant le critère (remplace preDefaultInsertRender si celui-ci est présent),
postInsertRender: fonction ou chaîne de caractères qui est insérée devant le critère (remplace postDefaultInsertRender si celui-ci est présent),
multiplicity: "simple" ou "multiple" indique si le critère est présenté sous forme pour attribut non multiple ou multiple
type :chaîne de caractères,
type: indique le type d'attribut ou de propriété sur lequel s'effectue la recherche
type :chaîne de caractères,
urlSource: url source de l'appel serveur pour les critères de type énuméré, relation, account et state. Cette URL doit accepter un paramètre "term" qui contient ce qui est actuellement ajouté dans le champs de recherche par l'utilisateur,
et retourner un objet array contenant, pour chaque ligne, un objet avec les trois propriétés key (clef stockée et non affichée), value (affiché à l'utilisateur si cet élément est sélectionné), label (présenté dans la liste déroulante)
defaultValue: valeur par défaut du critère. Le contenu de cet élément doit être de même type que celui du setValue.

note : les id de type account et color ne sont pas encore pris en compte.

2.4 Méthodes associées

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

destroy

Permet de détruire la table.
La table est alors supprimée (la balise reste en place, mais son contenu est vidé),

getValues

Permet de retrouver les valeurs des critères, cette valeur est retournée sous la forme d'un array javaScript qui contient pour chacun de ses éléments les points suivants :

id: identifiant du critère,
kind: type du critère,
type: type de l'attribut/propriété,
multiplicity: indique la multiplicité du critère (multiple ou simple),
operator: opérateur sélectionné,
value: valeur ou array de valeurs

getValue

Identique à getValues mais prend en entrée l'id d'un critère et ne retourne que la valeur de celui-ci,

setValue

Permet d'indiquer la valeur d'un critère. Cette fonction a comme paramètres entrant :

id du critère
valeur à donner au critère :
- chaîne de caractères pour les critères date, text, numérique,
- objet javascript avec les propriétés value1 et value2 pour les critères date et numérique avec l'opérateur between,
- objet javascript avec les propriétés value et key pour les énuméré, relation, account et state simple et tableaux d'objet javascript avec les propriétés value et key pour les énuméré, relation, account et state multiple

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

$("#criterias").criterias("fonction_name");

note : Suite à l'évolution de la docGrid les critères pourront lui être passée directement et ensuite être utilisés par la grid pour filtrer ses résultats.

2.5 Évènements associés

Des évènements sont déclenchés à 2 niveaux :

au niveau de criteria
au niveau de chacun des critères

2.5.1 Événements de plus haut niveau

error: déclenché à chaque erreur détectée.
Il fournit un objet event et un objet erreur (tableau de messages d'erreurs),
draw: déclenché après l'insertion de l'ensemble des critères de recherche

Les évènements peuvent être écoutés de deux manières différentes :

en utilisant les fonctionnalités pour s'attacher à un évènement de jQuery
Il faut alors préfixer l'évènement cible par le nom du widget en minuscule (dans notre cas docgrid)

$("#criterias").on("criteriaserror", function(e, ui) { console.log(ui);});

en s'inscrivant directement à la création du widget :

$("#criterias").criterias({ error : function(e, ui) { console.log(ui);}};

2.5.2 Événements par critère

change: déclenché lorsque la valeur du critère change.
Le premier paramètre envoyé est un objet event, le deuxième contient la nouvelle valeur, ou la valeur ajoutée et la liste des nouvelles valeurs pour les critères enum et relation multiple
preGetValues: uniquement pour les critères relations et énuméré.
Cet évènement est déclenché avant l'envoi de la requête sur le serveur et permet d'ajouter des paramètres à la requête serveur (voir exemple ci-dessous) :

preGetValues : function(evt, ui) {
    ui.additionnalSourceParams = {
        myNewProp : 'theValue'
    };
}

Il est possible de s'attacher aux évènements des critères lors de la création du widget critère de la manière suivante :

$("#criterias").criterias({
  criteriasDef : {
    defaultFam : "TST_FMTCOL",
    criterias : [
      {"id" : "title", 
       change : function(evt, ui) {
        console.log(ui); 
       }},
      {"id" : "tst_rellatest"},
      {"id" : "tst_enum",
       change : function(evt, ui) {
        console.log(ui); 
       }},
      {"id" : "tst_rellatests", preGetValues : function(evt, ui) {
        ui.additionnalSourceParams = {
          myNewProp : 'theValue'
        };
      }, postGetValues : function(evt, ui) {
        console.log(ui);
      },
       change : function(evt, ui) {
        console.log(ui); 
       }
      },
      {"id" : "tst_double"},
      {"id" : "tst_date"}
      ]
  }
});

Chapitre 3 Intégration avec le module docGrid

Les critères sont construits de telle manière à pouvoir être simplement intégré avec le plugin docGrid.
Pour ce faire, il suffit de modifier l'option "criterias" d'une docGrid en lui donnant le retour du getValues d'un criterias. Soit :

$("#result").on("click", function() {
    $("#myTable").docGrid("option","criterias",$("#criterias").criterias("getValues"));
});

Chapitre 4 Test

Le plugin criterias 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 SEARCH_CRITERIA_TEST à l'adresse http://host?app=SEARCH_CRITERIA_TEST

La partie de gauche permet de saisir du code JS et celle de droite du HTML, au clic sur le [publish] le code est exécuté dans la partie basse de la page.

Il est à noter que le code est sauvé sur la page et que celle-ci peut-être rechargée sans perdre le JS ni le HTML.

Liste des illustrations

Figure 1.

Licence

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

Vous êtes libres :

de reproduire, distribuer et communiquer cette création au public
de modifier cette création

Selon les conditions suivantes :

Paternité — Vous devez citer le nom de l'auteur original de la manière indiquée par l'auteur de l'œuvre ou le titulaire des droits qui vous confère cette autorisation (mais pas d'une manière qui suggérerait qu'ils vous soutiennent ou approuvent votre utilisation de l'œuvre).
Pas d'Utilisation Commerciale — Vous n'avez pas le droit d'utiliser cette création à des fins commerciales.
Partage des Conditions Initiales à l'Identique — Si vous modifiez, transformez ou adaptez cette création, vous n'avez le droit de distribuer la création qui en résulte que sous un contrat identique à celui-ci.

Édition

Guide d'intégration
© Anakeen, Anakeen Labs <labs@anakeen.com>
Module Search Criteria UI, 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.