---
title: Naviguer entre les vues
slug: oip-next/v3/navigation-vue
icon: {"lucideIcon":"📘"}
createdAt: 2025-10-15T08:22:17.000Z
---

Vous pouvez trouver des informations complémentaires concernant les transitions dans la documentation de l'[OIP Core](#) et dans la documentation [ OIP par l'exemple](#)&#x20;

Les fichiers responsables de la logique de transition des vues se trouvent dans le dossier `viewsConfig`

:::CodeblockTabs
Tree

```none
viewsConfig/
├─ transitions-handlers/
│    ├─ altSummary.mjs
│    ├─ home.mjs
│    ├─ start.mjs
│    └─ summary.mjs
├─ 01_home.yml
├─ 02_start.yml
├─ 03_summary.yml
├─ 04_alt_summary.yml
├─ transitions.mjs
└─ workflow.mjs
```
:::

Le fichier `workflow.mjs` liste les identifiants des vues du projet et définit la première vue du parcours. Les identifiants des vues sont l'identifiant `viewId` déclaré dans le fichier de configuration de chacune des vues :

:::CodeblockTabs
workflow\.mjs

```javascript
export default {
  rootView: 'home',
  views: ['home', 'start', 'summary', 'altSummary']
};
```
:::

Le fichier `transitions.mjs` définit la liste de toutes les transitions possibles entre les vues du projet :

:::CodeblockTabs
transitions.mjs

```javascript
export default [
  {
    srcViewId: 'home',
    tgtViewId: 'start',
    action: 'next',
    conditionLabel: 'home_next',
    conditionOrder: 1
  },
  {
    srcViewId: 'start',
    tgtViewId: 'summary',
    action: 'next',
    conditionLabel: 'start_to_summary',
    conditionOrder: 1
  },
  {
    srcViewId: 'start',
    tgtViewId: 'altSummary',
    action: 'next',
    conditionLabel: 'start_to_altSummary',
    conditionOrder: 2
  },
  {
    srcViewId: 'start',
    tgtViewId: 'home',
    action: 'prev',
    conditionLabel: 'start_prev',
    conditionOrder: 1
  },
  {
    srcViewId: 'summary',
    tgtViewId: 'start',
    action: 'prev',
    conditionLabel: 'summary_prev',
    conditionOrder: 1
  },
  {
    srcViewId: 'altSummary',
    tgtViewId: 'start',
    action: 'prev',
    conditionLabel: 'altSummary_prev',
    conditionOrder: 1
  }
];
```
:::

Chaque élément de la liste définit une transition possible :

- `srcViewId` l'id de la vue source
- `tgtViewId` l'id de la vue ciblée par la transition
- `action` l'action de la transition, deux choix possibles `next` et `prev`
- `conditionLabel` définit le nom de l'handler de cette transition
- `conditionOrder` définit l'ordre d'éxecution de la transition

Il peut y avoir plusieurs transitions possibles pour une même vue source et pour une même action. Dans ce cas `conditionOrder` définit l'ordre d'évaluation de ces transitions.

# Logique de transition

La transition d’une vue à une autre est conditionnée par l’évaluation de la logique définie dans le **handler&#x20;**&#x61;ssocié à la transition.&#x20;

Si l’exécution du handler est un succès, alors la transition est déclenchée.
Dans le cas contraire, si le handler échoue, le moteur teste la transition suivante (s’il en existe une).
La transition suivante est identifiée par le **même&#x20;**`srcViewId`, la **même&#x20;**`action`, mais avec un `conditionOrder`**&#x20;incrémenté** (valeur `n + 1`).

Tant que l’exécution échoue, le moteur continue de tester les transitions suivantes dans l’ordre défini par `conditionOrder`.
Si **aucune des transitions disponibles ne réussit**, le moteur retourne une **erreur**.

Les fichiers contenant les handlers sont situés dans le dossier `viewsConfig/transitions-handlers`.
&#x20;Par convention, chaque fichier correspond à une vue et porte pour nom l’identifiant de cette vue.

**Exemple :** fichier du handler pour la vue `start` :

:::CodeblockTabs
start.mjs

```javascript
export default {
  start: {
    hooks: {
      beforeNext: () => {
        // add `message` to the context transition
        return {
          message: 'hello world!'
        };
      }
    },
    transitionConditions: {
      start_to_summary: (ctx) => {
        console.log(ctx.message); // => hello world!
        const customer = ctx?.customer;
        return customer && customer.firstName && customer.lastName;
      },
      start_to_altSummary: () => true,
      start_prev: () => true
    }
  }
};
```
:::

## Les hooks

L'objet `hooks` définit des logiques qui seront exécutées avant ou après l'évaluation des conditions de transition. Les hooks sont utiles pour exécuter des traitements asynchrones par exemple.

L’objet `hooks` permet de définir des logiques à exécuter **avant ou après** l’évaluation des conditions de transition.
Les hooks sont notamment utiles pour effectuer des **traitements asynchrones** (appels d’API, récupération de données, etc.).

### Hooks disponibles

Quatre hooks peuvent être définis :

- `beforeNext` → exécuté **avant chaque transition** dont l’action est `next`
- `afterNext` → exécuté **après chaque transition** dont l’action est `next`
- `beforePrev` → exécuté **avant chaque transition** dont l’action est `prev`
- `afterPrev` → exécuté **après chaque transition** dont l’action est `prev`

### Fonctionnement

Un hook est une **fonction** recevant en paramètre un objet `context`, représentant le contexte de la transition.
&#x20;Les hooks `beforeNext` et `beforePrev` peuvent **surcharger ce contexte** : les propriétés ajoutées seront ensuite accessibles dans les handlers des transitions concernées.

### Exemple

Dans l’exemple ci-dessous, un hook `beforeNext `est défini.
&#x20;Il ajoute une propriété `message` au contexte. Les handlers liés à une transition de type `next` recevront ce **contexte enrichi** en paramètre.

## Les handlers de transition

Signature d'un handler de transition : `(ctx) => boolean`

L'objet `transitionConditions` d'un fichier handler d'une vue définit les handlers de transition de la vue. Les propriétés de cet objet sont les valeurs des propriétés `conditionLabel` définies depuis le fichier `transitions.mjs`

Un handler est une fonction qui peut reçevoir en paramètre un objet context qui représente le context de la transition.

La fonction doit impérativement retourner un booléen. Si *true* est retourné alors le moteur valide la transition, si *false* est retourné alors la transition suivante est évaluée.

## Contexte de transition

L'objet `context` reçu en paramètre d'un handler de transition est par défaut de la forme :

```none
{
  projectId
  setup
  ...dataFromView
}
```

- `projectId` contient l'id de l'entité Project en cours
- `setup` contient les champs ajoutés au contexte depuis les hooks `beforeNext` et `beforePrev` ou est `undefined` si le contexte n'est pas surchargé
- les informations passées depuis une vue (via les handlers de transition de `processHandlers`) sont ajoutées et accessibles depuis la racine de l'objet context

# Déclencher une transition depuis une vue

Le hook client `useProcess` qui peut être importé dans les composants des vues depuis la dépendance `@fasstech/oip-starter-utils` retourne en réponse un objet dont la propriété `processHandlers` expose des méthodes relatives à la logique de transition :

:::CodeblockTabs
Home.jsx

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

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

  // processHandlers.onAction
  // processHandlers.onNext
  // processHandlers.onPrev
  
  return (
    <div className="t-home">
      ...
    </div>
  );
}

