Skip to main content

Aide contextuelle des modules

Le paquet commun @openent/context-help fournit un client JavaScript, un composant HTML openent-context-help et un adaptateur React 18/19. Sa source se trouve dans le dépôt openent-frontend-framework, sous packages/context-help.

Le premier périmètre couvre les fonctions collectivité et les actions groupées du Dashboard, ainsi que le dépôt de documents dans Rack. Le panneau est ouvert à la demande, en français. Il ne lance aucune action métier et ne modifie pas les droits de l'utilisateur.

Définir une aide dans Docusaurus​

Ajouter une entrée dans le front matter de la page qui décrit la fonctionnalité :

contextual_help:
  - id: module.action
    title: Titre court
    summary: Explication de l'action
    anchor: section-de-la-page
    steps:
      - Première étape
      - Deuxième étape

L'identifiant est stable et indépendant du libellé du bouton. Le plugin context-help génère help/fr.json avec les liens réels des pages Docusaurus. Il refuse les identifiants dupliqués et les entrées incomplètes. Ne pas y mettre de données de compte ou d'établissement.

Intégrer le composant​

import { ContextHelp } from '@openent/context-help/react';

<ContextHelp
  helpId="module.action"
  catalogueUrl="/dashboard/api/documentation?format=catalogue"
  docUrl={`${window.location.origin}/dashboard/api/documentation?helpId=module.action`}
  label="Aide sur cette action"
/>

Dans une application avec rendu serveur, construire l'URL absolue après hydratation ; avant cela, rendre un lien relatif vers le résolveur (voir les composants ContextHelp du Dashboard et de Rack). L'identifiant doit exister dans le catalogue du Dashboard.

Le paramètre facultatif context affiche un texte local, par exemple le nombre d'établissements sélectionnés. Il n'est pas envoyé au serveur documentaire. Placer le composant à côté du bouton, jamais à l'intérieur d'un autre bouton ou d'un élément de menu interactif.

Sans React, importer registerContextHelp() et utiliser l'élément HTML du même nom avec les attributs help-id, catalogue-url, doc-url et label. Prévoir un lien enfant vers la documentation : il reste utilisable avant le chargement du composant.

Catalogue et distribution du premier essai​

Le Dashboard expose le catalogue commun par /dashboard/api/documentation?format=catalogue. Rack et le Dashboard utilisent cette adresse sur le même domaine ENT, sans CORS. La copie embarquée dans chaque application conserve les titres et les types. Après modification des résumés, étapes ou identifiants :

yarn --cwd docs build
node docs/scripts/sync-context-help.cjs --rack ../open-ent-mods/modules/rack

Reconstruire les applications pour publier leurs nouveaux catalogues. Les anciennes variables NEXT_PUBLIC_HELP_CATALOGUE_URL et VITE_HELP_CATALOGUE_URL ne sont plus utilisées par ces deux intégrations : la localisation du site se règle maintenant côté serveur, au runtime.

Le paquet est publié sur GitHub Packages sous le nom @open-ent/context-help. Rack utilise l'alias npm versionné "@openent/context-help": "npm:@open-ent/context-help@0.1.0", ce qui conserve les imports existants sans archive locale. Ses fichiers .npmrc configurent déjà le scope @open-ent. L'installation requiert NODE_AUTH_TOKEN avec accès en lecture aux packages ; sa CI utilise OPENENT_PACKAGES_TOKEN. Le Dashboard conserve pour l'instant son archive du premier essai : sa migration vers le registre reste distincte.

Changer de site sans reconstruire les applications​

Les liens du Dashboard (connexion, activation, menus, administration et page Documentation) et ceux des panneaux d'aide passent par un résolveur public en lecture seule :

  • /dashboard/api/documentation?kind=functional : documentation fonctionnelle ;
  • /dashboard/api/documentation?kind=technical : documentation technique ;
  • /dashboard/api/documentation?helpId=rack.deposer-document : page contextuelle.

Le préfixe du Dashboard suit NEXT_PUBLIC_BASE_PATH (vide pour un déploiement à la racine). L'intégration Rack cible le déploiement standard /dashboard ; pour un autre préfixe, exposer également cet alias via le reverse proxy. Le Dashboard doit être déployé sur le même ENT que Rack pour fournir ce service partagé.

