link to documentation repo

make install && make demo && make run

```

Pour ajouter des sources xml :

```

make feed path=/path/to/sources_dir/

```

## Fonctionnement général

L'application est scindée en 2 blocs :

 - le cœur : déclaration des routes/fonctionnalités de base, accès aux sources xml et à la configuration, système de templating, traduction etc.

 - les bundles : chaque bundle ajoute une (ou des) fonctionnalité(s) à MaX.

Les sources XML à afficher doivent être stockées dans une base nommée `max`.

## Bundle de vocabulaire

Un bundle de *vocabulaire* est spécialisé dans le rendu d'un vocabulaire XML. C'est le cas du `max-dumb-tei-bundle` (il affiche une table des matières et les sources brutes non transformées pour des sources XML-TEI/.

Ce type de bundle doit contenir :

 - une fonction xquery déclarée dans l'espace de nom du bundle et définie par `[ns]:doc-to-html($document as document-node(), $lang as xs:string)`

  Cette fonction sera automatiquement appelée par le cœur pour la route `/{$lang=[a-z]{2}}/{$collection=.+}/{$doc=[a-zA-Z0-9_]+}.html`

 - un dossier templates contenant les templates :

   - `page.html` : template appliqué par défaut par le cœur pour les rendus des différentes pages

   - `error.html` : template d'erreur appliqué par défaut par le cœur

 - un fichier `expath-pkg.xml` définissant le module au format EXPath

 - un dossier `autoroute` (optionnel) avec un fichier `[page].xq` pour chaque fonctionnalité servie sur la route `/{$lang=[a-z]{2}}/{$page=[a-zA-Z0-9_]+}.html`

 - un dossier `webapp` (optionnel) contenant les routes (restxq) servies par le bundle

 - un dossier `locales` (optionnel) avec un fichier `[codelang].json` par langues gérées

 - un dossier `static` (optionnel) contenant les assets du bundle (fichiers js, css, images etc.)

### Configuration

La configuration se fait dans le fichier `config.xml`.

Afin d'opérer à un rendu, un bundle de vocabulaire doit être déclaré dans le fichier de configuration de MaX.

Exemple de configuration minimale :

```html

<!-- config.xml -->

<configuration xmlns="http://certic.unicaen.fr/max/ns/1.0" env="dev" vocabulary-bundle="max-dumb-tei-bundle">

    <languages>

        <language>fr</language>

        <language>en</language>

    </languages>

    <title>mon Corpus Numérique</title>

</configuration>

