Naviguer entre des vues

16 min

Vue d’ensemble

Cette page décrit la mécanique de navigation entre les vues dans un OAV sous un angle fonctionnel, en détaillant notamment les concepts suivants :

déclencher une transition depuis le composant d'une vue ;

passer des données utiles pour l'évaluation d'une transition ;

passer des données de contexte d'une vue à l'autre ;

exécuter une mécanique commune avant ou après l'évaluation d'une transition.

Déclencher une transition

Le hook useProcess retourne un objet processHandlers qui expose deux fonctions permettant de déclencher une transition depuis un composant d'une vue :

onNext() : affiche la vue suivante ;

onPrev() : affiche la vue précédente.

Exemple dans un composant

import { useProcess } from '@fasstech/oip-starter-utils/app';

const MyView = () => {
  const { processHandlers } = useProcess();

  const onPrev = () => processHandlers.onPrev();
  const onNext = () => processHandlers.onNext();

  return (
    <div>
      <button onClick={onPrev}>Go back</button>
      <button onClick={onNext}>Go next</button>
    </div>
  );
};

Dans cet exemple :

Le clic sur le bouton Go back déclenche la transition vers la vue précédente grâce à l'appel de l'handler onPrev ;

Le clic sur le bouton Go next déclenche quant à lui la transition vers la vue suivante grâce à l'appel de l'handler onNext.

Passer des données utiles pour l'évaluation d'une transition

Vous pouvez transmettre des données supplémentaires au moteur de transition qui seront utiles lors de l'évaluation de la transition en utilisant l'objet transitionData en paramètre des handlers onNext et onPrev.

Exemple dans un composant

const MyView = () => {
  const { processHandlers } = useProcess();

  const onNext = () => {
    processHandlers.onNext({ 
      transitionData: { foo: 'bar' },
    });
  };

  return (
    <button onClick={onNext}>Go next</button>
  );
};

Ces données sont alors accessibles dans l'objet reçu en paramètre par les handlers de transition définis dans config/views/transitions/<VIEW_ID>.mjs.

[info] Par défaut, le contexte reçu en paramètre d'un handler de transition ne contient que le champ projectId.

Exemple dans un fichier de transition

const next__NEXT_VIEW = (ctx) => {
  // ctx = { projectId: 'xxx', foo: 'bar' }

  // some logic
  if (ctx.foo !== 'bar') {
    return false;
  };
  
  return true;
};

const next__FALLBACK_VIEW = (ctx) => {
  return true;
};

export default {
  next: {
    transitions: [
      { viewId: 'NEXT_VIEW', handler: next__NEXT_VIEW },
      { viewId: 'FALLBACK_VIEW', handler: next__FALLBACK_VIEW }
    ]
  }
};

[info] Un handler de transition doit toujours retourner un booléen :• true : la transition est validée, la vue ciblée par viewId est alors affichée

• false : la transition n'est pas valide, le moteur teste la transition suivante disponible

Dans cet exemple, la propriété foo :

est définie dans l'objet transitionData lors de l'appel à l'handler onNext dans le composant de la vue ;

est accessible depuis le contexte de transition reçu en paramètre par les handlers next__NEXT_VIEW et next__FALLBACK_VIEW dans le fichier de transition de la vue ;

peut être utilisée dans le cadre d'une condition dans le corps des handlers pour valider ou rejeter la transition.

Passer des données de contexte d'une vue à l'autre

Toujours dans le cadre d'une transition, il est également possible de transmettre des données de contexte à la vue cible en utilisant l'objet resolvedViewData en paramètre des handlers onNext et onPrev depuis le code de la vue initiale.

Exemple dans le composant de la vue initiale

const MyView = () => {
  const { processHandlers } = useProcess();

  const onNext = () => {
    processHandlers.onNext({ 
      resolvedViewData: { something: 42 }, 
    });
  };

  return (
    <button onClick={onNext}>Go next</button>
  );
};

Dans cet exemple, la propriété something sera injectée au contexte de la vue cible résolue par le moteur de transition pour l'action next.

Exemple dans le composant de la vue cible