export default Home;
```
:::

- `onAction` permet de déclencher une transition

Prend un objet en paramètre de type `{ action: 'NEXT'|'PREV', context: any }`

- `onNext` permet de déclencher la transition vers la vue suivante

Prend un objet en paramètre de type `{ context: any }`

- `onPrev` permet de déclencher la transition vers la vue précédente

Prend un objet en paramètre de type `{ context: any }`

Lors de l'appel à une de ces méthodes, les informations de l'objet context passé en paramètre sont reçu par les hooks ainsi que par les handlers relatifs à la transition ciblée. Ce paramètre est optionnel.

Se référer au chapitre [Process handlers](https://doc.fasst.tech/oip-project-starter/process-handlers#2JaHn) pour la documentation complète des handlers de transition exposés par le hook `useProcess`

# Passer de la metadata lors d'une transition

La gestion de metadata lors des transitions est disponible à partir de la version 3.5.0 de l'OIP Core combinée à une version de l'OIP Starter Utils >= 3.0.4

Il est possible de passer un objet `metadata` lors du déclenchement d'une transition depuis une vue. **Cette metadata sera alors accessible depuis le contexte des composants ou depuis le contexte des resolvers de la vue suivante, cf.&#x20;**[Process](https://doc.fasst.tech/oip-project-starter/process)

Pour se faire il vous suffit de définir un objet `metadata` dans l'objet `context` passé en paramètre aux méthodes de transitions depuis le composant d'une vue :

:::CodeblockTabs
Demo.jsx

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

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

  const onNext = () => {
    processHandlers.onNext({
      // transition context
      context: {
        logic: true,
        // metadata definition
        metadata: {
          someId: 'azerty'
        }
      } 
    });
  };

  return (
    <div>
      <h2>DEMO</h2>

      <button onClick={onNext}>NEXT</button>
    </div>
  );
};

export default Demo;
```
:::

