Plugins

Nota bene :
La présente documentation est rédigée pour la version 1.1.0-rc3 de MaX

Un plugin est une brique logicielle proposant une fonctionnalité supplémentaire au noyau de l’application MaX. Il est désactivé par défaut et peut être activé pour une ou plusieurs éditions numériques. Il peut être constitué de ressources RestXQ, XSL, Javascript, CSS...

MaX propose un ensemble de plugins placés dans le dossier plugins. Le script max.sh permet l’activation/désactivation de ces plugins.

Se placer dans le dossier tools de MaX puis indiquer à MaX le chemin vers BaseX :

cd le/chemin/vers/le/projet/[projet]-max/tools

export BASEX_PATH=../../[projet]-basex

lister les plugins disponibles

./max.sh --list-plugins

Le terminal affiche alors la liste des plugins disponibles, ceux inutilisés et ceux activés.

Activer un plugin

./max.sh --enable-plugin [plugin_name] [mon-edition]

Par exemple : ./max.sh --enable-plugin abreviation thecae

Désactiver un plugin

./max.sh --disable-plugin [plugin_name] [mon-edition]

Par exemple : ./max.sh --disable-plugin abreviation thecae

Une fois activé via la ligne de commande ./max.sh, le plugin est automatiquement inscrit dans le fichier de configuration de l’édition dans laquelle il a été autorisé : [projet]-max/editions/[mon-edition]/[mon-edition]_config_inc.xml. Il se retrouve au sein d’un élément <plugin name='plugin_id'/> de la section <plugins/> de ce fichier. Dans chaque élément <plugin>, d’éventuels paramètres de configuration du plugin en question pourront être spécifiés.

Fonctionnement des plugins

Lors de la consultation d’un fragment, MaX exécute l’ensemble des Xquery des plugins actifs respectant la convention de nommage : plugins/[NOM_PLUGIN]/[NOM_PLUGIN].xq.

Par exemple :

graph LR; A-->B B-->C A["plugins"] B["breadcrumb"] C("breadcrumb.xq")

Chaque XQuery reçoit en paramètres d’entrée les variables suivantes :

$dbPath : nom de la base de données XML du projet,
$project : identifiant du projet,
$doc : document consulté,
$id : id consulté.

Les résultats de ces appels sont renvoyés dans un nœud HTML <div class='plugins-wrapper'/> qui précède le contenu « textuel » XML transformé.

Pour l’édition de démonstration par exemple, on obtient :

[...]

<div class="plugins-wrapper">
  <div class="apparat-witnesses"> ...</div>
  <div id="breadcrumb">...</div>
</div>

<div id="text">
    [...]
</div>

[...]

Les XSL des plugins activés qui respectent la convention de nommage plugins/[NOM_PLUGIN]/[NOM_PLUGIN].xsl sont automatiquement appliquées.

Par exemple :

graph LR; A-->B B-->C A["plugins"] B["breadcrumb"] C("breadcrumb.xsl")

Plugins et dépendances Javascript

Certains plugins ont des dépendances vers des bibliothèques javascript (par exemple img_viewer requiert OpenSeadragon). Ces bibliothèques sont incluses dans chacun des plugins.

Abréviation

Développer ou non les abréviations (balises tei:ex & tei:am).

<plugin name="abreviation"/>

Abréviation

Exemple de texte sans l’option Abréviation :
Exemple de texte avec l’option Abréviation :

Ajout

Afficher/masquer les interventions, ajouts, suppressions (balises tei:ad & tei:del), via les options de lecture.

<plugin name="ajout"/>

Ajout

Exemple de texte sans l’option Ajout :
Exemple de texte avec l’option Ajout (ajouts en orange, suppressions barrées en noir) :

Apparat critique

Affichage des différents témoins restitués par un apparat critique :

<plugin name="apparat_critique"/>

Une fenêtre proposant l’affichage par témoin apparaît si le fichier xml contient les balises <listWit><witness @xml:id>.

Apparat critique

<!-- dans le fichier xml -->

<listWit>
    <witness n="utile" xml:id="V">
        [...]
    </witness>
     <witness n="utile" xml:id="O">
        [...]
    </witness>
</listWit>

