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) : contient les fichiers d'internationalisation (en surcharge/complément de ceux du bundle de vocabulaire)
• un dossier static (optionnel) : contient les fichiers statiques (CSS, Javascript, images, etc.)

Les routes principales

• version HTML du source XML nommé $doc.xml dans la collection $collection :

 /{$lang=[a-z]{2}}/{$collection=.+}/{$doc=[a-zA-Z0-9_]+}.html

• fichier statique d'un bundle (js, css, etc.) :

/{$bundle}/static/{$filename}

• page HTML stockée dans content_html/[$lang]/[$page].html ou transforme le fichier Markdown content_html/[$lang]/[$page]:

/{$lang=[a-z]{2}}/pages/{$page=[a-zA-Z0-9_]+}.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)

Construction d'un corpus numérique

Configuration

La commande climax new [project_name] crée un dossier project_name avec une configuration par défaut renseignée dans le fichier config.xml.

Exemple de configuration minimale :

<!-- config.xml -->
<configuration xmlns="http://certic.unicaen.fr/max/ns/1.0" vocabulary-bundle="max-dumb-xml">
    <version name="x.y.z" url="https://git.unicaen.fr/pdn-certic/max-v2/-/archive/x.y.z/max-v2-x.y.z.zip"/>
    <languages>
        <language>fr</language>
        <language>en</language>
    </languages>
    <title>mon Corpus Numérique</title>

    <bundles>    
        <bundle name="max-dumb-xml"/>
    </bundles>

</configuration>

La commande climax config permet de consulter le contenu de ce fichier.

La configuration doit à minima déclarer :

• un bundle de vocabulaire (attribut vocabulary-bundle)
• un titre (nom du corpus numérique) dans la balise <title/>
• l'intégralité des bundles utilisés doit être listée dans la section <bundles/>
• la liste des langues supportées dans la section <languages/>

Ajout de sources XML

climax feed /path/to/file.xml

Les fichiers sont ajoutés à la base max de l'instance du serveur BaseX intégré à MaX.

Contenus HTML

Ils sont à placer dans le dossier contents_html, dans un sous-dossier correspondant au code langue du contenu. Ces fichiers peuvent être au format HTML ou Markdown.

Exemple d'arborescence d'un dossier contents_html :

  ├── content_html
  │   ├── en
  │   │   └── index.html
  │   └── fr
  │       ├── a_propos.md
  │       └── index.html

Ces contenus sont consultables sur /{$lang=[a-z]{2}}/pages/{$page=[a-zA-Z0-9_]+}.html. Par exemple, pour l'aboresence ci-dessus :

• /fr/pages_a_propos.html
• /en/pages/index.html

Autoroutes

Une autoroute est une fonctionnalité xquery automatiquement branchée sur une URL. Chaque fonctionnalité doit être placé dans un fichier xquery du dossier autoroute.

(:exemple d'autoroute | fichier autoroute/test.xq)
xquery version "3.0";

import module namespace templating = 'https://certic.unicaen.fr/max/templating' at '../.max/basex/webapp/max/core/templating.xqm';

(: paramètre à déclarer. Il est issu de l'url courante et est systématiquement passé en paramètre d'une fonction d'autoroute :)
declare variable $lang external;

let $translations := map {
    'fr' : "Ceci est un test d'autoroute !",
    'en' : 'This is a custom autoroute test !'
}

let $content := <div>
                    <p>{$translations?$lang} (<code>autoroute/test.xq</code>)</p>
                    {
                        for $n in 1 to 42
                        return <span class="me-2">{$n}</span>
                    }
                    <p></p>
                </div>
return templating:render('page.html', map{'content': $content, 'lang': $lang})

Le résultat de cette xquery est automatiquement accessible sur /{$lang}/test.html.

Templates

Il est possible de surcharger les templates proposés par le bundle de vocabulaire actif. Les surchages doivent être placées dans le dossier templates en utilisant les mêmes noms que les templates du bundle de vocabulaire actif (consulter sa documentation pour plus de précisions).

Fichiers statiques

Les fichiers placés dans ce dossier peuvent être convoqués depuis les templates à l'aide de la fonction templating:static('monfichier.extension')

Il est possible de surcharger les fichiers statiques (CSS, JS, etc) du bundle de vocabulaire actif en utilisant les mêmes noms que les fichiers du bundle de vocabulaire actif (consulter sa documentation pour plus de précisions).

Ajouter un bundle

Bundle officiel

climax bundles-add bundle_name

Pour obtenir la liste des bundles disponibles :

climax bundles-list

Bundle local

Indiquer le chemin vers l'archive du bundle à installer :

climax bundles-add /path/to/custom_bundle.zip

Internationalisation

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

{
  "gm": "bonjour",
  "ge": "bonsoir"
}

Depuis une fonction xquery, la traduction se fait à l'aide de la fonction i18n:translate($key, $lang) :

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

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