Skip to content
Snippets Groups Projects
Select Git revision
  • 0f4ad86905772ba6ac03417841eecc280f93a117
  • master default protected
  • jc/side_toc_update
  • jc/locales-in-urls
  • jc/mirador-options
  • gp/langueAfficheeDansURL
  • jc/easy-start
  • em/basex104
  • gp-proposition-dossier-plugins-perso
  • gp/projectData
  • ag/paramFragIdTextHook
  • ad/update_init_script
  • dev
  • ag/apparatCritique
  • jc/fop2
  • ag/correctionTei
  • jc/install-ead-demo
  • ag/ajoutjspourEad
  • jc/nakala
  • ovp/corrCons
  • ag/affichageEad
  • v1.1.0
  • v1.1.0-rc4
  • v1.1.0-rc3
  • v1.1.0-rc2
  • v1.1.0-rc1
  • v1.0.2
  • MaX-V1.0.1
  • MaX-V1.0.0
  • MaX-V0.9.5
  • MaX-V0.9
  • MaX-V0.5
  • MaX-V0.4
  • MaX-V0.3
  • MaX-V0.2
  • MaX-V0.1
  • MaX-V0
37 results

MaX

  • Open with
  • Download source code
  • Your workspaces

      A workspace is a virtual sandbox environment for your code in GitLab.

      No agents available to create workspaces. Please consult Workspaces documentation for troubleshooting.

  • 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

    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 &amp; 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 :

    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

    UNICAEN-PDN-CERTIC

    IA Biblissima