====== 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.
ScrutariJS peut être vu en action aux adresses suivantes (la recherche porte sur la Coredem) :
* [[http://scrutarijs.coredem.info/?engine=coredem]]
* [[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.
Pour le moment, ScrutariJs n'a pas de version empaquetée. Le code source est disponible sur le dépôt FramaGit : https://framagit.org/Scrutari/scrutarijs
ou via le dépôt Subversion :
svn co http://depot.exemole.fr/svn/web/apps/coredem.info/scrutarijs
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.
===== À propos du répertoire scrutarijs/ =====
//scrutarijs// contient deux répertoires css/ et js/.
==== 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 :
var $ficheDisplayBlock = $("#ficheDisplayBlock")
==== 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 (