Pleade Menus

Menus

Pleade propose des menus de navigation qui sont construits dynamiquement à partir du fichier de configuration module-eadeac/conf/menus.xconf (voir en [[Annexe/Fichier de configuration des menus]]). Chaque menu et chaque item y est défini de manière déclarative, sans programmation. La structure XML de ce fichier est très simple. Nous allons l'aborder par étape.

Structure générale

La structure générale du fichier est la suivante :

<menus>
  <menu id="" type="">
    <item id="" type="" … />
    <item id="" type="" … />
    <item id="" type="" … >
      <item id="" type="" … />
      <item id="" type="" … />
      ⋮
    </item>
    ⋮
  </menu>
  <menu>
  ⋮
  </menu>
</menus>

Ainsi, au premier niveau, le fichier contient un élément <menus> qui contient un ou plusieurs élément(s) <menu>. Ces derniers contiennent des éléments <item>, qui peuvent eux-mêmes contenir d'autres éléments <item>, ce qui constitue un sous-menu en quelque sorte.

Nous allons documenter d'abord la définition d'un <menu>, ensuite des <item>.

Élément <menu>

La définition d'un menu est fait à l'aide de la structure XML suivante :

<menu
  id=""
  type=""
  depends=""
  reserve=""
  class="pl-accordion"
>
  <item … />
  <menu … />
  ⋮
</menu>

Un élément <menu> peut contenir un sous-élément <menu>, <item> ou les deux types.

Les informations importantes sont donc définies dans les quatre attributs, définis ci-dessous :

Paramètre	Description
id	Obligatoire. L'identifiant du menu. Il doit être unique parmi tous les identifiants du fichier, menus ou items. Il sert notamment à déclarer les dépendances entre menus.
type	Obligatoire. Le type de menu, qui détermine notamment son emplacement dans la page. Les valeurs possibles sont : Paramètre Description htop pour un positionnement horizontal en haut de page, avant même l'en-tête de la page. htabs pour un positionnement sous l'en-tête de la page, sous la forme d'onglets à l'horizontal. vleft pour un menu de navigation vertical à gauche de la page.
depends	Optionnel. La dépendance du menu par rapport à un autre. Si un menu est dépendant d'un autre, il ne sera affiché que si le menu dont il est dépendant est lui-même actif. Le contenu de l'attribut est l'identifiant du menu dont il dépend. Si l'attribut n'est pas présent, il n'y a aucune dépendance (le menu est toujours affiché).
class	Optionnel. Permet de donner une classe particulière pour ajuster la mise en forme dans une feuille de style CSS. Dans le cas, d'un menu vertical (type vleft), si on donne la classe pl-accordion à un menu, celui-ci s'affichera sous la forme d'un accordéon, c'est-à-dire que l'on peut plier ou déplier ses sous-entrées. Fichier:Exemple/menu-accordéon.png
default	Optionnel. Avec la valeur true permet de préciser le menu à afficher par défaut. Remarques : Il ne doit être présent que sur un seul menu par type. Il est surtout utile pour les menus verticaux ; il peut y en avoir plusieurs car on peut associer à menu vertical à un onglet.

Élément <item>

La définition des attributs des items permet d'automatiser la création de plusieurs types de liens.

Pour ce qui est de son contenu, un item doit fournir une indication à l'utilisateur (un « texte ») et, dans la plupart des cas, un lien hypertexte.

La structure générale d'un item de menu est la suivante :

  <item
  id=""
  type=""
  href=""
  context=""
  title=""
  field=""
  reserve=""
  reserve-uri=""
  >
    Texte affiché du menu
  <item … />
  ⋮
  </item>

Un <item> peut contenir d'autres items, qui définissent ainsi des sous-menus, ou encore des items de niveau inférieur. La structure des éléments <item> est la même peu importe le niveau.

Le texte affiché pour l'item est celui que l'on trouve à l'intérieur de l'élément <item>. Dans le fichier par défaut de Pleade, ce texte utilise le mécanisme i18n de Cocoon, mais cela n'est pas obligatoire et n'est pas documenté ici. On peut également y insérer du simple texte.

Attributs de l'élément <item>

Ensuite, les informations qui définissent le comportement de l'item sont renseignées en attribut de l'élément item. Nous les définissons de la façon suivante :

