Commit 4bf08b7e authored by Marie Bisson's avatar Marie Bisson
Browse files

maj surcharge

parent feb71d63

documentation/docs/overriding.md

+11 −150
Original line number Diff line number Diff line
@@ -4,6 +4,7 @@ 


Éditer le fichier <span class="dossier">[projet-]editions</span>/<span class="dossier">[edition]</span>/<span class="dossier">fragments</span>/<span class="fichier">accueil.frag.html</span> pour modifier la page d’accueil d’une édition.



Voir [Page d’accueil](../home_page)



## Menu
@@ -15,72 +16,13 @@ Trois paramètres sont disponibles dans cette XSL : 
* **baseURI** : baseURI du projet,

* **selectedTarget** : entrée de menu courante (valeur d’un des attributs @target).



Voir [Menu](../menu)



## Sommaires 



### Sommaire d’une édition



Il est possible de :



* Modifier la XQuery afin de modifier les entrées listées dans le sommaire (ou leur ordre de tri),

* Modifier la XSL transformant cette liste des entrées au format HTML.



#### Modification de la XQuery

Pour modifier la Xquery, il convient de :



1. Créer un fichier <span class="dossier">editions</span>/<span class="dossier">[edition]</span>/<span class="dossier">xq</span>/<span class="fichier">toc.xq</span>,

