Différences

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

--- clients:scrutarijs [2014/10/20 13:56]
vincent [Configuration]
+++ 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 lib/ qui contient le cœur de l'interaction avec l'API Json et le répertoire engigine/ qui contient les fichiers construisant l'interface finale.
+<code javascript>
+<script src="scrutarijs/l10n/fr.js"></script>
+</code>
+===== Les fichiers de gabarit HTML =====
-===== À propos du répertoire lib/ =====
+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.
-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/ :
+L'intégration de Bootstrap3 se fait ainsi :
+<code javascript>
+<script src="scrutarijs/html/bootstrap3.js"></script>
+</code>
-  - 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)
+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/
-  - 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)
-  - Une fonction //Scrutati = fonction ();// sert de racine à l'ensemble : tous les objets et fonctions commencent par //Scrutari.// qui sert ainsi d'espace de noms à l'ensemble
-  - 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 :
+===== Options de Scrutari.Client.init =====
-  * //scrutari-core.js// : contient les appels Ajax et la définition de classes de paramétrage (Scrutari.Loc pour la langue et Scrutari.Engine pour le moteur)
-  * //scrutari-utils.js// : contient des fonctions utilitaires
-  * //scrutari-meta.js// : définit l'objet //Scrutari.Meta// qui encapsule l'objet //engineInfo// renvoyé par la requête //json?type=engine//
-  * //scrutari-result.js// : définit l'objet //Scrutari.Result// qui encapsule l'objet //ficheSearchResult// renvoyé par la requête //json?type=q-fiche//
-  * //scrutari-filter.js// : définit l'objet //Scrutari.Filter// servant à construire le filtre appliqué à une recherche
-  * //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
-===== À propos du répertoire engine/ =====
-Les fichiers de ce répetoire assurent l'affichage final et l'interaction entre les éléments de l'interface. //html.php// contient la structure HTML qui suit le modèle Bootstrap (notamment pour la disposition en colonnes). //script.php// contient du code Javascript inclus générés dynamiquement et inclus directement dans le fichier PHP, il contient également l'initialisation des différents éléments HTML ainsi que les fonctions principales, ce sont ces fonctions qui sont les plus à même d'évoluer (le fichier //static/engine.js// contient les fonctions utilisées par l'interface « stabilisées ».
-Pour distinguer les classes Bootstrap de celles propres à l'application, 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>
-//script.php// est le fichier à lire pour voir les possibilités offertes par les fichiers Javascript de lib/
-===== 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 »)
-===== 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}
-  * //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, notamment //engine.css// et //engine.js// qui jouent un rôle important dans la construction de l'interface finale, //engine.css// sert principalement à surcharger les classes par défaut de Bootstrap
-  * //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("static/engine.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(
-                "static/engine.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.
+  * //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.
+  * //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 :
+    * "fiche-count" : par le nombre de fiches (défaut)
+    * "none" : ordre « naturel » (ordre de déclaration des bases dans le serveur)
+  * //corpusSort// : ordre de classement des corpus (si withCorpus est égal à true) ; peut prendre les valeurs suivantes :
+    * "fiche-count" : par le nombre de fiches (défaut)
+    * "none" : ordre « naturel » (ordre de déclaration des corpus dans les fichiers ScrutariData)
+  * //target// : cible des liens vers les fiches (par défaut, "_target")
+  * //initialQuery// : séquence de recherche initiale (par défaut, ""), permet de remplir le client avec le contenu d'une nouvelle recherche
+  * //initialQId// : identifiant d'un recherche existante (par défaut, ""), permet de remplir le client avec le contenu d'une recherche existante
+  * //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
+  * //paginationChangeCallback// : Fonction de rappel optionnelle appelée lorsque l'utilisateur change la pagination
+  * //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
+  * //templateFactory// : fonctions ou tableau de fonctions qui fournissent des gabarits alternatifs à ceux par défaut
-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://static.autourdu1ermai.fr/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>.