# Explication de la logique depuis la vue start

Explication complète de la logique de transition conditionnelle pour l'action `next` depuis la vue `start` :

1. &#x20;La transition `next` est déclenchée depuis le composant `views/start/client/Start.jsx` grâce à la méthode `onNext` exposée par la propriété `processHandlers` reçu en réponse du hook `useProcess`

:::CodeblockTabs
Start.jsx

```javascript
import { useProcess } from '@fasstech/oip-starter-utils/app';
import useGetCustomerQuery from './hooks/useGetCustomerQuery.js';

const Start = () => {
  const { processHandlers } = useProcess();
  
  const { 
    getCustomer, 
    loading: isLoadingGetCustomer, 
    refetch 
  } = useGetCustomerQuery();

  const $onNext = () => {
    processHandlers.onNext({
      context: {
        customer: getCustomer
      }
    });
  };
  
  ...
  
  return (
    <div className="t-home">
      ...

      <button className="f-button ml-2" onClick={$onNext}>NEXT</button>
    </div>
  );
}

export default Start;
```
:::

2. &#x20;L'objet context passé en paramètre à la méthode `onNext` contient l'entité `customer`
3. Deux transitions sont possibles pour l'action `next` depuis la vue `start`. Ces transitions sont définies comme suit dans le fichier `transitions.mjs` :

:::CodeblockTabs
transitions.mjs

```javascript
export default [
  ...
  {
    srcViewId: 'start',
    tgtViewId: 'summary',
    action: 'next',
    conditionLabel: 'start_to_summary',
    conditionOrder: 1
  },
  {
    srcViewId: 'start',
    tgtViewId: 'altSummary',
    action: 'next',
    conditionLabel: 'start_to_altSummary',
    conditionOrder: 2
  },
  ...
];
```
:::

- transition ***start -> summary*** - ordre d'évaluation 1
- transition ***start -> altSummary*** - ordre d'évaluation 2

4. &#x20;Lors de l'évaluation de la transition `next` depuis la vue `start` le moteur de transition va d'abord évaluer la première transition possible ***start -> summary***
5. &#x20;Le hook `beforeNext` comme défini dans le fichier `transitions-handlers/start.mjs` est d'abord exécuté. Le context de transition est alors surchargé par l'ajout de la propriété `message`

