Fils d’Ariane

Les fils d’Ariane sont un modèle d’interface utilisateur qui aide les utilisateurs à comprendre leur emplacement actuel dans un site web ou une application. Ils fournissent une aide à la navigation sous forme de piste hiérarchique de liens depuis la page d’accueil jusqu’à la page actuelle. Les fils d’Ariane sont généralement affichés horizontalement près du haut de la page et utilisent des séparateurs, souvent des chevrons, pour indiquer la hiérarchie.

Dans OpenMRS, les fils d’Ariane sont implémentés dans le fichier index.ts au moyen des fonctions registerBreadcrumb ou registerBreadcrumbs exportées par le paquet @openmrs/esm-framework.

La fonction registerBreadcrumb prend un objet avec les propriétés suivantes:

path (obligatoire): le chemin URL de la page
title (obligatoire): le texte affiché dans le fil d’Ariane. Il peut s’agir d’une chaîne, d’une fonction qui retourne une chaîne ou d’une fonction qui retourne une Promise résolue en chaîne. Les fonctions reçoivent les paramètres de route comme argument.
parent (facultatif): le chemin du fil d’Ariane parent, utilisé pour créer une piste hiérarchique
matcher (facultatif): une chaîne ou une RegExp qui détermine si le fil d’Ariane doit être affiché. Si omis, la valeur de path est utilisée comme matcher. C’est utile pour les routes dynamiques avec paramètres, par exemple /patient/:patientUuid.

Quand un utilisateur navigue vers une page enregistrée, le registre de fils d’Ariane peut résoudre la piste appropriée selon le chemin courant. L’enregistrement des fils d’Ariane ne stocke que les données; une page ou une mise en page doit quand même rendre l’interface.

Voici un exemple de fil d’Ariane simple pour une page (Core v5+):


import { registerBreadcrumb } from "@openmrs/esm-framework";
 
export function startupApp() {
  registerBreadcrumb({
    path: `${window.spaBase}/myPage`,
    title: "My First Page",
  });
}

Quand un utilisateur navigue vers le chemin SPA ${window.spaBase}/myPage, par exemple /openmrs/spa/myPage, le fil d’Ariane affiche: My First Page

Les fils d’Ariane peuvent aussi représenter une piste de liens hiérarchiques depuis la page d’accueil du site vers des sous-pages. Pour l’implémenter, utilisez la propriété parent pour indiquer quel fil d’Ariane doit être le parent.

Voici un exemple de fils d’Ariane avec ancêtres et sous-pages (Core v5+):


import { registerBreadcrumbs } from "@openmrs/esm-framework";
 
export function startupApp() {
  registerBreadcrumbs([
    {
      path: `${window.spaBase}/myPage`,
      title: "My First Page",
    },
    {
      path: `${window.spaBase}/myPage/subpage1`,
      title: "Subpage 1",
      parent: `${window.spaBase}/myPage`,
    },
    {
      path: `${window.spaBase}/myPage/subpage2`,
      title: "Subpage 2",
      parent: `${window.spaBase}/myPage`,
    },
  ]);
}

Quand un utilisateur navigue vers différentes pages, les fils d’Ariane affichent:

Sur ${window.spaBase}/myPage: My First Page
Sur ${window.spaBase}/myPage/subpage1: My First Page > Subpage 1
Sur ${window.spaBase}/myPage/subpage2: My First Page > Subpage 2

Fils d’Ariane dynamiques avec paramètres de route

Vous pouvez créer des fils d’Ariane dynamiques qui utilisent les paramètres de route. La fonction title reçoit un tableau des paramètres de route correspondants. Par exemple, pour afficher l’UUID d’un patient dans le fil d’Ariane:


import { registerBreadcrumb } from "@openmrs/esm-framework";
 
export function startupApp() {
  registerBreadcrumb({
    path: `${window.spaBase}/patient/:patientUuid`,
    matcher: `${window.spaBase}/patient/:patientUuid`, // Facultatif: définit explicitement le matcher
    title: (params) => {
      // params est un tableau des paramètres de route correspondants
      // Pour un chemin comme /openmrs/spa/patient/<uuid>, params[0] est la valeur patientUuid
      return `Patient ${params[0]}`;
    },
    parent: `${window.spaBase}/patients`,
  });
}

Pour des scénarios plus complexes, vous pouvez récupérer des données de façon asynchrone:


import { registerBreadcrumb } from "@openmrs/esm-framework";
 
export function startupApp() {
  registerBreadcrumb({
    path: `${window.spaBase}/patient/:patientUuid`,
    title: async (params) => {
      const patientUuid = params[0];
      // Récupérer les données patient et retourner son nom
      const patient = await fetchPatient(patientUuid);
      return patient.name;
    },
    parent: `${window.spaBase}/patients`,
  });
}

Rendre les fils d’Ariane

registerBreadcrumb et registerBreadcrumbs enregistrent uniquement les données des fils d’Ariane. L’app shell actuel ne monte pas automatiquement les fils d’Ariane et n’enregistre pas d’extension core pour breadcrumbs-slot par défaut. Si une page rend un slot de fils d’Ariane partagé, ce slot n’affiche du contenu que si la distribution ou le module propriétaire de la mise en page lui assigne une extension de rendu des fils d’Ariane.


import { ExtensionSlot } from "@openmrs/esm-framework";
 
export default function MyPage() {
  return (
    <>
      <ExtensionSlot name="breadcrumbs-slot" />
      {/* Le contenu de votre page */}
    </>
  );
}

Si vous créez une nouvelle mise en page, vérifiez qu’un élément de la distro fournit réellement l’extension de fil d’Ariane pour breadcrumbs-slot; sinon le slot ne rendra rien.

Pour les mises en page personnalisées, utilisez getBreadcrumbsFor(path) depuis @openmrs/esm-framework pour lire la piste enregistrée et la rendre avec la bibliothèque d’interface utilisée par cette mise en page.

Comportement des fils d’Ariane

Les données de fils d’Ariane peuvent être filtrées selon le chemin courant avec getBreadcrumbsFor(path) ou filterBreadcrumbs(list, path).
La piste suit la hiérarchie des parents et affiche tous les ancêtres jusqu’à la page courante.
Le renderer de fils d’Ariane de l’app shell replie les pistes de plus de 4 éléments en remplaçant les entrées du milieu par ”…”.
Le renderer de fils d’Ariane de l’app shell affiche un indicateur de chargement pendant la résolution des titres fournis par fonction.
Les fils d’Ariane rendus sont des liens cliquables qui naviguent vers leurs chemins respectifs.