```

Note :  `.max/basex/webapp/max/` pointe vers  `src/main`, ce symlink est automatiquement créé par la commande `make install`.

## Organisation des sources

  - `resources` : ressources additionnelles  

  - `test` : source des tests (@todo)

Ce dépôt contient les bundles 

 - `max-dev` : aide au développement ([README](src/main/bundles/max-dev/README.md)).

 - `max-sources` : export des sources XML ([README](src/main/bundles/max-sources/README.md)).

## Le dossier `.max`

Il contient le serveur BaseX. C'est un dossier (caché) purement technique dans lequel l'utilisateur n'aura pas (et ne devra pas) intervenir.

## Lien symbolique dans un environnement de développement du core

- `.max/basex/webapp/max/` pointe vers  `src/main`

Lien automatiquement créé par la commande `make install`.

## Les routes principales

Elles sont déclarées dans le fichier `src/main/core/routes.xqm` :

- `/{$lang=[a-z]{2}}/{$collection=.+}/{$doc=[a-zA-Z0-9_]+}.html` : version HTML du source XML nommé `$doc.xml` dans la collection `$collection`

- `/{$bundle}/static/{$filename}` : fichier statique d'un bundle (js, css, etc.)

- `/{$lang=[a-z]{2}}/pages/{$page=[a-zA-Z0-9_]+}.html` : rend la page HTML stockée dans  `content_html/[$lang]/[$page].html` ou transforme le fichier Markdown`content_html/[$lang]/[$page].md` en HTML.

- `/{$lang=[a-z]{2}}/{$page=[a-zA-Z0-9_]+}.html` : exécute

  - `autoroute/{$page}.xq` : si le fichier existe

  - sinon, `.max/basex/webapp/max/bundles/${bundle_vocabulaire}/autoroute/{$page}.xq` : si le fichier existe

  - sinon, exécute la fonction `${bundle_vocabulaire}:doc-to-html` du bundle de vocabulaire actif (transformation de la source `{$page}.xml`)

  Par exemple, si `max-dumb-tei-bundle` est actif, la route `/fr/tdm.html` retourne le résultat de `.max/basex/webapp/max/bundles/max-dumb-tei-bundle/autoroute/tdm.xq`

## Organisation d'un corpus numérique

 - un fichier config.xml

 - un dossier `templates` (optionnel) : contient les templates HTML (en surcharge/complément de ceux du bundle de vocabulaire)

 - un dossier `autoroute` (optionnel)

 - un dossier `content_html` (optionnel) : contient les contenus HTML (ou markdown)

 - un dossier `locales` (optionnel) : les fichiers d'internationalisation (en surcharge/complément de ceux du bundle de vocabulaire)

## Le dossier .max

Il contient le serveur BaseX. C'est un dossier (caché) purement technique dans lequel l'utilisateur n'aura pas (et ne devra pas) intervenir.

## Développement d'un bundle de vocabulaire

 - Le dossier racine du bundle doit être placé (directement ou via un lien symbolique) dans le répertoire `.max/basex/webapp/max/bundles`.

 - Le dossier racine du bundle doit contenir un fichier `expath-pkg.xml` décrivant le bundle :

````xml

<package xmlns="http://expath.org/ns/pkg"

         name="name"

         abbrev="abbrev_name"

         version="0.0.1"

         spec="1.0">

   <!-- dépendances -->      

   <dependency package="max"/>

    <!-- titre -->   

   <title>...</title>

   <!-- url vers page du bundle -->

   <home>...</home>

   <xquery>

      <!-- namespace du bundle -->

      <namespace>...</namespace>

      <!-- nom du fichier xqm contenant la fonction bundle-namespace:doc-to-html(), stocké dans le répertoire abbrev_name du bundle-->

      <file>...</file>

   </xquery>

</package>

````

### Ajouter une fonctionnalité

#### Autoroute

Créer dans le dossier du bundle un fichier `autoroute/my_feature.xq`. Le résultat de cette XQuery est automatiquement disponible sur la route :

`/{$lang=[a-z]{2}}/my_feature.html`. Un exemple (tdm.xq) est disponible dans le `max-dumb-tei-bundle`.

Cette XQuery reçoit le paramètre `$lang` issu de la route courante.

#### Fonctionnalité avancée

Ajouter une fonction RestXQ dans un fichier `.xqm` du bundle.

### Templating

Les templates HTML doivent être placés dans le répertoire `templates` du bundle.

L'injection de variables dans un template HTML se fait à l'aide de la fonction `templating:render($template as xs:string, $parameters as map)`

#### Héritage

La racine du template fils doit être déclarée à l'aide de la balise `template` et de l'attribut `data-extends`:

````html

<!-- template_fils.html -->

<template data-extends="template_de_base.html">

  [...]

</template>

````

#### Blocs nommés

Il est possible de nommer des blocs à l'aide de la balise `<slot/>` et de l'attribut `name` :

````html

<!-- template_de_base.html -->

<slot name="mon_bloc"></slot>

````

Pour ensuite en définir leur contenu dans un template fils. La définition du bloc se fait avec la balise HTML souhaitée et l'attribut `slot` correspondant au nom du bloc parent (`@name`) à redéfinir : 

````html

<!-- template_fils.html -->

<div slot="mon_bloc">

  Bonsoir

</div>

````

#### Inclusions

L'inclusion d'un template au sein d'un autre se fait à l'aide de la balise `template` et de l'attribut `data-include`

````html

<!-- template.html -->

<template data-include="autre_template.html"></template>

````

#### Injection de variables

L'ensemble des variables passées en paramètre de l'appel à la fonction `render` peuvent être injectées dans un template :

````html

<p>{$ma_variable}</p>

````

#### Appels de fonction

L'ensemble des fonctions  des modules déclarés dans le fichier `expath-pkg.xml` sont accesibles depuis les templates.

````html

<!-- ajout du titre du corpus numérique dans la balise <title/>-->

<head><title>{conf:get-title()}</title></head>

[...]

<!-- traduction de la clé 'tdm' -->

<span><title>{i18n:translate('tdm', $lang)}</span>

````

### Internationalisation

Les fichiers de traductions doivent être placées dans le dossier `locales` du bundle, avec un fichier au format json par langue.

````json

{

  "gm": "bonjour",

  "ge": "bonsoir"

}

````

## Documentations

La traduction se fait à l'aide de la fonction `templating:translate($key, $lang)` :

Consultables [ici] (https://git.unicaen.fr/pdn-certic/max-documentation/-/tree/max-v2/docs)

````html

<p>{templating:translate('ge', $lang)}</p>

````

Note : La variable `$lang` doit être passée en paramètre de l'appel à la fonction `render`.

 No newline at end of file