Commit edc9b3f4 authored by Marie Bisson's avatar Marie Bisson
Browse files

Merge branch 'mb/doc' into pdn/doc 

relecture plugin et surcharge par MB
parents 5122436a 270ec4b5

documentation/docs/overriding.md

+22 −22
Original line number Diff line number Diff line
@@ -11,9 +11,9 @@ Le menu HTML est le résultat de la transformation du fichier <span class="dossi 
Une feuille de transformation placée dans <span class="dossier">[projet-]editions</span>/<span class="dossier">[edition]</span>/<span class="dossier">ui</span>/<span class="dossier">xsl</span>/<span class="fichier">menu.xsl</span> peut remplacer celle par défaut.    

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

* **$projectId** : identifiant du projet,

* **$baseURI** : baseURI du projet,

* **$selectedTarget** : entrée de menu courante (valeur d’un des attributs @target).



## Sommaires
@@ -30,9 +30,9 @@ Pour modifier la Xquery, il convient de : 
1. Créer un fichier <span class="dossier">editions</span>/<span class="dossier">[edition]</span>/<span class="dossier">xq</span>/<span class="fichier">toc.xq</span>,

2. Y rédiger une requête Xquery prenant en compte 3 paramètres :



    * $baseURI : valeur de la variable de configuration [baseURI](../config#la-variable-baseuri)

    * $dbPath  : valeur de la variable de configuration [dbPath](../config) permettant le requêtage la base de données

    * $project : identifiant de l’édition

    * **$baseURI** : valeur de la variable de configuration [baseURI](../config#la-variable-baseuri)

    * **$dbPath**  : valeur de la variable de configuration [dbPath](../config) permettant le requêtage la base de données

    * **$project** : identifiant de l’édition





Exemple de squelette d’une telle XQuery :
@@ -93,10 +93,10 @@ Tout comme le sommaire d’une édition, il est possible de : 


1. Créer un fichier <span class="dossier">[projet-]editions</span>/<span class="dossier">[edition]</span>/<span class="dossier">xq</span>/<span class="fichier">document_toc.xq</span>

2. Y rédiger une requête Xquery prenant en compte 4 paramètres :

    * $baseURI : valeur de la variable de configuration [baseURI](../config#la-variable-baseuri),

    * $dbPath  : valeur de la variable de configuration [dbPath](../config),

    * $project : identifiant de l’édition,

    * $doc     : nom du document courant pour lequel est construite la table des matières.

    * **$baseURI** : valeur de la variable de configuration [baseURI](../config#la-variable-baseuri),

    * **$dbPath**  : valeur de la variable de configuration [dbPath](../config),

    * **$project** : identifiant de l’édition,

    * **$doc**     : nom du document courant pour lequel est construite la table des matières.



Exemple de squelette d’une telle XQuery :
@@ -130,40 +130,40 @@ La XSL par défaut peut également surchargée : 
Il faut alors créer un fichier <span class="fichier">document_toc.xsl</span>.    

<span class="dossier">[projet-]editions</span>/<span class="dossier">[edition]</span>/<span class="dossier">ui</span>/<span class="dossier">xsl</span>/<span class="dossier">[tei ou ead]</span>/<span class="fichier">document_toc.xsl</span>    



Cette XSL permet de transformer le résultat de la XQuery (XQuery par défaut ou surcharge présente dans <span class="dossier">[projet-]editions/[projectId]/xq/document_toc.xq** ) en HTML.

Cette XSL permet de transformer le résultat de la XQuery (XQuery par défaut ou surcharge présente dans <span class="dossier">[projet-]editions</span>/<span class="dossier">[edition]</span>/<span class="dossier">xq</span>/<span class="fichier">document_toc.xq</span> ) en HTML.    

Cette XSL reçoit en entrée :



* le titre du document courant dans une variable **$docTitle**,

* les variables de configuration **$baseuri** et **$project"**.

* les variables de configuration **$baseuri** et **$project**.





En l'absence d'un tel fichier, MaX exécutera **MAX/ui/xsl/document_toc.xsl**.

En l’absence d'un tel fichier, MaX exécutera <span class="dossier">[projet-]MaX</span>/<span class="dossier">ui</span>/<span class="dossier">xsl</span>/<span class="dossier">[tei ou ead]</span>/<span class="fichier">document_toc.xsl</span>.



## Texte



La surcharge de transformation de la XSL de consultation du texte se fait en rédigeant une XSL placée dans `editions/[projectId]/xsl/text_hook.xsl`.

La surcharge de transformation de la XSL de consultation du texte se fait en rédigeant une XSL placée dans <span class="dossier">[projet-]editions</span>/<span class="dossier">[edition]</span>/<span class="dossier">ui</span>/<span class="dossier">xsl</span>/<span class="fichier">text_hook.xsl</span>.





## Barre de navigation



En ajoutant une feuille de transformation dans `editions/[projectId]/xsl/nav_bar.xsl`.

En ajoutant une feuille de transformation dans <span class="dossier">[projet-]editions</span>/<span class="dossier">[edition]</span>/<span class="dossier">ui</span>/<span class="dossier">xsl</span>/<span class="dossier">[tei ou ead]</span>/<span class="fichier">nav_bar.xsl</span>.



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 :

Celle-ci recevra en entrée le même arbre XML que <span class="dossier">[projet-]editions</span>/<span class="dossier">[edition]</span>/<span class="dossier">ui</span>/<span class="dossier">xsl</span>/<span class="dossier">[tei ou ead]</span>/<span class="fichier">document_toc.xsl</span> 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 suivant le fragment courant

    $prevArrow : 'true' s'il existe des fragments précédant le fragment courant

* **$selectedId** : identifiant du fragment en cours de consultation

* **$nextArrow** : 'true' s’il existe des fragments suivant le fragment courant

* **$prevArrow** : 'true' s’il existe des fragments précédant le fragment courant







## Mise en page



Le template de mise en page par défaut se trouve dans **ui/templates/[tei ou ead].html**.

Il est possible de remplacer cette mise en page en créant son propre template dans `editions/[projectId]/ui/templates/template.html`.

Le template de mise en page par défaut se trouve dans <span class="dossier">[projet-]MaX</span>/<span class="dossier">ui</span>/<span class="dossier">templates</span>/<span class="fichier">[tei ou ead].html</span>.    

Il est possible de remplacer cette mise en page en créant son propre template dans <span class="dossier">[projet-]editions</span>/<span class="dossier">[edition]</span>/<span class="dossier">ui</span>/<span class="dossier">templates</span>/<span class="fichier">template.html</span>.



## Métadonnées HTML



Le contenu des métadonnées d'une édition est modifiable en créant un fichier **editions/[projectId]/xq/metadata.xq**.

Le contenu des métadonnées d’une édition est modifiable en créant un fichier <span class="dossier">[projet-]editions</span>/<span class="dossier">[edition]</span>/<span class="dossier">xq</span>/<span class="fichier">metadata.xq</span>.



Cette XQuery recevra 3 paramètres :

documentation/docs/plugins.md

+54 −52
Original line number Diff line number Diff line 
# Plugins



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

Un plugin est une brique logicielle proposant une fonctionnalité supplémentaire au noyau de l’application MaX. Il est activé (désactivé par défaut) 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 répertoire *plugins*. Le script *tool/max.sh* permet l'activation/désactivation de ces plugins.

MaX propose un ensemble de plugins placés dans le dossier <span class="dossier">plugins</span>. Le script *max.sh* permet l’activation/désactivation de ces plugins.



````

# lister les plugins disponibles

$ ./tools/max.sh --list-plugins

* Se placer dans le dossier **tools** : 



# Activer un plugin

./tools/max.sh --enable-plugin <plugin_name> <mon-edition>

``cd le/chemin/vers/le/projet/[projet-]MaX/tools``



# Désactiver un plugin

./tools/max.sh --disable-plugin <plugin_name> <mon-edition>

* lister les plugins disponibles



````

``./tools/max.sh --list-plugins``



* Activer un plugin



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



* Désactiver un plugin



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





Une fois activé, la configuration du plugin se fait dans les fichiers de configuration des différentes éditions (mon-edition\_config\_inc.xml) dans lequel d'éventuels paramètres de configuration du plugin en question sont spécifiés. 



Cette configuration se fait au sein d'un élément `<plugin name='plugin_id'/>` de la section `<plugins/>` du fichier de configuration d'une édition.



Une fois activé, la configuration du plugin se fait dans les fichiers de configuration des différentes éditions (<span class="fichier">mon-edition\_config\_inc.xml</span>) dans lequel d’éventuels paramètres de configuration du plugin en question sont spécifiés. 



Cette configuration se fait au sein d'un élément `<plugin name='plugin_id'/>` de la section `<plugins/>` du fichier de configuration d’une édition.



````xml

<plugins>

<-- exemple de l'activation du plugin breadcrumb -->

<!-- exemple de l’activation du plugin breadcrumb -->

   <plugin name="breadcrumb">

		<parameters>

			<parameter key="topLabel" value="Sanctoral – Beata Maria"/>
@@ -35,8 +40,8 @@ Cette configuration se fait au sein d'un élément `<plugin name='plugin_id'/>` 


## Fonctionnement



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

Lors de la consultation d’un fragment, MaX exécute l’ensemble des Xquery des plugins actifs respectant la convention de nommage :

<span class="dossier">plugins</span>/<span class="dossier">[NOM_PLUGIN]</span>/<span class="fichier">[NOM_PLUGIN].xq</span>.



Par exemple :
@@ -49,17 +54,17 @@ graph LR; 
    C("breadcrumb.xq")

</div>



Chaque XQuery reçoit en paramètres d'entrée :

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



* **baseURI** : valeur de la variable baseURI,

* **dbPath** : nom de la base de données XML du projet,

* **project** : identifiant du projet,

* **doc** : document consulté,

* **id** : id consulté.

* **$baseURI** : valeur de la variable baseURI,

* **$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é.

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 :

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



````

[...]
@@ -76,7 +81,7 @@ Pour l'édition de démonstration par exemple, on obtient : 
[...]

````



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

Les XSL des [plugins](../plugins) activés qui respectent la convention de nommage <span class="dossier">plugins</span>/<span class="dossier">[NOM_PLUGIN]</span>/<span class="fichier">[NOM_PLUGIN].xsl</span>. sont automatiquement appliquées.



Par exemple :
@@ -91,15 +96,14 @@ graph LR; 


### 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'activation du plugin à la lecture

Certains plugins ont des dépendances vers des bibliothèques javascript (ex : *img_viewer* requiert *OpenSeadragon*).

Ces bibliothèques sont automatiquement copiées à l’activation du plugin à 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*).

Ex : l’édition de démonstration TEI (**max_tei_demo**) fonctionnant avec les plugins *img_viewer* et *equations*, les bibliothèques *Mathjax* et *Openseadragon* sont

automatiquement copiées lors de l’installation de l’édition (lecture de *equations/dependencies.json* et *img_viewer/resources.json*).



Note : ces dépendances ne sont pas supprimées lors de la désactivation d'un plugin (à venir ?) afin d'éviter la suppression d'une lib

utilisée par un autre plugin.

Note : ces dépendances ne sont pas supprimées lors de la désactivation d’un plugin (à venir ?) afin d’éviter la suppression d’une bibliothèque utilisée par un autre plugin.





## Les plugins disponibles
@@ -122,13 +126,13 @@ Afficher/masquer les interventions (balises `tei:ad` & `tei:del`). 


### Apparat critique



Affichage de l'apparat critique :

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



```xml

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

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



![Apparat critique](images/apparat.png)
@@ -136,10 +140,10 @@ Une fenêtre proposant l'affichage par témoin apparaît si le fichier xml conti 
<!-- dans le fichier xml -->



<listWit>

    <witness n='utile" xml:id="V">

    <witness n="utile" xml:id="V">

        [...]

    </witness>

     <witness n='utile" xml:id="O">

     <witness n="utile" xml:id="O">

        [...]

    </witness>

</listWit>
@@ -149,12 +153,12 @@ Une fenêtre proposant l'affichage par témoin apparaît si le fichier xml conti 


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.

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





![Fil d'ariane](images/breadcrumb.png)

![Fil d’ariane](images/breadcrumb.png)



Le paramètre `topLabel` permet de configurer le label de la racine du fil d’Ariane.

Le paramètre `$topLabel` permet de configurer le label de la racine du fil d’Ariane.





```xml
@@ -167,7 +171,7 @@ Le paramètre `topLabel` permet de configurer le label de la racine du fil d’A 


### Correction



Afficher/masquer les erreurs et leurs corrections (balises `tei:sic` & `tei:corr`).

Afficher/masquer les erreurs et leurs corrections (balises `tei:sic` et `tei:corr`).



```xml

<plugin name="correction"/>
@@ -175,7 +179,7 @@ Afficher/masquer les erreurs et leurs corrections (balises `tei:sic` & `tei:corr 


### Diplomatique



Plugin rassemblant les plugins correction (balises `tei:sic` & `tei:corr`), abréviation (balises `tei:ex` & `tei:am`) et normalisation (balises `tei:reg` & `tei:orig`).

Plugin rassemblant les plugins correction (balises `tei:sic` et `tei:corr`), abréviation (balises `tei:ex` et `tei:am`) et normalisation (balises `tei:reg` et `tei:orig`).



```xml

<plugin name="diplomatique"/>
@@ -183,12 +187,12 @@ Plugin rassemblant les plugins correction (balises `tei:sic` & `tei:corr`), abr 


### EAD basket



CSS et JS importés de base dans une édition EAD (depuis le template HTML). Ne doit donc pas être ajouté à la liste des

plugins déclarés dans la configuration de l’édition.

CSS et JS importés de base dans une édition EAD (depuis le template HTML). Ne doit donc pas être ajouté à la liste des plugins déclarés dans la configuration de l’édition.



|Nota Bene JR|

|---------|

| Je ne comprends pas de quoi il est question ici|

|pourtant moi (MB) je le déclare… sinon ça marche pô|
@@ -198,9 +202,9 @@ plugins déclarés dans la configuration de l’édition. 
<plugin name="ead_pdf"/>

```



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

Le fait d’activer ce plugin, déclenche l’affichage d'un bouton permettant de générer un pdf dans une édition en EAD.



L'url permettant d'activer cette fonctionnalité :

L’url permettant d’activer cette fonctionnalité :



``http://[host]:[port]/[edition]/[document].xml/ead/[id].pdf``
@@ -232,8 +236,8 @@ Ce plugin requiert le chemin (relatif à l’édition) de stockage des images (` 
```





Pour consulter des images tuilées (dzi, iiif, etc.), il faut surcharger le template `tei:graphic` (dans la `text_hook` de l'édition)

afin de remplacer le paramètre d'appel à `MAX.plugins['img_viewer'].openImageInDialog` par l'URL du `.dzi` ou `.json`.

Pour consulter des images tuilées (dzi, iiif, etc.), il faut surcharger le template `tei:graphic` (dans le fichier <span class="fichier">text_hook.xsl</span> de l’édition)

afin de remplacer le paramètre d'appel à `MAX.plugins['img_viewer'].openImageInDialog` par l’URL du `.dzi` ou `.json`.





### Index
@@ -287,10 +291,8 @@ Voici un exemple de configuration du plugin de recherche : 


### Side toc



Doit être déclaré dans une édition EAD.

|Nota Bene JR|

|---------|

| À compléter. À quoi ça sert ?|

Ce plugin est déclaré par défait pour les éditions en EAD.

Il permet de générer un sommaire interactif et arborescent sur la partie gauche du site.



### Sources export

Permet de récupérer un dossier zippé contenant tous les fichiers XML.
@@ -299,7 +301,7 @@ Permet de récupérer un dossier zippé contenant tous les fichiers XML. 
<plugin name="sources_export"/>

```



L'url permettant d'activer cette fonctionnalité :

L’url permettant d'activer cette fonctionnalité :



``http://[host]:[port]/[edition]/[edition].zip``
@@ -314,9 +316,9 @@ Par exemple : 
<plugin name="tei_pdf"/>

```



Le fait d'activer ce plugin, déclenche l'affichage d'un bouton permettant de générer un 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é :

L’url permettant d'activer cette fonctionnalité :



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