2. Y rédiger une requête Xquery prenant en compte 3 paramètres :



    * **$baseURI** : valeur de la variable de configuration [baseURI](../config#la-variable-baseuri)

    * **$dbPath**  : valeur de la variable de configuration [dbPath](../config) permettant le requêtage la base de données

    * **$project** : identifiant de l’édition





Exemple de squelette d’une telle XQuery :



```

declare variable $baseURI external;

declare variable $dbPath external;

declare variable $project external;





<ul>

  [...]

<ul>

```  



Afin d'être compatible avec la XSL de la table des matières de MaX (fichier <span class="dossier">[projet-]MaX</span>/<span class="dossier">ui</span>/<span class="dossier">xsl</span>/<span class="dossier">[tei ou ead]</span>/<span class="fichier">toc.xsl</span>), cette XQuery doit générer

un élément `<ul/>` composé d’éléments `<li/>` (et `<ul/>` s’il y a besoin de listes impriquées). Les valeurs des liens devront être renseignées en valeur de l’attribut **data-href** de l’élément ``<li>``.



Exemple de listing (généré par la XQuery par défaut de MaX) compatible avec <span class="dossier">[projet-]MaX</span>/<span class="dossier">ui</span>/<span class="dossier">xsl</span>/<span class="dossier">tei</span>/<span class="fichier">toc.xsl</span> :



```

<ul>

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

  <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.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_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_lorem_3.xml">

    <title xmlns="http://www.tei-c.org/ns/1.0">Lorem Ipsum in MaX - Tome 3. Images et Équations</title>

  </li>

</ul>

```



#### Modification de la XSL





Pour modifier la XSL par défaut, il faut créer un fichier <span class="fichier">toc.xsl</span>.    

 <span class="dossier">[projet-]editions</span>/<span class="dossier">[edition]</span>/<span class="dossier">ui</span>/<span class="dossier">xsl</span>/<span class="dossier">[tei ou ead]</span>/<span class="fichier">toc.xsl</span>.    

 Cette XSL permet detransformer le résultat de la XQuery par défaut ou celle qui la surcharge (<span class="dossier">[projet-]editions</span>/<span class="dossier">[edition]</span>/<span class="dossier">xq</span>/<span class="fichier">toc.xq</span>) en HTML.



En l’absence d'un tel fichier, MaX exécutera <span class="dossier">[projet-]MaX</span>/<span class="dossier">ui</span>/<span class="dossier">xsl</span>/<span class="dossier">[tei ou ead]</span>/<span class="fichier">toc.xsl</span>.

Voir [Sommaire d’une édition](../toc/#sommaire-dune-edition)



### Sommaire d’un document
@@ -89,110 +31,29 @@ Tout comme le sommaire d’une édition, il est possible de : 
* modifier la XQuery afin de modifier les éléments sélectionnés pour le sommaire,

* modifier la XSL transformant ces éléments au format HTML.



#### Modification de la XQuery



1. Créer un fichier <span class="dossier">[projet-]editions</span>/<span class="dossier">[edition]</span>/<span class="dossier">xq</span>/<span class="fichier">document_toc.xq</span>

2. Y rédiger une requête Xquery prenant en compte 4 paramètres :

    * **$baseURI** : valeur de la variable de configuration [baseURI](../config#la-variable-baseuri),

    * **$dbPath**  : valeur de la variable de configuration [dbPath](../config),

    * **$project** : identifiant de l’édition,

    * **$doc**     : nom du document courant pour lequel est construite la table des matières.



Exemple de squelette d’une telle XQuery :



```



declare variable $baseURI external;

declare variable $dbPath external;

declare variable $project external;

declare variable $doc external;



(: xquery listant les items du sommaire du document $doc:)

<ul>

    {

      for $entry in doc($dbPath || '/' || $doc)// ...

      return     

        <li id="..." data-href="..."><head>...</head></li>

    }

</ul>



```  



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



#### Modification de la XSL



La XSL par défaut peut également surchargée : 

Il faut alors créer un fichier <span class="fichier">document_toc.xsl</span>.    

<span class="dossier">[projet-]editions</span>/<span class="dossier">[edition]</span>/<span class="dossier">ui</span>/<span class="dossier">xsl</span>/<span class="dossier">[tei ou ead]</span>/<span class="fichier">document_toc.xsl</span>    



Cette XSL permet de transformer le résultat de la XQuery (XQuery par défaut ou surcharge présente dans <span class="dossier">[projet-]editions</span>/<span class="dossier">[edition]</span>/<span class="dossier">xq</span>/<span class="fichier">document_toc.xq</span> ) en HTML.    

Cette XSL reçoit en entrée :



* le titre du document courant dans une variable **$docTitle**,

* les variables de configuration **$baseuri** et **$project**.





En l’absence d'un tel fichier, MaX exécutera <span class="dossier">[projet-]MaX</span>/<span class="dossier">ui</span>/<span class="dossier">xsl</span>/<span class="dossier">[tei ou ead]</span>/<span class="fichier">document_toc.xsl</span>.

Voir [Sommaire d’une document](../toc/#sommaire-dun-document)



## Texte



La surcharge de transformation de la XSL de consultation du texte se fait en rédigeant une XSL placée dans <span class="dossier">[projet-]editions</span>/<span class="dossier">[edition]</span>/<span class="dossier">ui</span>/<span class="dossier">xsl</span>/<span class="fichier">text_hook.xsl</span>.



Voir [Texte](../text/#textes)



## Barre de navigation



En ajoutant une feuille de transformation dans <span class="dossier">[projet-]editions</span>/<span class="dossier">[edition]</span>/<span class="dossier">ui</span>/<span class="dossier">xsl</span>/<span class="dossier">[tei ou ead]</span>/<span class="fichier">nav_bar.xsl</span>.



Celle-ci recevra en entrée le même arbre XML que <span class="dossier">[projet-]editions</span>/<span class="dossier">[edition]</span>/<span class="dossier">ui</span>/<span class="dossier">xsl</span>/<span class="dossier">[tei ou ead]</span>/<span class="fichier">document_toc.xsl</span> 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 suivant le fragment courant

* **$prevArrow** : 'true' s’il existe des fragments précédant le fragment courant



La surcharge du comportement par défaut de la barre de navigation se fait en ajoutant une feuille de transformation dans <span class="dossier">[projet-]editions</span>/<span class="dossier">[edition]</span>/<span class="dossier">ui</span>/<span class="dossier">xsl</span>/<span class="dossier">[tei ou ead]</span>/<span class="fichier">nav_bar.xsl</span>.



Voir [Texte, Barre de navigation](../text/#barre-de-navigation)



## Mise en page



Le template de mise en page par défaut se trouve dans <span class="dossier">[projet-]MaX</span>/<span class="dossier">ui</span>/<span class="dossier">templates</span>/<span class="fichier">[tei ou ead].html</span>.    

Il est possible de remplacer cette mise en page en créant son propre template dans <span class="dossier">[projet-]editions</span>/<span class="dossier">[edition]</span>/<span class="dossier">ui</span>/<span class="dossier">templates</span>/<span class="fichier">template.html</span>.



Voir [Gabarits, mise en page](../layouttext)



## Métadonnées HTML



Le contenu des métadonnées d’une édition est modifiable en créant un fichier <span class="dossier">[projet-]editions</span>/<span class="dossier">[edition]</span>/<span class="dossier">xq</span>/<span class="fichier">metadata.xq</span>.



Cette XQuery recevra 3 paramètres :



* **$project** : l'identifiant de l'édition,

* **$requestPath** : le chemin de l'URL en cours de consultation,

* **$content** : le fragment XML en cours de consultation.



Exemple d'une telle XQuery (comportement par défaut de MaX) :



```

import module namespace max.html = 'pddn/max/html' at '../../../rxq/html.xqm';

import module namespace max.config = 'pddn/max/config' at '../../../rxq/config.xqm';



declare variable $project external;

declare variable $requestPath external;

declare variable $content external;



<title>{max.html:cleanValue(string-join(($content//(*:h3 | *:h2 | *:h1)[1])//text(), ''))}</title>,

<meta name="author" content="{max.config:getProjectAuthor($project)}"/>,



<meta property="dc:description" content="{max.config:getProjectDescription($project)}"/>,

<meta property="dc:title" content="{max.html:cleanValue(string-join(($content//(*:h3 | *:h2 | *:h1)[1])//text(), ''))}"/>,

<meta property="dc:type" content="Web page"/>,

<meta property="dc:relation" content="{$requestPath}"/>,



<meta property="og:description" content="{max.config:getProjectDescription($project)}"/>,

<meta property="og:title" content="{max.html:cleanValue(string-join(($content//(*:h3 | *:h2 | *:h1)[1])//text(), ''))}"/>,

<meta property="og:type" content="page"/>,

<meta property="og:url" content="{$requestPath}"/>



```

Voir [Métadonnées HTML](../metadata)

documentation/docs/text.md

+6 −1
Original line number Diff line number Diff line
@@ -42,8 +42,13 @@ graph LR; 
Lors de l’affichage du texte d’un fragment, la barre de navigation (sous forme de liste déroulante) permet de naviguer de fragment en fragment.    

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 de consultation.    



Voir [Surcharges, Barre de navigation](../overriding#barre-de-navigation).

En ajoutant une feuille de transformation dans <span class="dossier">[projet-]editions</span>/<span class="dossier">[edition]</span>/<span class="dossier">ui</span>/<span class="dossier">xsl</span>/<span class="dossier">[tei ou ead]</span>/<span class="fichier">nav_bar.xsl</span>.



Celle-ci recevra en entrée le même arbre XML que <span class="dossier">[projet-]editions</span>/<span class="dossier">[edition]</span>/<span class="dossier">ui</span>/<span class="dossier">xsl</span>/<span class="dossier">[tei ou ead]</span>/<span class="fichier">document_toc.xsl</span> 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 suivant le fragment courant

* **$prevArrow** : 'true' s’il existe des fragments précédant le fragment courant



## Options de lecture

documentation/docs/toc.md

+112 −10
Original line number Diff line number Diff line
@@ -32,13 +32,69 @@ Dans le cas où les fichiers XML sont organisés en dossiers et sous-dossiers, l 


### Surcharge du comportement



|Nota Bene|

|---------|

|Ne faudrait-il pas détailler la surcharge ici plutôt ?|

Il est possible de :



* Modifier la XQuery afin de modifier les entrées listées dans le sommaire (ou leur ordre de tri),

* Modifier la XSL transformant cette liste des entrées au format HTML.



#### Modification de la XQuery

Pour modifier la Xquery, il convient de :



1. Créer un fichier <span class="dossier">editions</span>/<span class="dossier">[edition]</span>/<span class="dossier">xq</span>/<span class="fichier">toc.xq</span>,

2. Y rédiger une requête Xquery prenant en compte 3 paramètres :



    * **$baseURI** : valeur de la variable de configuration [baseURI](../config#la-variable-baseuri)

    * **$dbPath**  : valeur de la variable de configuration [dbPath](../config) permettant le requêtage la base de données

    * **$project** : identifiant de l’édition





Exemple de squelette d’une telle XQuery :



```

declare variable $baseURI external;

declare variable $dbPath external;

declare variable $project external;





<ul>

  [...]

<ul>

```  



Afin d'être compatible avec la XSL de la table des matières de MaX (fichier <span class="dossier">[projet-]MaX</span>/<span class="dossier">ui</span>/<span class="dossier">xsl</span>/<span class="dossier">[tei ou ead]</span>/<span class="fichier">toc.xsl</span>), cette XQuery doit générer

un élément `<ul/>` composé d’éléments `<li/>` (et `<ul/>` s’il y a besoin de listes impriquées). Les valeurs des liens devront être renseignées en valeur de l’attribut **data-href** de l’élément ``<li>``.



Exemple de listing (généré par la XQuery par défaut de MaX) compatible avec <span class="dossier">[projet-]MaX</span>/<span class="dossier">ui</span>/<span class="dossier">xsl</span>/<span class="dossier">tei</span>/<span class="fichier">toc.xsl</span> :



```

<ul>

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

  <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.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_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_lorem_3.xml">

    <title xmlns="http://www.tei-c.org/ns/1.0">Lorem Ipsum in MaX - Tome 3. Images et Équations</title>

  </li>

</ul>

```



#### Modification de la XSL



<br/>



Voir la section [surcharges, sommaire d’une édition](../overriding/#sommaire-dune-edition).

Pour modifier la XSL par défaut, il faut créer un fichier <span class="fichier">toc.xsl</span>.    

 <span class="dossier">[projet-]editions</span>/<span class="dossier">[edition]</span>/<span class="dossier">ui</span>/<span class="dossier">xsl</span>/<span class="dossier">[tei ou ead]</span>/<span class="fichier">toc.xsl</span>.    

 Cette XSL permet detransformer le résultat de la XQuery par défaut ou celle qui la surcharge (<span class="dossier">[projet-]editions</span>/<span class="dossier">[edition]</span>/<span class="dossier">xq</span>/<span class="fichier">toc.xq</span>) en HTML.



En l’absence d'un tel fichier, MaX exécutera <span class="dossier">[projet-]MaX</span>/<span class="dossier">ui</span>/<span class="dossier">xsl</span>/<span class="dossier">[tei ou ead]</span>/<span class="fichier">toc.xsl</span>.







## Sommaire d’un document
@@ -117,11 +173,57 @@ let $title:= max.util:getDocTitle(max.config:getProjectDBPath($project), 
<br/>-->



### Surcharge du comportement

Tout comme le sommaire d’une édition, il est possible de :



|Nota Bene|

|---------|

|Ne faudrait-il pas détailler la surcharge ici plutôt ?]

* modifier la XQuery afin de modifier les éléments sélectionnés pour le sommaire,

* modifier la XSL transformant ces éléments au format HTML.



#### Modification de la XQuery



1. Créer un fichier <span class="dossier">[projet-]editions</span>/<span class="dossier">[edition]</span>/<span class="dossier">xq</span>/<span class="fichier">document_toc.xq</span>

2. Y rédiger une requête Xquery prenant en compte 4 paramètres :

    * **$baseURI** : valeur de la variable de configuration [baseURI](../config#la-variable-baseuri),

    * **$dbPath**  : valeur de la variable de configuration [dbPath](../config),

    * **$project** : identifiant de l’édition,

    * **$doc**     : nom du document courant pour lequel est construite la table des matières.



Exemple de squelette d’une telle XQuery :



```



declare variable $baseURI external;

declare variable $dbPath external;

declare variable $project external;

declare variable $doc external;



(: xquery listant les items du sommaire du document $doc:)

<ul>

    {

      for $entry in doc($dbPath || '/' || $doc)// ...

      return     

        <li id="..." data-href="..."><head>...</head></li>

    }

</ul>



```  



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



#### Modification de la XSL



La XSL par défaut peut également surchargée : 

Il faut alors créer un fichier <span class="fichier">document_toc.xsl</span>.    

<span class="dossier">[projet-]editions</span>/<span class="dossier">[edition]</span>/<span class="dossier">ui</span>/<span class="dossier">xsl</span>/<span class="dossier">[tei ou ead]</span>/<span class="fichier">document_toc.xsl</span>    



Cette XSL permet de transformer le résultat de la XQuery (XQuery par défaut ou surcharge présente dans <span class="dossier">[projet-]editions</span>/<span class="dossier">[edition]</span>/<span class="dossier">xq</span>/<span class="fichier">document_toc.xq</span> ) en HTML.    

Cette XSL reçoit en entrée :



* le titre du document courant dans une variable **$docTitle**,

* les variables de configuration **$baseuri** et **$project**.



<br/>



Voir la section [surcharges, sommaire d’un document](../overriding/#sommaire-dun-document).
 
En l’absence d’un tel fichier, MaX exécutera <span class="dossier">[projet-]MaX</span>/<span class="dossier">ui</span>/<span class="dossier">xsl</span>/<span class="dossier">[tei ou ead]</span>/<span class="fichier">document_toc.xsl</span>.

documentation/docs/metadata.md

+1 −1

File changed.

Contains only whitespace changes.