:::CodeblockTabs
start.mjs

```javascript
export default {
  start: {
    hooks: {
      beforeNext: () => {
        return {
          message: 'hello world!'
        };
      }
    },
    transitionConditions: {
      start_to_summary: (ctx) => {
        console.log(ctx.setup.message); // => hello world!
        const customer = ctx?.customer;
        return customer && customer.firstName && customer.lastName;
      },
      start_to_altSummary: () => true,
      start_prev: () => true
    }
  }
};
```
:::

6. &#x20;Ensuite l'handler de la transition nommé `start_to_summary` comme défini en valeur de la propriété `conditionLabel` dans le fichier `transitions.mjs` est exécuté.&#x20;

La logique de l'handler est définie dans le fichier des handlers de la vue `start` (comme ci-dessus) depuis la propriété `transitionConditions.start_to_summary`.&#x20;

La fonction associée reçoit en paramètre l'entité `customer` définie depuis l'objet `ctx`

7. &#x20;Si l'entité `customer` est correctement définie alors l'évaluation est un succès. *true* est retourné par la fonction. Le moteur valide la transition vers la vue `summary` comme défini dans le fichier `transitions.mjs` propriété `tgtViewId` de la transition relative

***start -> summary***

8. &#x20;Si l'entité `customer` n'est pas complète alors l'évaluation échoue. *false* est retourné par la fonction. Le moteur évalue alors la transition suivante dans l'ordre défini par `conditionOrder`

Dans notre exemple la transition suivante à évaluer est donc ***start -> altSummary***

:::CodeblockTabs
transitions.mjs

```javascript
export default [
  ...
  {
    srcViewId: 'start',
    tgtViewId: 'altSummary',
    action: 'next',
    conditionLabel: 'start_to_altSummary',
    conditionOrder: 2
  },
  ...
];
```
:::

9. &#x20;Le moteur évalue alors l'handler `start_to_altSummary`. Cet handler réussit à chaque fois puisqu'il retourne toujours *true*. Le moteur valide la transition vers la vue `altSummary`

***start -> altSummary***

# Lors de l'ajout d'une vue

Lors de l'ajout d'une vue il vous faut éditer / ajouter les différents fichiers relatifs aux transitions :

1. &#x20;éditer le fichier `workflow.mjs` et ajouter l'identifiant de la nouvelle vue à la liste `views`
2. &#x20;éditer le fichier `transitions.mjs` et ajouter les transitions relatives à la nouvelle vue
3. &#x20;ajouter le fichier des handlers de la nouvelle vue dans le dossier `transitions-handlers`

# Choix conditionnel de la 1ère vue du parcours

Cette fonctionnalité est disponible à partir de la version 3.4.0 de la dépendance OIP Starter Utils.

Cette fonctionnalité vous permet également de définir la vue souhaitée en fonction de la dernière vue active d'un projet lors d'une reprise du parcours.

Par défaut, le parcours démarre par la vue `rootView` définie dans le fichier `viewsConfig/workflow.mjs` sans configuration supplémentaire.

Mais vous pouvez également choisir de démarrer votre parcours par une vue différente en fonction de la valeur d'une propriété d'une entitié par exemple.

Pour ce faire, vous pouvez passer une callback `resolveFirstView` en paramètre de la méthode `startServer` du fichier `server/index.mjs`, ex. :

:::CodeblockTabs
server/index.mjs

```javascript
import { start as startServer } from '@fasstech/oip-starter-utils/server';
import { resolveFirstView } from './resolve-first-view.mjs';

const config = {
  // ...
  resolveFirstView,
};

const { app } = await startServer(config);
```

resolve-first-view\.mjs