Le contenu des différents témoins est ensuite géré à l’intérieur des balises <app>, puis <lem>et <rdg>.

<!-- dans le fichier xml -->

<app xml:id="c">
    <lem wit="V">
        La variante que l’on veut garder dans l’affichage par défaut
    </lem>
     <rdg wit="O">
        Une autre variante
    </rdg>
    <rdg wit="P">
        Une autre variante
    </rdg>
</app>

Lors du rendu final, en sélectionnant un témoin particulier, pour chaque balise app rencontrée, ne seront affichées que les balises lem ou rdg qui auront pour attribut @wit le nom du témoin.

Affichage du fil d’Ariane lors de la consultation du texte.

Un fil d’ariane (ou breadcrumb en anglais) est une aide à la navigation, pour permettre au lecteur de se situer dans le site.

Exemple d’un fil d’ariane :

EAD metadata

Ce plugin permet d’afficher les métadonnées d’une édition en EAD contenues dans les balises <eadheader> et <archdesc>.

<plugin name="ead_metadata"/>

Index

Permet de générer différents index pour les documents en EAD et en TEI : personnes, lieux, documents, etc.

<plugin name="index"/>

Index

Les index étant trop spécifiques pour permettre la mise en place d’un traitement par défaut satisfaisant, ce plugin propose donc une route* unique pour chaque index, solution pour systématiser la production des index ainsi que les routes correspondantes.

Il permet de limiter les temps de calcul en stockant les fragments html de chaque page d’index.

L’URL associée à un index est http://[serveur:port]/[mon-edition]/index/[typeindex].html

typeindex : valeur choisie par l’utilisateur (par exemple index/lieux.html ou index/personnes.html).

Par exemple : http://localhost:17002/mon-edition/index/lieux.html

Cela nécessite de créer un dossier index dans les dossiers suivants :

[projet]-max/editions/[mon-edition]/xq
[projet]-max/editions/[mon-edition]/ui/xsl
[projet]-max/editions/[mon-edition]/fragments/[langue-locale]

On place dans le dossier xq/index un fichier nommé index_[typeindex].xq qui permettra de générer l’index. Par exemple, pour un index de lieux (ici en EAD), un fichier index_lieux.xq :

declare variable $dbPath external;
declare variable $project external;

<index type="lieux">
    {for $idx in collection($dbPath)//*:geogname[@normal] | collection($dbPath)//*:corpname[@normal]
    let $cId := $idx/ancestor::*:c[@id][1]/@id
    let $baseuridb := substring-after(base-uri($idx), $dbPath)
    let $cOtherlevel := $idx/ancestor::*:c[1]/@otherlevel
    let $role := $idx/@role
    let $initiale := substring($idx/@normal,1,1) 
    let $cUnitid := $idx/ancestor::*:c[1]/descendant::*:unitid[1]/text()
    let $cParent := $idx/ancestor::*:c[@otherlevel]/descendant::*:unitid[1]/text()
    let $result := 
            <marker id="{$cId}" otherlevel="{$cOtherlevel}" role="{$role}">
            <entry>{$cUnitid}</entry>
                <manuscrit>{$cParent}</manuscrit>
                <value>{data($idx/@normal)}</value>
                <baseuri>{'/' || $project || $baseuridb}</baseuri>
                <initiale>{translate($initiale,'É[','E')}</initiale>
            </marker>
        return $result
    }
</index>

On surcharge avec une XSL dans le dossier ui/xsl/index avec un fichier index_[typeindex].xsl.

Lors du premier accès à la page [mon-edition]/index/[typeindex].html, un fichier HTML (index_[typeindex].frag.html) est généré dans le dossier fragments/[langueLocale]/index : la requête XQUERY et le traitement XSL associé sont exécutés lors de ce premier appel.

Pour générer à nouveau la page d’index, il faut supprimer le fichier index_[typeindex].frag.html souhaité, et relancer la page [mon-edition]/index/[typeindex].html.

Normalisation

Afficher/masquer la normalisation de l’éditeur (balises tei:reg & tei:orig), via les options de lecture.

<plugin name="normalisation"/>

Normalisation

Exemple de texte sans l’option Normalisation :

