readme.md 15.4 KB
Newer Older
dje's avatar
dje committed
1
# MaX
dje's avatar
dje committed
2

Arnaud Daret's avatar
Arnaud Daret committed
3
4
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/)

dje's avatar
dje committed
5
6
## Licence

Jerome Chauveau's avatar
Jerome Chauveau committed
7
voir [legal.txt](legal.txt)
dje's avatar
dje committed
8

Pierre-Yves Buard's avatar
Pierre-Yves Buard committed
9
10
11
12
## Participer au développement

Demander à rejoindre [MaX-Community](https://git.unicaen.fr/MaX-Community).

dje's avatar
dje committed
13
## Contacts
dje's avatar
dje committed
14

Arnaud Daret's avatar
Arnaud Daret committed
15
Vous pouvez nous contacter via [contact.certic@unicaen.fr](mailto:contact.certic@unicaen.fr?subject=[MaX])
dje's avatar
dje committed
16

dje's avatar
dje committed
17
---
18

dje's avatar
dje committed
19
20
21
22
## Prérequis

- Java 8+

Jerome Chauveau's avatar
Jerome Chauveau committed
23
- NodeJS (et npm) 10+
dje's avatar
dje committed
24
25

- xmllint
Jerome Chauveau's avatar
Jerome Chauveau committed
26

Jerome Chauveau's avatar
Jerome Chauveau committed
27
- BaseX 9.2+
dje's avatar
dje committed
28
29
30
31

## Installation

```bash
Arnaud Daret's avatar
Arnaud Daret committed
32
$ cd tools && ./max.sh -i
dje's avatar
dje committed
33
# change dir to your basex app folder
34
$ cd </path/to/basex>/webapp
dje's avatar
dje committed
35
36
# create a symlink on your MaX instance
$ sudo ln -s /path/to/max .
37
38
39
# run basex http
$ cd </path/to/basex>/bin
$ ./basexhttp
Jerome Chauveau's avatar
Jerome Chauveau committed
40
# then check your install at: http://localhost:8984/max: 'MaX' should be displayed.
dje's avatar
dje committed
41
42
43
44
45
46
```

Il est fortement recommandé d'utiliser saxon9 comme moteur de transformation XSLT. Il faut alors l'ajouter aux librairies chargées par BaseX :

```bash
$ cp </path/to/saxon/>saxon9.jar </path/to/basex>/lib
Jerome Chauveau's avatar
Jerome Chauveau committed
47
```
dje's avatar
dje committed
48

49
50


dje's avatar
dje committed
51
52
53
54
55
56
57
58
### Édition de démonstration

```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
59
$ export BASEX_PATH=/path/to/basex
60
61
62
```

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 :
dje's avatar
dje committed
63

64
```bash
Jerome Chauveau's avatar
Jerome Chauveau committed
65
$ ./max.sh -d
Jerome Chauveau's avatar
Jerome Chauveau committed
66
```
Arnaud Daret's avatar
Arnaud Daret committed
67

Jerome Chauveau's avatar
Jerome Chauveau committed
68
L'édition de démonstration est consultable à **http://localhost:8984/demo_lorem**
dje's avatar
dje committed
69

70
## Paramétrages
dje's avatar
dje committed
71

72
73
### Ajouter une édition

Jerome Chauveau's avatar
Jerome Chauveau committed
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112

```
# Utilisation du port par défaut de BaseX : 1984
$ ./max.sh -n

ou

./max.sh -p 1234 -n
```

Plusieurs questions sont posées :

	1. Identifiant du projet ?

Saisissez le nom de site, sans espace ni caractères spéciaux. Exemple : pouille

	2. Nom de la base de données ?

  Renseignez le nom de la base de données XML

	3. Vocabulaire XML du projet (tei, ead, ...)?

  Saisissez tei ou ead

	4. Dossier des sources XML à charger ?

  Resneigner le chemin complet vers le dossier où se trouvent les sources XML. Exemple : /Users/johndoe/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 :
`http://localhost:[numero_de_port]/NOM_PROJET`

Exemple : http://127.0.0.1:8984/pouille
113

dje's avatar
dje committed
114
115
### Fichiers de configuration

116
117
118
119
120
121
122
123
#### 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 :*

124
```
125
<!--inclusion de la configuration de l'édition demo au sein de la configuration de MaX-->
126
127
 <xi:include href="../editions/demo/demo_config_inc.xml"/>

128
129
```

Jerome Chauveau's avatar
Jerome Chauveau committed
130
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*.
131

dje's avatar
dje committed
132
133
### Page d'accueil

Jérôme Chauveau's avatar
Jérôme Chauveau committed
134
135
136
* **URL** : http://[host]:[port]/[project]/accueil
* **Fonctionnalité** : Affiche le fragment HTML stocké dans **editions/[project]/fragments/accueil.frag.html**

dje's avatar
dje committed
137

138
139
### Menu

dje's avatar
dje committed
140
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. 
141

dje's avatar
dje committed
142
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**. 
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169

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

Arnaud Daret's avatar
Arnaud Daret committed
170
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**.
171

dje's avatar
dje committed
172
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 :
173
174
175

 * **projectId** : identifiant du projet
 * **baseURI** : baseURI du projet
Jerome Chauveau's avatar
Jerome Chauveau committed
176
 * **selectedTarget**: entrée de menu courante (valeur d'un des attributs @target)
177
178
179

 

dje's avatar
dje committed
180
181
### Table des matières d'une édition

dje's avatar
dje committed
182
183
La table des matières d'une édition est disponible à l'URL **http://[host]:[port]/[project]/sommaire**

184
185
#### Fonctionnement par défaut

186
Par défaut, la page de sommaire liste les documents présents dans la collection:
187
188
189
190

 * 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()**

Jérôme Chauveau's avatar
Jérôme Chauveau committed
191
#### Surchage du comportement
192

Jerome Chauveau's avatar
Jerome Chauveau committed
193
194
195
196
197
198
199
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;
200
declare variable $doc external;
Jerome Chauveau's avatar
Jerome Chauveau committed
201
202
203
204
205
206

<div>
 [ ... ]
</div>
```

Jerome Chauveau's avatar
Jerome Chauveau committed
207
Pour être compatible avec la XSL par défaut, cette XQUERY devra générer une balise *ul* composée de *li* et *ul*.
208
Les items de lien devront renseigner ces liens dans l'attribut **data-href**.
Jerome Chauveau's avatar
Jerome Chauveau committed
209
210

Exemple de listing (comportement par défaut):
211
212

```
Jerome Chauveau's avatar
Jerome Chauveau committed
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
<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>
230
231
232

```

Jerome Chauveau's avatar
Jerome Chauveau committed
233
234
235
236

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 :

237
238
 * 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
Jerome Chauveau's avatar
Jerome Chauveau committed
239
240


241
242
La feuille de transformation par défaut se trouve dans **max/ui/xsl/toc.xsl**

dje's avatar
dje committed
243
244
### Sommaire d'un document

dje's avatar
dje committed
245
246
Le sommaire d'un document est accessible à l'URL **http://[host]:[port]/[project]/sommaire/[document_path].xml**

Jerome Chauveau's avatar
Jerome Chauveau committed
247
#### Fonctionnement par défaut
248

Jerome Chauveau's avatar
Jerome Chauveau committed
249
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*.
250
251
252


#### Surcharge
253
La modification peut se faire par l'ajout d'un fichier **document_toc.xq** dans **editions/[projectId]/xq/**.
254

255
Le fichier doit à minima déclarer les variables qui lui sont automatiquement passées en paramètres par MAX :
256
```
257
declare default element namespace "http://www.tei-c.org/ns/1.0";
258
declare variable $baseURI external;
dje's avatar
dje committed
259
260
261
declare variable $dbPath external; (:path du document dans la db:)
declare variable $project external; (: id du projet :)
declare variable $doc external; (: nom du document :)
262

263
264
265
(: xquery listant les items du sommaire du document $doc:)
<ul>
    <li id="..." data-href="..."><head>...</head></li>
266
 [ ... ]
267
</ul>
268
269

```
270
271
272
273
274
275
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.

276

277
278
279
280
281
282
283
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.
Jérôme Chauveau's avatar
Jérôme Chauveau committed
284
 
285

dje's avatar
dje committed
286
287
### Textes

Jérôme Chauveau's avatar
Jérôme Chauveau committed
288
289
290
291
292
293
294
295
La consultation des textes se fait aux URLs suivantes :

 * **http://[host]:[port]/[project]/[chemin_fichier.xml]/[id]** : consultation d'un fragment identifié
 * **http://[host]:[port]/[project]/doc/[chemin_fichier.xml]** : consultation d'un document XML complet
 * **http://[host]:[port]/[project]/fragment_html/[id]** : consultation "isolée" (sans css, jc, menu, barre de navigation, etc.). L'ajout du query parameter
 *?wrap=true* offre une consultation dans une page HTML complète (css + js).
 
 La feuille de transformation appliquée par défaut se trouve dans **ui/xsl/[environnement]/[environnement].xsl** (environnement = tei ou ead).
Jerome Chauveau's avatar
Jerome Chauveau committed
296
297
298
299
 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.

Jérôme Chauveau's avatar
Jérôme Chauveau committed
300
301
 

dje's avatar
dje committed
302
303
#### Options de lecture

304
305
306
### 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.
dje's avatar
dje committed
307
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
308
309
de consultation.

Jerome Chauveau's avatar
Jerome Chauveau committed
310
Il est possible de modifier l'affichage des ces entrées en ajoutant une feuille de transformation dans  **editions/[projectId]/xsl/nav_bar.xsl**.
311
312
313
314
315
316
317
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
                                                    
                                                                                                      

dje's avatar
dje committed
318
319
#### Alignement

dje's avatar
dje committed
320
321
### Page statique

322
323
324
325
326
327
328
329
330
331
332
333
334
335
### 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**. 



dje's avatar
dje committed
336
337
### Plugins

dje's avatar
dje committed
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
#### Abréviation

#### Ajout

#### Apparat critique

#### Fil d'ariane (Breadcrumb)

#### Correction

#### Équations

#### Images (img_viewer)

#### Notes

#### Pagination (Pager)

#### Recherche (search)

Jerome Chauveau's avatar
Jerome Chauveau committed
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
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 :

```xml
<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
dje's avatar
dje committed
377

378
379
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
Jerome Chauveau's avatar
Jerome Chauveau committed
380
du fichier *plugins/<plugin_name>/resources.json*.
381
Ex : l'édition de démo fonctionnant avec les plugins *img_viewer* et *equations*, les librairies *Mathjax* et *Openseadragon* sont
Jerome Chauveau's avatar
Jerome Chauveau committed
382
automatiquement copiées lors de l'installation de l'édition (lecture de *equations/dependencies.json* et *img_viewer/resources.json*).
dje's avatar
dje committed
383

384

385
386
387
388
389
390
391
392
393
394
395
396
397
## 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:)
[...]

```

398
399
400

## Exécution d'une édition dans un container Docker

dje's avatar
dje committed
401
402
403
404

* 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* :
dje's avatar
dje committed
405

406
407
408
Création de l'édition de démonstration

```
Jerome Chauveau's avatar
Jerome Chauveau committed
409
$ ./tools/max.sh -i && ./tools/max.sh -d
410
411
412
413
414
415

```

Ajout des droits sur les données de la base pour le container :

```
dje's avatar
dje committed
416
$ sudo chown -R 1984 /opt/basex/data/max_demo_lorem
417
418
419
420
```

Création de l'image de l'édition puis lancement du container :

dje's avatar
dje committed
421
422
```
 $ sudo docker build -t unicaen/max_demo_lorem .
dje's avatar
dje committed
423
 $ sudo docker run -d -p 9999:8984 --volume /opt/basex/data/max_demo_lorem:/srv/basex/data/max_demo_lorem unicaen/max_demo_lorem
dje's avatar
dje committed
424
425
426
427
```



Arnaud Daret's avatar
Arnaud Daret committed
428
429
430
![UNICAEN-PDN-CERTIC](https://www.certic.unicaen.fr/ui/images/UNICAEN_PDN_CERTIC.png)

[![IA](http://medites.fr/partenaires/investissement-avenir/@@images/d94128c2-f712-4712-9659-a86f6f8f36c5.jpeg)](http://www.agence-nationale-recherche.fr/investissements-d-avenir/)
dje's avatar
dje committed
431
![Biblissima](http://asynchrone.fr/sites/default/files/projet/logo/biblissima-logo.png)