```javascript
import { Entities } from '@fasstech/oip-core';

export const resolveFirstView = async (projectId, process) => {
  // pour gérer la reprise du parcours
  if (process) {
    return process.viewId; // ou autre viewId
  }
  
  // récupération de l'entité Project
  const project = await Entities('Project').get({ id: projectId });
  
  // votre logique
  
  return 'my-desired-view-id';
};
```
:::

La callback `resolveFirstView` est exécutée par le server à la suite de l'initialisation de l'entité *Project*. Par conséquent, vous pouvez accéder à l'entité *Project* dans le corps de la callback.

La callback `resolveFirstView` est appelée avec les paramètres suivants :

- en 1er paramètre, l'identifiant de l'entité *Project* actuelle est reçu
- en 2ème paramètre, un objet `{ viewId, metadata }` ou `null` est reçu. Cet objet correspond au *process* existant si il existe. Par exemple dans le cas de la reprise d'un projet existant, `viewId` contiendra l'identifiant de la dernière vue active du parcours lié à l'entité *Project* actuelle (identifiée par le 1er paramètre)

**La callback doit toujours retourner l'identifiant d'une vue peu importe vos conditions.**

# Initialiser les transitions

### Fichier `viewsConfig/workflow.mjs`

Le fichier `viewsConfig/workflow.mjs` contient deux informations :

1. L'identifiant de la première vue de l'OAV.
2. La liste des identifiants de l'ensemble des vues.

```javascript
export default {
  rootView: 'home',
  views: ['home', 'summary']
};
```

### Fichier `viewsConfig/transitions.mjs`

Le fichier `viewsConfig/transitions.mjs` contient les transitions entre toutes les vues de l'OAV.

```javascript
export default [
  {
    srcViewId: 'home',
    tgtViewId: 'summary',
    action: 'next',
    conditionOrder: 1
  },
  {
    srcViewId: 'summary',
    tgtViewId: 'home',
    action: 'prev',
    conditionOrder: 1
  }
];
```

***

# Déclarer une transition conditionnelle

Une transition est conditionnelle si elle a la propriété `conditionLabel`.

Déclaration d'une transition conditionnelle `Company => Grantee`.

### Fichier `viewsConfig/transitions.mjs`

```javascript
export default [
  {
    srcViewId: 'home',
    tgtViewId: 'company',
    action: 'next',
    conditionOrder: 1
  },
  {
    srcViewId: 'company',
    tgtViewId: 'home',
    action: 'prev',
    conditionOrder: 1
  },
  {
    srcViewId: 'company',
    tgtViewId: 'grantee',
    action: 'next',
    conditionOrder: 1,
    conditionLabel: 'company_next_grantee'
  },
  {
    srcViewId: 'company',
    tgtViewId: 'summary',
    action: 'next',
    conditionOrder: 2
  },
  {
    srcViewId: 'grantee',
    tgtViewId: 'company',
    action: 'prev',
    conditionOrder: 1
  },
  {
    srcViewId: 'grantee',
    tgtViewId: 'summary',
    action: 'next',
    conditionOrder: 1
  },
  {
    srcViewId: 'summary',
    tgtViewId: 'grantee',
    action: 'prev',
    conditionOrder: 1
  }
];
```

### Fichier `viewsConfig/transitions-handlers/company.mjs`

```javascript
export default {
  company: {
    hooks: {},
    transitionConditions: {
      company_next_grantee: (ctx) => ctx.form.isActive
    }
  }
};
```

***

# Utiliser les hooks

Les *hooks* disponibles sont au nombre de quatre : `beforeNext`, `beforePrev`, `afterNext`, `afterPrev`.

```javascript
export default {
  company: {
    hooks: {
      beforeNext: (ctx) => {
        // Récupération de données
        // pour les mettre à disposition de tous les handlers
        return foo(ctx);
      }
    },
    transitionConditions: {
      company_next_grantee: (ctx) => {
        // `ctx.setup` contient la valeur de retour de `foo(ctx)`
      }
    }
  }
};
```