Dans le composant de la vue cible, something est alors accessible via la propriété viewData de l'objet context retourné par le hook useProcess.

const NextView = () => {
  const { context } = useProcess();

  // context.viewData = { something: 42 }

  return <div>...</div>;
};

Exécuter une mécanique globale avant ou après l'évaluation d'une transition

Il est possible d'exécuter une logique globale avant ou après le déclenchement d'une transition next ou prev pour une vue via les hooks before et after :

l'exécution de cette logique est commune et partagée à l'ensemble des transitions du même type (next ou prev) ;

cette logique n'est exécutée qu'une seule fois par type de transition :

avant l'évaluation de la transition - hook before ;

après l'évaluation de la transition - hook after.

La définition des hooks before ou after se fait également dans le fichier de transition de la vue concernée config/views/transitions/<VIEW_ID>.mjs.

Hook before

Signature : hooks.before = (ctx) => Promise<object>

Description :

Exécuté une seule fois avant l'évaluation de la transition ;

Reçoit en paramètre le contexte de la transition ;

L'objet retourné est injecté dans le contexte de transition, accessible depuis la propriété setup.

Hook after

Signature : hooks.after = (ctx) => Promise<void>

Description :

Exécuté une seule fois après la résolution de la transition ;

Reçoit en paramètre le contexte de la transition.

Exemple dans un fichier de transition

const next__NEXT_VIEW = (ctx) => {
  // ctx = { 
  //   projectId: 'xxx', 
  //   foo: 'bar',
  //   setup: { 
  //     someData: 'Le Guide du voyageur galactique' 
  //   }
  // }

  // some logic
  if (ctx.foo !== 'bar') {
    return false;
  };
  
  return true;
};

const next__FALLBACK_VIEW = (ctx) => {
  return true;
};

export default {
  next: {
    transitions: [
      { viewId: 'NEXT_VIEW', handler: next__NEXT_VIEW },
      { viewId: 'FALLBACK_VIEW', handler: next__FALLBACK_VIEW }
    ],
    hooks: {
      before: (ctx) => {
        // ctx = { 
        //   projectId: 'current-project-id', 
        //   foo: 'bar' 
        // }

        // some heavy processing once before
      
        return {
          someData: 'Le Guide du voyageur galactique'
        };
      },
      after: (ctx) => {
        // some heavy processing once after
      }
    }
  }
};

Dans cet exemple, la vue MY_VIEW possède pour ses transitions de type next, un hook before et un hook after ainsi que deux transitions possibles.

Le hook before retourne un objet qui contient une propriété someData.

setup.someData est alors accessible depuis le contexte de transition reçu en paramètre par les handlers next__NEXT_VIEW, next__FALLBACK_VIEW et par le hook after.

Explication complète du processus de transition de l'exemple

Déclenchement de la transition next depuis le code client de la vue MY_VIEW grâce à l'handler de transition onNext. foo est défini dans le contexte de la transition (via la propriété transitionData passée en paramètre) ;

Le moteur lit le fichier de transition relatif config/views/transitions/MY_VIEW.mjs ;

Le hook before est exécuté qu'une seule fois avant que le moteur ne commence à évaluer les transitions de type next disponibles. setup.someData est injecté dans le contexte de la transition ;

Le moteur évalue ensuite une à une les deux transitions de type next disponibles dans l'ordre de définition du tableau transitions. foo et setup.someData sont accessibles depuis le contexte de la transition reçu en paramètre par les handlers ;

La transition est résolue lorsque le premier des handlers retourne true. La vue cible est déterminée ;

pour finir, le hook after est exécuté qu'une seule fois après la résolution de la transition.

Résumé

onNext() / onPrev() déclenchent une transition depuis le code client d'une vue ;

transitionData → données destinées à enrichir le contexte de la transition ;

resolvedViewData → données injectées dans le contexte de la vue cible ;

Les transitions sont définies dans config/views/transitions/<VIEW_ID>.mjs ;

Un handler de transition doit toujours retourner true ou false ;

Les hooks before et after permettent d’exécuter une mécanique globale et partagée avant ou après l'évaluation complète d'une transition.