Le Moteur d'Affichage XML est une interface de lecture de sources XML développé par l'[Université de Caen Normandie](http://www.unicaen.fr)([Pôle Document Numérique](http://www.unicaen.fr/recherche/mrsh/document_numerique) / [CERTIC](https://www.certic.unicaen.fr)) notamment dans le cadre de l'Equipex [Biblissima](http://www.biblissima-condorcet.fr/)
Le Moteur d’Affichage XML est une interface de lecture de sources XML développé par l’[Université de Caen Normandie](http://www.unicaen.fr)([Pôle Document Numérique](http://www.unicaen.fr/recherche/mrsh/document_numerique) / [CERTIC](https://www.certic.unicaen.fr)) notamment dans le cadre de l’Equipex [Biblissima](http://www.biblissima-condorcet.fr/)
## Licence
...
...
@@ -25,34 +25,111 @@ Vous pouvez nous contacter via [contact.certic@unicaen.fr](mailto:contact.certic
- xmllint
- BaseX 9.2+
### Installation BaseX (et éventuels changements de ports)
## Installation
- vous pouvez télécharger BaseX (.zip) à cette adresse : [http://www.basex.org/download/](http://www.basex.org/download/).
- vous pouvez le renommer (ex. : maxTest) et l’installer où vous le souhaitez
ex. Documents/PDN/Standalone/maxTest
#### Modifications des ports
- Lancer une instance du serveur Jetty avec la commande basexhttp (afin de générer le fichier .basex) :
- dans le terminal se placer dans le dossier bin du BaseX (maxLight)
```bash
$ cd tools && ./max.sh --init
# 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.
```
$ cd PATH/Documents/PDN/Standalone/maxTest/bin
$ ./basexhttp &
```
Il est fortement recommandé d'utiliser saxon9 comme moteur de transformation XSLT. Il faut alors l'ajouter aux librairies chargées par BaseX :
- Arrêter l’application BaseX avec le terminal (toujours dans le dossier bin) pour changer les ports
```
$ ./basexhttpstop
```
- Changer les ports (par défaut 1984 / 8984) dans les fichiers :
- .basex (fichier caché à la racine du dossier) :
- PORT (l. 13) port du server (ex. : 14070) ;
- SERVERPORT (l.14) port du server (ex. : 14070) ;
- STOPPORT (l. 34) port d’arrêt (ex. : 14071)
- jetty.xml (fichier dans webapp > WEB-INF ) :
- Set @name="port" (l. 11) port du server d’application (ex : 14072).
> NOTA BENE : c’est le port configuré dans ce fichier jetty.xml qui va servir pour l’URL
- Relancer une instance du jetty (`./basexhttp &`) et vérifier que tout se passe bien dans le navigateur à l’adresse : http://localhost:14072 (la page "BaseX HTTP Services" doit s’afficher)
Il est fortement recommandé d’utiliser saxon9 comme moteur de transformation XSLT. Il faut alors l’ajouter aux librairies chargées par BaseX dans le dossier `lib` de l’instance baseX.
Récupérer MaX sur le git d’unicaen (git.unicaen.fr/pdn-certic) et l’installer dans le dossier webapp du baseX
- soit en le téléchargeant ;
- soit en ligne de commande (pour pouvoir faire les mises à jour)
```
$ cd Document/PDN/Standalone/maxTest/webapp/
$ git clone git@git.unicaen.fr:pdn-certic/MaX.git
```
Il existe plusieurs branches de max que vous pouvez rapatrier
```
$ cd MaX
$ git fetch
$ git checkout dev
```
### Récupérer toutes les fonctionnalités de MaX
Il faut se placer dans le dossier tools et lancer une première fois le script `max.sh`
> N. B. : Si vous avez changé les ports de BaseX, il faut modifier le script max.sh en modifiant la ligne 4 du script `PORT=1984` en `PORT=`*`port_du_serveur`*
```bash
# lancer le script
$ cd </path/to/basex>/webapp/MaX/tools
$ ./max.sh --init
# démarrer basex http si ce n’est pas fait
$ cd </path/to/basex>/bin
$ ./basexhttp
```
Vous pouvez vérifier si Max est bien installé sur votre navigateur à l’adresse : http://localhost:8984/max. MaX doit s’afficher dans votre navigateur.
> N. B. : Si vous avez changé les ports de BaseX, il faut chager 8984 par le port défini dans le fichiers `jetty.xml`.
### Édition de démonstration
Pour installer la version démo, il faut à nouveau utiliser le script max.sh
```bash
$ 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
...
...
@@ -65,50 +142,133 @@ Modifier si nécessaire le numéro de port (*1984* par défaut) de votre serveur
$ ./max.sh --install-demo
```
L'édition de démonstration est consultable à **http://localhost:8984/demo_lorem**
Le terminal demande les identifiants et mots de passe (par défaut admin / admin).
L’édition de démonstration est consultable à **http://localhost:8984/demo_lorem**
> N. B. : Si vous avez changé les ports de BaseX, il faut chager 8984 par le port défini dans le fichiers `jetty.xml`. Ex. ci-dessus http://localhost:14072/demo_lorem
## Paramétrages - todo
### Ajouter une édition
Pour ajouter une édition on peut utiliser à nouveau le script max.sh
```
#Se positionner en ligne de commande dans le dossier tools
$ cd path
#executer le script
$ ./max.sh --new-edition
```
Plusieurs questions vont être posées :
1. Identifiant du projet ?
Il faut écrire le nom de site, sans espace ni caractères spéciaux. Exemple : pouille
2. Chemin de la collection XML?
**Il s’agit du nom de la base de données XML**. Nous donnons souvent le même nom de base que le nom du projet ou le nom du maxiprojet suivi du nom du projet. Exemple : norecrit/pouille
3. Vocabulaire XML du projet (tei, ead, ...)?
tei
4. Dossier des sources XML à charger ?
Il s’agit de renseigner le chemin complet vers le dossier où se trouvent les fichiers XML. Exemple : /Users/marie/Documents/fichiersBaseX/pouille
5. Please type your BaseX login/password :
Par défaut admin / admin
- Username: admin
- Password: admin
Vous pouvez enfin vous connecter en local à l’adresse :
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.
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*.
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 :*
*Exemple d’inclusion de configuration de l’édition demo dans configuration/configuration.xml :*
```xquery
<!--inclusion de la configuration de l'édition demo au sein de la configuration de MaX-->
<!--inclusion de la configuration de l’édition demo au sein de la configuration de MaX-->
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*.
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
### Page d’accueil
Affiche le fragment HTML stocké dans **editions/[project]/fragments/accueil.frag.html** à l'url
Affiche le fragment HTML stocké dans **editions/[project]/fragments/accueil.frag.html** à l’url
**http://[host]:[port]/[project]/accueil**
### Table des matières d'une édition
### 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 (<entry>), il est nécessaire de renseigner son identifiant(<id>) ainsi que sa cible (<target>). 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**.
```xml
<menu>
<entrytype="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>
<entrytype="main">
<id>sommaire</id>
<target>sommaire</target>
</entry>
</menu>
```
**@todo** : les noeuds *id* sont-ils indispensables ?
#### 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/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
***selectedEntry**: 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**
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()**
* 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/**.
#### 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 :
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
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*).
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écution d'une édition dans un container Docker
## 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 !).
* 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’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* :