Paramètre	Description
id	Obligatoire. L'identifiant de l'item. Il doit être unique parmi tous les identifiants du fichier, menus ou items.
type	Obligatoire. Le type d'item. Plusieurs valeurs sont possibles, et le contenu de l'attribut href sera interprété différemment selon le type d'item : Paramètre Description link-normal un lien normal, c'est-à-dire dont la cible sera affichée dans la même page que celle où se trouve l'item. link-ead un lien vers un document EAD, qui ouvrira la fenêtre de consultation d'un document EAD. L'attribut href doit alors contenir l'identifiant du document EAD. link-window un lien qui ouvrira une autre fenêtre de navigation dans le navigateur Internet. Si l'on souhaite que la fenêtre ait un nom spécifique dans le navigateur (ce nom n'est pas visible, mais cela permet d'éviter plusieurs fenêtre différentes), on peut renseigner ce nom après un « : » (deux-points), par exemple link-window:ext. txt un item qui n'est pas un lien, mais uniquement un texte affiché. grp un item qui contient uniquement d'autres items. S'il contient directement du texte, celui-ci sera ignoré. simple-search un formulaire de recherche simple sera inséré par Pleade à l'emplacement de cet item. Si ce type est utilisé, on peut ajouter quatre attributs à l'élément item : Paramètre Description action pour indiquer la page de résultats de recherche (par défaut results.html) ; method pour indiquer la méthode de soumission du formulaire (par défaut get) ; base pour indiquer la ou les base(s) de documents à rechercher (par défaut ead), séparées par un espace ; @field pour modifier le champ de recherche (par défaut fulltext). Fichier:Exemple/recherche-simple.png
href	Obligatoire, sauf pour les liens de type=txt ou type=simple-search. Indique l'adresse de la cible du lien représenté par cet item. Pour les items de type=link-window ou link-normal, href doit contenir l'adresse URL, qui peut être relative ou absolue (les protocoles supportés sont : http et mailto). Dans le cas d'adresse relative, on doit la renseigner par rapport à l'URL racine de l'application Pleade. Pour les items de type=link-ead, c'est l'identifiant du document EAD uniquement qui doit être renseigné dans cet attribut.
onclick	Optionnel. Cet attribut et son contenu sont reportés dans le HTML généré.
context	Optionnel. Le contexte où cet item est « actif », c'est-à-dire le patron d'URL qui, s'il est respecté par la page en cours d'affichage, rend l'item actif. Le patron est une expression régulière valide selon la norme XSLT<ref>Regular Expression Syntax XQuery 1.0 and XPath 2.0 Functions and Operators (Second Edition)</ref><ref>Definitive XML Schema, Chapter 10: Regular expressions</ref><ref>Regular Expression Matching in XSLT 2</ref>. Le contexte peut aussi être donné par l'attribut href, dans ce cas, il faut indiquer @href comme contexte. Par exemple, si le contexte est edit/.*, cela signifie que l'item sera actif lorsque la page affiché a une URL qui comme par edit/.
field	Optionnel et uniquement pour un item de type=simple-search. Précise le nom du champ de recherche pour la recherche simple, par défaut celui-ci est fulltext.
title	Optionnel, mais recommandé pour des raisons d'accessibilité et de facilité d'utilisation. Le texte qui sera affiché en bulle d'aide lorsque l'utilisateur passe la souris au-dessus du lien. Par défaut, le contenu de cet attribut est une clé i18n dont la valeur est définie dans un fichier de message. Cette méthode simplifie l'internationalisation de l'application. Mais ce n'est pas obligatoire, on peut y mettre le texte directement.
reserve	Optionnel. Cet attribut peut contenir un ou plusieurs rôles (séparés par une espace), et si c'est le cas l'item ne sera visible que si l'utilisateur est identifié et joue l'un de ces rôles. Important : Par défaut, c'est-à-dire si l'attribut n'est pas renseigné, l'item est visible par tous.
reserve-uri	Optionnel. Cet attribut peut contenir un ou plusieurs patrons d'URL (séparés par une espace), et si c'est le cas l'item ne sera visible que si l'URL demandée correspond à l'un des patrons. Important : Par défaut, c'est-à-dire si l'attribut n'est pas renseigné, l'item est visible pour toutes les URL.

Références

<references/>