Exemple de texte avec l’option Normalisation :

Recherche EAD (ead_search)

Voici un exemple de configuration du plugin de recherche :

<plugin name="ead_search">
    <parameters>
        <parameter key="searchForm">
            <search>
                <tags>
                    <tag name="persname" attribute="role" value="auteur" label="Auteurs"/>
                    <tag name="title" attribute="type" value="Oeuvre" label="Titre des œuvres"/>
                    <tag name="geogname" attribute="role" value="publication" label="Lieux de publication"/>
                    <tag name="corpname" attribute="role" value="scriptorium" label="Scriptoria"/>
                </tags>
                <dates format="YYYY"/>
            </search>
        </parameter>
    </parameters>
</plugin>

tag : nom de l’élément XML dans lequel les recherches sont effectuées, avec name pour le nom de la balise, atribute pour l’attribut voulu dans la balise et value pour la valeur de l’attribut.
Les balises ead:name visées par la recherche (ici persname, title, geogname, corpname) doivent absolument posséder un attribut @normal dans le document XML pour être prises en compte par la recherche.

La recherche est accessible à cette URL : http://[host]:[port]/[edition]/rechercher.html

Recherche EAD

Side toc (EAD)

<plugin name="side_toc"/>

Ce plugin doit être déclaré pour les éditions en EAD. Il permet de générer un sommaire interactif et arborescent sur la partie gauche du site.

Side toc

Pour modifier l’affichage par défaut de la side toc, on peut surcharger son comportement en créant un fichier nommé document_toc.xq, que l’on place dans le dossier [projet]-max/editions/[mon-edition]/xq.

Sources export

Ce plugin permet de récupérer l’ensemble des fichiers XML de l’édition (ajoutés via BaseX) dans un dossier zippé.

<plugin name="sources_export"/>

Pour récupérer le dossier zippé, il faut saisir l’url suivante :
http://[host]:[port]/[edition]/[edition].zip

Par exemple :
http://localhost:17002/mon-edition/mon-edition.zip

Si un fichier XML est indenté lorsqu’il est ajouté dans BaseX, le plugin le récupérera indenté dans le fichier .zip. On peut rajouter des paramètres dans l’URL pour récupérer :

Soit l’ensemble des fichiers XML indentés :

http://[host]:[port]/[edition]/[edition].zip?indent=true

Soit l’ensemble des fichiers XML non indentés :

http://[host]:[port]/[edition]/[edition].zip?indent=no

TEI to PDF

<plugin name="tei_pdf"/>

Le fait d’activer ce plugin, déclenche l’affichage d’un bouton permettant de générer un PDF.

L’url permettant d’activer cette fonctionnalité :

http://[host]:[port]/[edition]/[document].xml/[id].pdf

Par exemple :

http://localhost:17002/mon-edition/monFichier.xml/div1.1.pdf

    Nota Bene
    La génération d’un PDF pour une édition alignée en TEI ne fonctionne pas pour l’instant.

Visionneuse d’images (img_viewer)

Permet la consultation des images au sein d’une visionneuse (Openseadragon).

Ce plugin requiert le chemin de stockage des images relatif à l’édition (imagesRepository) comme paramètre de configuration :

     <plugin name="img_viewer">
       <parameters>
         <parameter key="imagesRepository" value="ui/images/" xsl="true"/>
       </parameters>
     </plugin>

Le chemin (ici ui/images) est indiqué dans l’attribut @value de la balise <parameter>.

Pour consulter des images tuilées (dzi, iiif, etc.), il faut surcharger le template relatif à la balise tei:graphic dans le fichier text_hook.xsl (situé dans le dossier [projet]-max/editions/[mon-edition]/ui/xsl/[ead ou tei]). On remplace alors le paramètre d’appel à MAX.plugins['img_viewer'].openImageInDialog par l’URL du .dzi ou .json.

Plugins

Fonctionnement des plugins

Plugins et dépendances Javascript

Abréviation

Ajout

Apparat critique

Breadcrumb (Fil d’Ariane)

EAD metadata

Index

Normalisation

Recherche EAD (ead_search)

Side toc (EAD)

Sources export

TEI to PDF

Visionneuse d’images (img_viewer)