Différences

Ci-dessous, les différences entre deux révisions de la page.

--- clients:scrutarijs [2015/06/18 18:50]
vincent
+++ clients:scrutarijs [2017/07/01 01:44]
vincent [Les fichiers de gabarit HTML]
@@ Ligne 1: / Ligne 1: @@
 ====== ScrutariJs ======
-//ScrutariJs// est un projet de client javascript complexe pour le moteur de recherche Scrutari. Son but est double : montrer toutes les possibilités offertes par l'API Json (et identifier ainsi les manques et les améliorations possibles) et proposer des composants réutilisables et adaptables à d'autres contextes.
+===== Les fichiers de localisation (l10n) =====
-ScrutariJS peut être vu en action aux adresses suivantes (la recherche porte sur la Coredem) :
+L'insertion d'un fichier de localisation est indispensable pour que l'interface soit lisible. Un fichier de localisation est un fichier Javascript où est défini un objet javascript appelé SCRUTARI_L10N dont les noms de propriétés correspondent aux clés de localisation.
-  * [[http://scrutarijs.coredem.info/?engine=coredem]]
+Extrait du fichier pour le français :
-  * [[http://scrutarijs.coredem.info/?engine=coredem&page=frame&width=md]] : avec décomposition de l'écran en deux : à gauche l'interface de recherche à droite l'affichage des résultats
-  * [[http://scrutarijs.coredem.info/?engine=coredem&page=frame&width=lg]] : même chose que précédent pour les écrans vraiment larges (plus de place est donnée au départ à l'interface de recherche)
-ScrutariJs est en HTML 5 et se base sur les bibliothèques [[http://jquery.com|JQuery]] (requêtes Ajax et manipulation du DOM) et [[http://getbootstrap.com|Bootstrap]] (pour la définition des composants et l'adaptation aux tailles d'écran). Les traitements du côté serveur sont fait en PHP.
+<code javascript>
+var SCRUTARI_L10N = {
+  lang:'fr',
+  '_ and':'ET',
+  '_ button_check_all':'Tout cocher',
+  '_ button_close':'Fermer'
+};
+</code>
-Pour le moment, ScrutariJs n'a pas de version empaquetée. Le code source est disponible via le dépôt Subversion :
+Les fichiers de localisation sont définis à part dans le répertoire !!l10n/!!. Ils doivent être insérés spécifiquement.
-  svn co http://depot.exemole.fr/svn/web/apps/coredem.info/scrutarijs
+Exemple :
-Comme JQuery et Bootstrap, ScrutariJs est sous licence [[http://en.wikipedia.org/wiki/MIT_License|MIT]].
-ScrutariJs est composée de deux parties principales : le répertoire scrutarijs/ qui contient le cœur de l'application sous la forme de fichiers statiques Javascript, CSS et d'images et le reste de l'application comprenant principalement des fichiers PHP. Le répertoire scrutarijs est autonome et conçu pour être réutilisable dans d'autres projets sans avoir besoin de PHP. La partie PHP est une exemple d'utilisation de la bibliothèque scrutarijs/ avec des possibilités de configuration pour l'utilisation du même code PHP avec des moteurs différents. Cette partie comprend également des scripts de génération de fichiers (compilation de javascript, fichiers de langue, pour scrutari.js.
+<code javascript>
+<script src="scrutarijs/l10n/fr.js"></script>
+</code>
+===== Les fichiers de gabarit HTML =====
-===== À propos du répertoire scrutarijs/ =====
+Les fichiers de gabarit HTML sont situés dans le répertoire  html/, ils doivent être insérés en plus de scrutarijs.js car ils s'appuient sur des bibliothèques tierces. Il faut donc n'insérer que le fichier correspondant à la bibliothèque utilisée. Pour l'heure, la seule bibliothèque entièrement géré est Bootstrap version 3. La gestion de Bootstrap 2 est prévue.
-//scrutarijs// contient deux répertoires css/ et js/.
+L'intégration de Bootstrap3 se fait ainsi :
+<code javascript>
+<script src="scrutarijs/html/bootstrap3.js"></script>
-==== scrutarijs/css ====
-Contient la feuille de style de l'application (//scrutarijs.css//) et les images utilisées par cette feuille de style.
-//scrutarijs.css// contient des surcharges du style de Bootstrap ainsi que des indications de style pour les éléments propres à ScrutariJs. Pour distinguer les classes Bootstrap de celles propres à ScrutariJs, ces dernières commencent toujours par le préfixe //scrutari-//.
-Pour les identifiants d'éléments HTML, la convention de nommage choisie est de les nommmer comme s'il s'agissait de noms de variable classique (commençant en minuscules avec des majuscules pour marquer le type, exemple : categoryPanelBody). Lorsque l'élement est transformé est manipulé sous forme JQuery, la variable est préfixé avec //$//. cela donne ce type de formulation qui facilite la correspondance entre code HTML et Javascript :
- <code javascript>var $ficheDisplayBlock = $("#ficheDisplayBlock")</code>
-==== scrutarijs/js ====
-C'est le cœur de l'application puisque comme son nom l'indique, il contient les fichiers Javascript. //scrutarijs/js// contient à sa racine le fichier scrutarijs.js qui est la compilation de tous les fichiers Javascript du répertoire lib/ (ainsi que la structure HTML). L'ordre de compilation de ces fichiers est indiqué par le fichier lib/list.txt.
-lib/ contient deux répertoires : scrutari/ qui est centré sur l'interaction avec l'API JSON du serveur Scrutari et engine/ qui contient l'interaction avec l'interface
-La souplesse du langage Javascript conduit rapidement à un code difficilement lisible. Pour essayer d'éviter ce phénomène, les principes suivant ont été appliqués au code javascript des fichiers contenus dans le répertoire lib/ :
-  - Minimum de dépendance : seule la bibliothèque JQuery est utilisée pour les requêtes Ajax et la manipulation du DOM; aucune extension JQuery n'est utilisée et aucune extension n'est faite de JQuery (ni d'éléments natifs de Javascript)
-  - Utilisation du mécanisme Javascript classique de prototypage pour les objets (une fonction de construction plus des déclarations de prototypes)
-  - Aucune utilisation de variables globales, les éléments nécessaires à une fonction ou une méthode sont tous passés en argument (à l'exception bien sûr des propriétés de l'objet en question lorsqu'il s'agit d'une méthode)
-  - À une exception près (les fonctions de tri), les arguments sont toujours obligatoires, aucune fonction n'a donc de comportement différent suivant la présence ou non d'un argument
-  - Les objets passés en argument ne sont jamais altérés directement ; s'il subissent une modification, c'est par le biais d'une méthode spécifique à l'objet (par exemple, la méthode addBase dans Scrutari.Filter)
-  - Deux fonction //Scrutati = function ();// et //Engine = function () // servent de racine à l'ensemble : tous les objets et fonctions commencent par //Scrutari.// ou //Engine.// qui servent ainsi d'espace de noms
-  - Aucun mécanisme d'extension n'est mis en place
-  - Les variables correspondant aux objets JQuery commençent toutes par //$// (On aura par exemple var $this = $(this))
-Ces différents principes conduisent à un code volontairement verbeux en espérant qu'il soit le plus lisible possible.
-Les différents fichiers du répertoire lib/ sont les suivants :
-  * //scrutari/scrutari-core.js// : racine de la partie //scrutari//
-  * //scrutari/scrutari-loc.js// : utilitaire de gestion de la traduction de l'interface
-  * //scrutari/scrutari-config.js// : configuration de l'accès au moteur Scrutari
-  * //scrutari/scrutari-ajax.js// : fonctions d'appel Ajax
-  * //scrutari/scrutari-utils.js// : contient des fonctions utilitaires
-  * //scrutari/scrutari-meta.js// : définit l'objet //Scrutari.Meta// qui encapsule l'objet //engineInfo// renvoyé par la requête //json?type=engine//
-  * //scrutari/scrutari-result.js// : définit l'objet //Scrutari.Result// qui encapsule l'objet //ficheSearchResult// renvoyé par la requête //json?type=q-fiche//
-  * //scrutari/scrutari-filter.js// : définit l'objet //Scrutari.Filter// servant à construire le filtre appliqué à une recherche
-  * //scrutari/scrutari-html.js// : série de fonctions traduisant en HTML des objets (provenant en particulier de l'API Json), ce sont ces fonctions qui sont à remplacer en premier pour l'adaptation du code HTML généré (en particulier
-  * //engine/engine-core.js// : racine de la partie //engine//
-  * //engine/engine-init.js// : initialisation du moteur
-  * //engine/engine-query.js// : gestion de la recherche
-  * //engine/engine-ui.js// : comportement de l'interface
-  * //engine/engine-framemode.js// : méthodes spécifiques à l'interface basée sur des cadres
-scrutarijs/js contient également un répertoire //l10n// qui contient des fichiers javascript de localisation.
-===== À propos du répertoire engine/ =====
-Les fichiers de ce répetoire assurent l'affichage de l'interface du moteur de recherche. Ce répertoire contient le fichier //engine.php// qui génère le HTML final. En mode « développement », il compile également les fichiers .html contenus dans ce répertoire engine/. En  mode « production », ces fichiers .html sont inclus directement dans scrutarijs/js/scrutarijs.js (via les propriétés d'un objet Engine.html) et sont inclus au moment de l'initialisation du javascript.
-===== Invocation =====
-Comme le fichier //index.php// à la racine de l'application sert d'aiguillage, il suffit de passer des paramètres à l'adresse du répertoire dans lequel est l'application (exemple : http://scrutarijs.coredem.info/?engine=coredem). En cas d'absence du paramètre //engine//, c'est le premier moteur défini qui est pris. Les autres paramètres possibles sont :
-  * q: recherche initiale appliqué au moment du chargement
-  * page=frame: disposition à base de cadres (<frameset>), un paramètre supplémentaire //width// peut être ajouter pour la largeur consacrée à l'interface (une valeur en pixels ou les valeurs //md// (pour « medium ») ou //lg// (pour « large »)
-  * dev=1 : utilisation au cours de développement : il n'utilise pas la compilation scrutarijs/js/scrutarijs.js mais charge séparément tous les fichiers Javascript de scrutarijs/js/lib et les fichiers html de engine/ sont inclus directement dans le code HTML (et non rajouté en Javascript)
-===== Autres fichiers et répertoires =====
-  * //index.php// : fichier à la racine qui se charge de gérer les paramètres transmis et sert ainsi d'aiguillage. De fait toutes les URLs de Scrutari sont sous la forme « /?engine={nom du moteur}&{autres paramètres}
-  * //compile.php// : invoqué en ligne de commande (via //php compile.php//), il compile les différents fichiers de scrutarijs/js/lib (ainsi que les fichiers html de engine/) pour créer un fichier complet scrutarijs/js/scrutarijs.js
-  * //frame/// : répertoire qui contient les fichiers nécessaires pour afficher le moteur au sein d'un système de cadres HTML (//frameset//)
-  * //static/// : répertoire contenant des fichiers statiques, pour l'instant uniquement icon.png
-  * //l10n/// : traductions de l'interface
-  * //scrutarijs-conf_example.php// : exemple de fichier de configuration
-===== Configuration =====
-Une même instance de ScrutariJs peut appeler des moteurs différents. C'est le rôle du paramètre //engine// qui indique le nom du moteur à utiliser. Les moteurs disponibles sont indiqués dans un fichier de configuration. //index.php// considère que ce fichier de configuration s'appelle //scrutarijs-conf.php// et se situe au niveau en dessous du répertoire d'installation de ScrutariJs. Le fichier //scrutarijs-conf_example.php// compris dans le dépôt est un exemple de configuration. Un fichier de configuration doit définir un tableau associatif stocké dans $GLOBALS['scrutari']['conf']. Ce tableau associatif a les deux clés suivantes :
-  * //'origin-prefix'// : Ce préfixe est collé avant le nom du moteur pour indiquer au moteur Scrutari l'origine de l'appel (le moteur Scrutari stocke cette information dans son journal des recherches
-  * //'engines'// : tableau associatif des moteurs, chaque clé correspondant au nom d'un moteur ; la valeur associée à chaque clé est un tableau associatif dont les clés sont les suivantes :
-    * //url// : (obligatoire) url du moteur (ne pas oublier la barre oblique / finale)
-    * //corpus// : (facultatif) valeur booléenne indiquant si c'est le filtre par corpus qui doit être utilisé plutôt que le filtre par base ; le filtre par corpus est adapté au moteur centré sur un site
-    * //css-links// : (facultatif) tableau d'URL de fichiers CSS (permettant de surcharger le CSS), sa valeur par défaut est array("scrutarijs/css/scrutarijs.css")
-    * //js-links// : (facultatif) tableau d'URL de fichiers Javascript qui seront mis en lien après les autres déclarations (permettant de surcharger le Javascript, de réécrire des fonctions, etc.)
-    * //base-sort// : (facultatif) règle pour le classement des bases, les valeurs possibles sont //fiche-count// (valeur par défaut, les bases sont classées par le nombre de fiches) ou //none// (pas de classement, c'est l'ordre des bases dans le fichier de configuration sources.xml)
-    * //corpus-sort// : (facultatif) règle pour le classement des corpus, les valeurs possibles sont //fiche-count// (valeur par défaut, les corpus sont classées par le nombre de fiches) ou //none// (pas de classement, c'est l'ordre des corpus dans le fichier ScrutariData qui compte)
-Exemple :
-<code php>
-<?php
-$GLOBALS['scrutari']['conf'] = array(
-    'origin-prefix' => "coredemjs-",
-    'engines' => array(
-        "coredem" => array(
-            "url" => "http://sct1.scrutari.net/sct/coredem/",
-            "corpus" => false
-            ),
-        "irenees" => array(
-            "url" => "http://sct1.scrutari.net/sct/irenees/",
-            "corpus" => true,
-            "corpus-sort" => "none"
-            ),
-        "socioeco" => array(
-            "url" => "http://sct1.scrutari.net/sct/socioeco/",
-            "corpus" => false
-            ),
-        "premiermai" => array(
-            "url" => "http://sct1.scrutari.net/sct/premiermai/",
-            "corpus" => true,
-            "css-links" => array(
-                "scrutarijs/css/scrutarijs.css",
-                "http://static.autourdu1ermai.fr/new/css/main.css",
-                "http://static.autourdu1ermai.fr/new/css/scrutari.css"
-                ),
-            "js-links" => array("http://static.autourdu1ermai.fr/new/js/scrutari.js")
-            )
-    )
-);
 </code>
-Dans cet exemple, le moteur de la Coredem (« coredem ») propose un filtre sur les bases alors que celui d'Irénées (« irenees ») propose un filtre sur les corpus.
+Un fichier de gabarit HTML définit un objet Javascript : SCRUTARI_HTML, celui doit posséder une propriété structure qui est un objet comprenant les chaines HTML utilisées pour constituer la structure du client ainsi qu'une propriété templates qui est un objet dont les propriétés définissent des gabarits Html/
-Le moteur d'Autour du 1er mai (« premiermai ») est allé plus loin dans la personnalisation. Les feuilles de styles font que l'aspect du moteur respecte la charte graphique du site et ne jure pas avec le reste. http://www.autourdu1ermai.fr/static/new/js/scrutari.js fait deux choses : d'une part, il réécrit la fonction //Scrutari.Html.initFicheHtmlFunction// pour que l'aspect des blocs de résultat soit plus proches des autres listes (par exemple, l'année est placée juste après le titre du film) et d'autre part, il définit un mode « iframe » qui lui permet d'adopter un comportement particulier correspondant à l'insertion de la page dans une balise <iframe>.
+===== Options de Scrutari.Client.init =====
-===== ScrutariJs en pur Javascript (sans PHP) =====
+  * //locMap// : objet Javascript dont les noms de propriétés correspondent aux clés de localisation. Cette option n'a pas besoin d'être définie si un fichier de localisation a été inséré préalablement.
+  * //htmlObject// : objet Javascript indiquant les gabarits HTML à utiliser. Cette option n'a pas besoin d'être définie si un fichier de gabarit a été inséré préalablement.
-La compilation de tous les fichiers Javascript dans scrutarijs/js/scrutarijs.js permet de mettre en place l'interface du moteur de recherche sans besoin des fichiers PHP. Le code minimal pour le mettre en place est le suivant :
+  * //withCorpus// : //false// ou //true//, indique si les options de filtre proposent un filtre par corpus, défaut : //false//
+  * //baseSort// : ordre de classement des bases dans les options de filtres ; peut prendre les valeurs suivantes :
-<code html>
+    * "fiche-count" : par le nombre de fiches (défaut)
-<!DOCTYPE html>
+    * "none" : ordre « naturel » (ordre de déclaration des bases dans le serveur)
-<html lang="fr">
+  * //corpusSort// : ordre de classement des corpus (si withCorpus est égal à true) ; peut prendre les valeurs suivantes :
-<head>
+    * "fiche-count" : par le nombre de fiches (défaut)
-<title>ScrutariJs</title>
+    * "none" : ordre « naturel » (ordre de déclaration des corpus dans les fichiers ScrutariData)
-<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+  * //target// : cible des liens vers les fiches (par défaut, "_target")
-<link href="static/icon.png" type="image/png" rel="icon">
+  * //initialQuery// : séquence de recherche initiale (par défaut, ""), permet de remplir le client avec le contenu d'une nouvelle recherche
-<meta name="viewport" content="width=device-width, initial-scale=1">
+  * //initialQId// : identifiant d'un recherche existante (par défaut, ""), permet de remplir le client avec le contenu d'une recherche existante
-<script src="//code.jquery.com/jquery-1.11.0.min.js"></script>
+  * //permalinkPattern// : patron de construction de l'URL du permalien vers la recherche (défaut null), doit être une chaine contenant "$QID" (sera remplacé par l'indentifiant de la recherche) et éventuellement $LANG
-<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.2.0/js/bootstrap.min.js"></script>
+  * //paginationChangeCallback// : Fonction de rappel optionnelle appelée lorsque l'utilisateur change la pagination
-<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.2.0/css/bootstrap.min.css">
+  * //hiddenList// : liste d'élements HTML à cacher, ces éléments doivent être définis dans les gabarits HTML, cette option permet de cacher simplement des éléments (par exemple, le titre) sans avoir à modifier le gabarit HTML lui-même
-<script src="http://scrutarijs.coredem.info/scrutarijs/js/scrutarijs.js"></script>
+  * //templateFactory// : fonctions ou tableau de fonctions qui fournissent des gabarits alternatifs à ceux par défaut
-<script src="http://scrutarijs.coredem.info/scrutarijs/js/l10n/fr.js"></script>
-<script>
-    $(function () {
-        var scrutariConfig = new Scrutari.Config("coredem","http://sct1.scrutari.net/sct/coredem/", "fr", "coredemjs-coredem");
-        var engine = new Engine(scrutariConfig, Engine.l10n);
-        engine.setWithCorpus(false);
-        engine.setBaseSort("fiche-count");
-        engine.setCorpusSort("fiche-count");
-        engine.setMode("");
-        engine.setTarget("_blank");
-        engine.setInitialQuery("");
-        Engine.Init.html(engine, "#mainContainer");
-        Engine.Init.mainTitle(engine);
-        Engine.Init.custom(engine);
-        var _scrutariMetaCallback = function (scrutariMeta) {
-            Engine.Init.scrutariMeta(engine, scrutariMeta);
-        };
-        Scrutari.Meta.load(_scrutariMetaCallback, scrutariConfig);
-    });
-</script>
-<link rel="stylesheet" href="http://scrutarijs.coredem.info/scrutarijs/css/scrutarijs.css">
-</head>
-<body>
-<div class="container" id="mainContainer"></div>
-</body>
-</html>
-</code>
-La partie la plus importante est celle d'initialisation indiquée par //$(function () {//, c'est là que le moteur est configuré.