MaX
Le Moteur d'Affichage XML est une interface de lecture de sources XML développé par l'Université de Caen Normandie (Pôle Document Numérique / CERTIC) notamment dans le cadre de l'Equipex Biblissima
Licence
voir legal.txt
Participer au développement
Demander à rejoindre MaX-Community.
Contacts
Vous pouvez nous contacter via contact.certic@unicaen.fr
Prérequis
-
Java 8+
-
NodeJS (et npm) 10+
-
xmllint
-
BaseX 9.2+
Installation
$ cd tools && ./max.sh -i
# change dir to your basex app folder
$ cd </path/to/basex>/webapp
# create a symlink on your MaX instance
$ sudo ln -s /path/to/max .
# run basex http
$ cd </path/to/basex>/bin
$ ./basexhttp
# then check your install at: http://localhost:8984/max: 'MaX' should be displayed.
Il est fortement recommandé d'utiliser saxon9 comme moteur de transformation XSLT. Il faut alors l'ajouter aux librairies chargées par BaseX :
$ cp </path/to/saxon/>saxon9.jar </path/to/basex>/lib
Édition de démonstration
$ cd tools
# set the env var $BASEX_PATH only if the basexclient command is not in your PATH. Useless
# if basex was install with your system package manager
# The basex dir must contains the bin subfolder
$ export BASEX_PATH=/path/to/basex
Modifier si nécessaire le numéro de port (1984 par défaut) de votre serveur BaseX dans le script max.sh puis éxécuter la commande :
$ ./max.sh --install-demo
L'édition de démonstration est consultable à http://localhost:8984/demo_lorem
Paramétrages
Ajouter une édition
todo: explication script max.sh --new-edition
Fichiers de configuration
Configuration globale
Le fichier configuration/configuration.xml se contente d'inclure les fichiers de configuration des différentes éditions hébergées par l'instance de MaX.
Chaque édition myedition existe de par la présence d'un dossier editions/myedition.
Exemple d'inclusion de configuration de l'édition demo dans configuration/configuration.xml :
<!--inclusion de la configuration de l'édition demo au sein de la configuration de MaX-->
<xi:include href="../editions/demo/demo_config_inc.xml"/>
Ces opérations de création et d'inclusion de fichier sont effectuées automatiquement par le script d'ajout d'édition max.sh --new-edition.
Page d'accueil
- URL : http://[host]:[port]/[project]/accueil
- Fonctionnalité : Affiche le fragment HTML stocké dans editions/[project]/fragments/accueil.frag.html
Menu
Le menu d'une édition myedition se configure dans un fichier editions/myedition/menu.xml décrivant au maximum deux niveaux de menu . Pour une entrée de menu (), il est nécessaire de renseigner son identifiant() ainsi que sa cible (). Dans l'exemple ci-contre, le menu généré contiendra deux entrées principales (attribut type='main'): home et parcours.
L'entrée home pointera vers l'URL http://{...}/myedition/accueil et contiendra deux sous-entrées presentation et contacts pointants respectivement vers http://{...}/myedition/presentation et http://{...}/myedition/contact.
<menu>
<entry type="main" default="true">
<id>home</id>
<target>accueil</target>
<!--home sub entries-->
<entry>
<id>presentation</id>
<target>presentation</target>
</entry>
<entry>
<id>contacts</id>
<target>contacts</target>
</entry>
</entry>
<entry type="main">
<id>sommaire</id>
<target>sommaire</target>
</entry>
</menu>
Modification de la mise en forme du menu
Le menu HTML est le résultat de la transformation du fichiers myedition/menu.xml par la feuille XSL par défaut placée dans MAX/ui/xsl/menu.xsl.
Une feuille de transformation placée dans myedition/ui/xsl/menu.xsl remplacera celle par défaut. 3 paramètres sont disponibles dans cette XSL :
- projectId : identifiant du projet
- baseURI : baseURI du projet
- selectedTarget: entrée de menu courante (valeur d'un des attributs @target)
Table des matières d'une édition
La table des matières d'une édition est disponible à l'URL http://[host]:[port]/[project]/sommaire
Fonctionnement par défaut
Par défaut, la page de sommaire liste les documents présents dans la collection:
- Pour la TEI, les élements TEI/tei:teiHeader/tei:fileDesc//tei:title//text()
- Pour l'EAD, les éléments ead/ead:archdesc/ead:did/ead:unittitle//text()
Surchage du comportement
La modification du comportement par défaut se fait par l'ajout d'un fichier XQUERY toc.xq, dans le répertoire editions/[projectId]/xq/. Ce fichier doit à minima déclarer les variables qui lui sont automatiquement passées en paramètres par MAX :
declare variable $baseURI external;
declare variable $dbPath external;
declare variable $project external;
declare variable $doc external;
<div>
[ ... ]
</div>
Pour être compatible avec la XSL par défaut, cette XQUERY devra générer une balise ul composée de li et ul. Les items de lien devront renseigner ces liens dans l'attribut data-href.
Exemple de listing (comportement par défaut):
<ul>
<li data-depth="0" data-href="/demo_lorem/sommaire/demo_lorem.xml">
<title xmlns="http://www.tei-c.org/ns/1.0">Lorem Ipsum <lb></lb>In <hi rend="small-caps">MaX</hi> - Corrections, notes & sauts de page</title>
</li>
<li data-depth="0" data-href="/demo_lorem/sommaire/demo_align_lat.xml">
<title xmlns="http://www.tei-c.org/ns/1.0">Lipsum - Version Latine.</title>
</li>
<li data-depth="0" data-href="/demo_lorem/sommaire/demo_lorem_3.xml">
<title xmlns="http://www.tei-c.org/ns/1.0">Lorem Ipsum in MaX - Tome 3. Images et Équations</title>
</li>
<li data-depth="0" data-href="/demo_lorem/sommaire/demo_lorem_2.xml">
<title xmlns="http://www.tei-c.org/ns/1.0">Lorem Ipsum In MaX - Tome 2. Apparat critique</title>
</li>
<li data-depth="0" data-href="/demo_lorem/sommaire/demo_align_fr.xml">
<title xmlns="http://www.tei-c.org/ns/1.0">Lipsum aligné - Version française / traduction latine.</title>
</li>
</ul>
Il est aussi possible d'intervenir sur le HTML généré par l'ajout d'une XSL toc.xsl, dans le répertoire editions/[projectId]/xsl/. Cette feuille de transformation reçoit en entrée :
- le listing des documents XML stockés dans la collection propre à l'édition (comportement par défaut) ou le XML généré par la surcharge XQUERY editions/[projectId]/xq/toc.xq.
- les paramètres $baseuri et $project contenant respectivement la variable base_uri et l'identifiant de l'édition
La feuille de transformation par défaut se trouve dans max/ui/xsl/toc.xsl
Sommaire d'un document
Le sommaire d'un document est accessible à l'URL http://[host]:[port]/[project]/sommaire/[document_path].xml
Fonctionnement par défaut
Actuellement, seule la TEI est dotée d'un comportement par défaut : le sommaire d'un document liste les balises head des div identifiée (avec un attribut @xml:id) contenant un attribut @type.
Surcharge
La modification peut se faire par l'ajout d'un fichier document_toc.xq dans editions/[projectId]/xq/.
Le fichier doit à minima déclarer les variables qui lui sont automatiquement passées en paramètres par MAX :
declare default element namespace "http://www.tei-c.org/ns/1.0";
declare variable $baseURI external;
declare variable $dbPath external; (:path du document dans la db:)
declare variable $project external; (: id du projet :)
declare variable $doc external; (: nom du document :)
(: xquery listant les items du sommaire du document $doc:)
<ul>
<li id="..." data-href="..."><head>...</head></li>
[ ... ]
</ul>
Afin d'être compatible avec la feuille de transformation XSL appliquée par défaut au résultat de cette XQUERY, celle-ci doit :
- retourner le sommaire dans un élement tei ul
- construire des sous-éléments li pour chaque entrée en spécifiant l'url des liens dans un attribut data-href
- construire un sous-élement head pour chaque li, contenant le libellé de l'entrée.
Tout comme pour la table des matières d'une édition, cette XSL peut être remplacée par une XSL editions/[projectId]/xsl/document-toc.xsl. Cette feuille de transformation recevra en entrée :
- le XML de la table des matières du document généré automatiquement par MAX ou le XML généré par la surcharge XQUERY editions/[projectId]/xq/document-toc.xq.
- les paramètres baseuri**, **project et $docTitle contenant respectivement la variable base_uri, l'identifiant de l'édition et le titre document courant.
Affichage des titres
todo: document_title.xsl
Textes
La consultation des textes se fait aux URLs suivantes :
- http://[host]:[port]/[project]/[chemin_fichier.xml]/[id] : consultation d'un fragment identifié
- http://[host]:[port]/[project]/doc/[chemin_fichier.xml] : consultation d'un document XML complet
- http://[host]:[port]/[project]/fragment_html/[id] : consultation "isolée" (sans css, jc, menu, barre de navigation, etc.). L'ajout du query parameter ?wrap=true offre une consultation dans une page HTML complète (css + js).
La feuille de transformation appliquée par défaut se trouve dans ui/xsl/[environnement]/[environnement].xsl (environnement = tei ou ead). La surcharge de cette transformation se fait en ajoutant un fichier xsl text_hook.xsl dans ** editions/[projectId]/xsl/text_hook.xsl.
Aussi, les XSL des plugins activés respectant la convention de nommage plugins/NOM_PLUGIN/NOM_PLUGIN.xsl sont automatiquement appliquées.
Options de lecture
Barre de navigation
Lors de l'affichage du texte d'un fragment, la barre de navigation (liste déroulante) permet de naviguer de fragment en fragment. Les entrées de cette liste déroulante sont par défaut identiques aux entrées de la table des matières du document en cours de consultation.
Il est possible de modifier l'affichage des ces entrées en ajoutant une feuille de transformation dans editions/[projectId]/xsl/nav_bar.xsl. Celle-ci recevra en entrée le même arbre XML que editions/[projectId]/xsl/document-toc.xsl ainsi que les paramètres baseuri, project accompagnés de :
- selectedId : identifiant du fragment en cours de consultation
- nextArrow : 'true' s'il existe des fragments suivants le fragment courant
- prevArrow : 'true' s'il existe des fragments précédents le fragment courant
Alignement
Page statique
Mise en page
Le template de mise en page par défaut se trouve dans ui/templates/[env].html. Il est possible de remplacer cette mise en page en créant son propre template et en le convoquant dans la configuration de l'édition concernée. Voici un exemple, pour une mise en page avec un menu vertical à gauche sur l'édition de démonstration :
<layout template="editions/demo_lorem/ui/layout/template.html"/>
Il est nécessaire d'activer la surcharge de transformation du menu en renommant le fichier editions/demo_lorem/ui/xsl/menu_left.xsl en editions/demo_lorem/ui/xsl/menu.xsl.
Plugins
Abréviation
Ajout
Apparat critique
Fil d'ariane (Breadcrumb)
Correction
Équations
Images (img_viewer)
Index
Notes
Pagination (Pager)
Recherche (search)
Son activation se fait par l'ajout d'une section plugin sous la section plugins du fichier de configuration d'une édition.
Voici un exemple de configuration du plugin de recherche :
<plugin name="search">
<parameters>
<!--Les recherches sont effectuées dans toutes les balises p (et leurs descendants)-->
<parameter key="tag" value="p"/>
<!--Pour chacun des résultats, le lien de retour au texte pointe
vers la div ancêtre identifiée ayant un @ type-->
<parameter key="backToTextID" value="(./ancestor::*:div[@*:type])[1]/@xml:id"/>
</parameters>
</plugin>
- tag: nom du tag xml dans lesquels les recherches sont effectuées
- backToTextId: xpath à suivre pour les liens de retour au texte sur les éléments de résultat
Plugins et dépendances Javascript
Certains plugins ont des dépendances vers des librairies js (ex : img_viewer requiert OpenSeadragon). Ces librairies sont automatiquement copiées à l'installation du plugin pour une édition à la lecture du fichier plugins/<plugin_name>/resources.json. Ex : l'édition de démo fonctionnant avec les plugins img_viewer et equations, les librairies Mathjax et Openseadragon sont automatiquement copiées lors de l'installation de l'édition (lecture de equations/dependencies.json et img_viewer/resources.json).
Métadonnées
Les métadonnées générées par défaut dans l'en-tête des documents HTML sont modifiables par l'ajout d'un fichier metadata.xq dans editions/[projectId]/xq/ :
declare variable $project external; (: id du projet :)
declare variable $requestPath external; (: path courant de l'url :)
declare variable $content external; (:contenu de la page = xml transformé = body:)
[...]
Exécution d'une édition dans un container Docker
-
L'image ne peut être créée que si une édition existe (la création d'une image à partir d'un MaX vide est impossible, et inutile !).
-
Création de l'image de l'édition (exemple avec l'édition de démonstration) puis lancement du container accessible sur le port 9999 (base XML du projet stockée dans /opt/basex/data/max_demo_lorem :
Création de l'édition de démonstration
$ ./tools/max.sh --init && ./tools/max.sh --install-demo
Ajout des droits sur les données de la base pour le container :
$ sudo chown -R 1984 /opt/basex/data/max_demo_lorem
Création de l'image de l'édition puis lancement du container :
$ sudo docker build -t unicaen/max_demo_lorem .
$ sudo docker run -d -p 9999:8984 --volume /opt/basex/data/max_demo_lorem:/srv/basex/data/max_demo_lorem unicaen/max_demo_lorem