Une première livraison des applications et du chart est nécessaire pour installer ce mécanisme. Les changements de site ultérieurs ne nécessitent aucun build. Le serveur répond par une redirection temporaire 307, avec Cache-Control: no-store. Même un catalogue déjà en cache pointe vers le résolveur : le prochain clic prend donc la nouvelle destination.

Avec Helm​

Configurer dashboard.documentation dans open-ent-mods/helm/openent-monolithe/values.yaml :

dashboard:
  documentation:
    technicalBaseUrl: https://documentation.exemple.fr/technique/
    functionalBaseUrl: https://documentation.exemple.fr/utilisateurs/
    entries:
      rack.deposer-document: https://documentation.exemple.fr/guides/casier#depot

Le chart crée le ConfigMap <fullname>-documentation, monté dans /etc/openent/documentation/ sans subPath. Le fichier config.json est relu à chaque clic. Mettre à jour ces valeurs via le processus Helm habituel ou modifier ce ConfigMap pour une bascule immédiate d'exploitation, puis reporter le changement dans les valeurs Helm pour le conserver au prochain déploiement.

Aucun redémarrage du Dashboard n'est nécessaire : attendre la propagation du volume ConfigMap par Kubernetes. Il n'y a pas de checksum documentaire dans le template du pod. Une mise à jour limitée à ces valeurs ne change pas le Deployment.

Les URLs de base conservent les chemins des pages et leurs ancres. Si le nouveau site a une autre arborescence, entries permet de remplacer l'URL complète pour chaque identifiant. Seules les URLs HTTP(S) sans identifiants de connexion sont acceptées. Les bases ne doivent pas contenir de paramètres de requête ni d'ancre.

Hors Helm​

Monter un fichier JSON lisible par le processus Next.js :

{
  "technicalBaseUrl": "https://documentation.exemple.fr/technique/",
  "functionalBaseUrl": "https://documentation.exemple.fr/utilisateurs/",
  "entries": {}
}

Définir OPENENT_DOCUMENTATION_CONFIG_FILE sur son chemin absolu au démarrage. Remplacer ensuite le fichier atomiquement pour changer les destinations à chaud. Monter le répertoire dans Docker si le remplacement s'effectue par renommage.

Sans fichier, les variables serveur OPENENT_DOCUMENTATION_TECHNICAL_URL et OPENENT_DOCUMENTATION_FUNCTIONAL_URL permettent une configuration sans rebuild mais avec redémarrage du processus lors d'un changement. Les clés du fichier sont prioritaires. Ne pas utiliser de variable NEXT_PUBLIC_* pour les adresses documentaires.

Sans configuration, les sites historiques https://doc.tech.fr/open-ent-dev/ et https://doc.tech.fr/open-ent-documentation/ restent les valeurs par défaut. Un fichier configuré mais illisible ou invalide donne une erreur 503 sans cache ; une aide inconnue, une erreur 404. La configuration ne doit contenir aucun secret.

Vérifier une bascule​

curl -sSI 'https://ent.exemple.fr/dashboard/api/documentation?helpId=rack.deposer-document'

Contrôler Location, modifier la configuration, puis répéter : l'URL et son ancre doivent pointer vers le nouveau site, sans recompilation ni redémarrage. Les tests automatisés couvrent aussi deux lectures successives d'un même fichier modifié à chaud.

Comportement vérifié​

  • Chargement à l'ouverture, cache de cinq minutes et délai d'attente maximal de cinq secondes.
  • Lien vers la documentation conservé si le chargement échoue.
  • Contenus affichés en texte, sans interpréter de HTML provenant du catalogue.
  • Ouverture au clavier, fermeture avec Échap et restitution du focus au bouton.
  • Panneau latéral sur ordinateur et pleine largeur sur petit écran.

Les interfaces qui imposent leur propre piège de focus dans une fenêtre modale demandent une adaptation avant d'y placer ce composant. Les trois intégrations initiales sont hors de ces fenêtres.