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 JQuery (requêtes Ajax et manipulation du DOM) et 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 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 (<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 :

<?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")
            )
    )
);

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.

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>.

ScrutariJs en pur Javascript (sans PHP)

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 :

<!DOCTYPE html>
<html lang="fr">
<head>
<title>ScrutariJs</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link href="static/icon.png" type="image/png" rel="icon">
<meta name="viewport" content="width=device-width, initial-scale=1">
<script src="//code.jquery.com/jquery-1.11.0.min.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.2.0/js/bootstrap.min.js"></script>
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.2.0/css/bootstrap.min.css">
<script src="http://scrutarijs.coredem.info/scrutarijs/js/scrutarijs.js"></script>
<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>

La partie la plus importante est celle d'initialisation indiquée par $(function () {, c'est là que le moteur est configuré.