Différences

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

Lien vers cette vue comparative

Les deux révisions précédentes Révision précédente
Prochaine révision
Révision précédente
clients:scrutarijs [2016/09/22 19:17]
vincent
clients:scrutarijs [2017/07/11 15:11] (Version actuelle)
vincent
Ligne 1: Ligne 1:
 ====== ScrutariJs ====== ====== 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 est un client de Scrutari ​écrit en JavascriptIl est déposé sur Framagit ​https://​framagit.org/​Scrutari/​scrutarijs. Le wiki du dépôt indique notamment [[https://​framagit.org/​Scrutari/​scrutarijs/​wikis/​installation|la procédure d'installation]] ​et comment [[https://​framagit.org/​Scrutari/​scrutarijs/​wikis/​adaptation|l'adapter]].
  
-ScrutariJS peut être vu en action ​aux adresses suivantes ​(la recherche ​porte sur la Coredem) :+Il est possible de le voir en action ​à l'​adresse [[http://​client.scrutari.net/​|client.scrutari.net]] ​(avec une recherche sur la Coredem). client.scrutari.net est constitué d'une série de scripts PHP qui organise l'​appel du client ScrutariJs avec notamment une variante pour grand écran qui divise la fenêtre en deux cadres : un pour la recherche proprement dite et l'​autre pour la consultation : [[http://​client.scrutari.net/?​page=frame|client.scrutari.net/?​page=frame]]. Le code de ce mini site est aussi hébergé sur Framagit : [[https://​framagit.org/​Scrutari/​scrutarijs-standalone|Scrutari/​scrutarijs-standalone]].
  
-  * [[http://​scrutarijs.coredem.info/?​engine=coredem]] +ScrutariJs est conçu pour s'intégrer dans des sites existants, comme le montre les exemples suivants ​:
-  * [[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. +  * [[http://www.films-luttes-mouvements.net/scrutarijs|Films en Luttes ​et en Mouvement]] 
- +  * [[http://www.socioeco.org/scrutarijs_fr.html|Socioeco.org]] 
-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 +  * [[http://www.autourdu1ermai.fr/​scrutarijs|Autour du 1er mai]] 
- +  * [[http://www.citego.org/scrutarijs_fr.html|Citego]]
-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 : +
- <​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. +
- +
-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 : +
- +
-<​code ​html+
-<​!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>​ +
-</​code>​ +
- +
-La partie la plus importante est celle d'​initialisation indiquée par //​$(function () {//, c'est là que le moteur est configuré.+
  
 +Une extension pour Spip est également développée pour faciliter son intégration dans un site Spip, comme le montre le [[http://​www.coredem.info/​spip.php?​page=recherche_scrutari&​moteur=coredem|site de la Coredem]]. Le code de cette extension est également déposé sur Framagit : [[https://​framagit.org/​Scrutari/​scrutari_client|Scrutari/​scrutari_client]].
clients/scrutarijs.1474564650.txt.gz · Dernière modification: 2016/09/22 19:17 par vincent
CC Attribution-Share Alike 4.0 International
Driven by DokuWiki Recent changes RSS feed Valid CSS Valid XHTML 1.0