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
...
...
@@ -26,33 +26,110 @@ Vous pouvez nous contacter via [contact.certic@unicaen.fr](mailto:contact.certic
- BaseX 9.2+
## Installation
### Installation BaseX (et éventuels changements de ports)
```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.
- 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)
```
$ cd PATH/Documents/PDN/Standalone/maxTest/bin
$ ./basexhttp &
```
- 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 :
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* :
