---
title: Configurer des vues
slug: oip-next/Zdxx-configurer
icon: {"lucideIcon":"📘"}
createdAt: 2025-10-17T15:41:01.000Z
---

# Vue d'ensemble

La configuration des vues d’un OAV repose sur :

- des fichiers YAML décrivant chaque vue ;
- des fichiers de transitions définissant la navigation entre les vues ;
- une commande `views:gen` générant le code client et serveur de chacune des vues.

# Définition des vues

## Emplacement

Les fichiers de définition des vues doivent être créés dans le dossier `config/views`.

## Structure

Chaque vue est associée à un fichier de configuration YAML qui contient les propriétés suivantes :

- `viewId` : identifiant unique de la vue ;
- `pathname` : chemin de la vue dans l’URL ;
- `directory` : nom du dossier dans lequel générer le code de la vue ;
- `graphql` : définition des *queries* et *mutations* GraphQL utilisées par la vue.

:::BlockQuote
**\[info]** Par convention, le nom du fichier est l'identifiant unique de la vue. Par exemple, pour une vue `start` le nom de son fichier de configuration est `start.yml`.
:::

## Exemple complet d'un fichier de configuration

```yaml
start:
  viewId: start
  pathname: /start
  directory: start
  graphql:
    queries:
      - type: Customer
        fields:
          firstName: String
          lastName: String
        resolver: getCustomer
    mutations:
      - type: Customer
        inputs:
          firstName: String
          lastName: String
        resolver: createCustomer
```

## Définition des queries GraphQL

La clé `queries` de l’objet `graphql` définit les **queries GraphQL** utilisées par la vue.

```yaml
graphql:
  queries:
    - type: Customer        # Type de la réponse de la query
      fields:               # Propriétés à retourner : nom + type
        firstName: String
        lastName: String
      resolver: getCustomer # Nom de la fonction resolver côté serveur
```

- `type` : nom du type de la réponse GraphQL ;
- `fields` : liste des champs attendus en réponse ;
- `resolver` : nom de la fonction qui résout la query côté serveur.

## Définition des mutations GraphQL

La clé `mutations` de l’objet `graphql` définit les **mutations GraphQL** utilisées par la vue.

```yaml
mutations:
  - type: Customer           # Type de la réponse de la mutation
    resolver: createCustomer # Fonction permettant d'exécuter la mutation
    inputs:                  # Arguments de la mutation : nom + type
      firstName: String
      lastName: String
```

- `type` : nom du type de la réponse GraphQL ;
- `resolver` : nom de la fonction qui résout la mutation côté serveur ;
- `inputs` : paramètres attendus par le resolver.

***

# Définition des transitions

## Emplacement

Les fichiers de définition des transitions doivent être créés dans le dossier `config/views/transitions`.

## Structure d’un fichier de transition

Chaque vue est associée à un fichier de transition.&#x20;

:::BlockQuote
**\[info]** Par convention, le nom du fichier de transition doit correspondre à la valeur de `viewId`. Par exemple, pour une vue `DONNEES_CONTRAT`, le fichier de transition est `config/views/transitions/DONNEES_CONTRAT.mjs`.
:::

Le fichier de transition exporte un objet qui contient au moins l’une des propriétés suivantes :

- `next` : définit **les vues « suivantes »** possibles lors d'une action **next**
- `prev` : définit **les vues « précédentes »** possibles lors d'une action **prev**

`next` et `prev` sont de type objet avec :

- `transitions` : propriété **obligatoire** qui définit chaque transition possible
- `hooks` : propriété **optionnelle** qui définit les *hooks* de transition `before` et `after`

### Propriété `transitions`

`transitions` est une **liste ordonnée** définissant les vues accessibles depuis la vue courante lors d'une action *next* ou *prev*.

Chaque élément de la liste est un objet qui contient :

- `viewId` : identifiant de la vue cible ;
- `handler` : fonction qui contient la logique d'évaluation de la transition. Elle doit retourner impérativement `true` ou `false`.

Pour déterminer la vue suivante (ou précédente) :

1. Le fichier de transitions de la vue courante est lu.
2. Les handlers définis dans `next.transitions` (ou `prev.transitions`) sont évalués **dans l’ordre**.
3. La première fonction qui retourne `true` détermine la vue cible via son `viewId`.

### Propriété `hooks` (optionnelle)

`hooks` est un objet regroupant des fonctions pouvant être appelées :

- **avant** l’évaluation des conditions (`before`) ;
- **après** l’évaluation des conditions (`after`).

Ces hooks permettent par exemple :

- de charger une seule fois des données utilisées dans plusieurs conditions ;
- d’exécuter des opérations de nettoyage après la résolution de la transition.

## Exemple d'un fichier de transition

:::CodeblockTabs
CHOIX\_GAMME.mjs

```javascript
const prev__DONNEES_CONTRAT = () => {
  return true;
};

export default {
  prev: {
    transitions: [
      { viewId: 'DONNEES_CONTRAT', handler: prev__DONNEES_CONTRAT }
    ]
  }
};
```
:::

Dans cet exemple :

- une seule transition **précédente** est définie ;
- elle cible la vue `DONNEES_CONTRAT` ;
- la transition est toujours autorisée car le handler retourne toujours `true`.

***

# Génération du code des vues et des transitions

La commande `views:gen` lit les fichiers YAML présents dans le dossier `config/views` pour :

- vérifier que chaque vue possède un fichier de transition associé ;
- vérifier que chaque transition est valide ;
- générer le fichier `views/views.mjs`, utilisé en interne pour la navigation entre les vues ;
- générer le code client et serveur de chaque vue.

```shell
npm run views:gen
```

## Fichiers générés d'une vue

Considérons le fichier de configuration suivant pour une vue `home` :

:::CodeblockTabs
home.yml

```yaml
home:
  viewId: home
  pathname: /
  directory: home
  graphql:
    queries:
      - type: Customer
        fields:
          firstName: String
          lastName: String
        resolver: getCustomer
    mutations:
      - type: Customer
        inputs:
          firstName: String
          lastName: String
        resolver: createCustomer
```
:::

Après exécution de la commande `npm run views:gen` l’arborescence générée est la suivante :

```text
views/home/
├─ client/
│   ├─ graphql/
│   │   ├─ mutations/
│   │   │   └─ CreateCustomerMutation.js
│   │   └─ queries/
│   │       └─ GetCustomerQuery.js
│   ├─ hooks/
│   │   ├─ useCreateCustomerMutation.js
│   │   └─ useGetCustomerQuery.js
│   ├─ Home.inte.test.jsx
│   └─ Home.jsx
└─ server/
    └─ graphql/
        ├─ resolver/
        │   ├─ createCustomer.mjs
        │   ├─ createCustomer.test.js
        │   ├─ getCustomer.mjs
        │   ├─ getCustomer.test.js
        │   └─ index.mjs
        └─ type/
            ├─ MutationType.mjs
            ├─ QueryType.mjs
            └─ queryTypeResolvers.mjs
```

Une vue est donc composée d'une partie **serveur** et **client**.

:::BlockQuote
**\[warning]** Certains fichiers générés ne doivent pas être édités. Ils possèdent l'en-tête suivant \:WARNING : fichier généré par cli, ne pas le modifier directement
:::

## Partie serveur

Deux dossiers principaux sont générés pour la partie serveur :

- `graphql/resolver` : contient deux fichiers squelettes pour chaque resolver déclaré dans le fichier de configuration :
  - un fichier pour la fonction `resolver` ;
  - un fichier de test associé.

:::BlockQuote
**\[info]&#x20;**&#x56;ous devez éditer ces fichiers pour implémenter votre logique et les rendre fonctionnels.
:::

- `graphql/type` : contient la déclaration des **types GraphQL** de la vue.

### Signature d’un resolver

Une fonction resolver possède la signature suivante :

```javascript
async (args, context) => ExpectedType;
```

avec :

- `args` : objet contenant les arguments de la query ou les inputs de la mutation ;
- `context` : objet possédant une propriété `process`, qui contient notamment :
  - `projectId` : identifiant du projet en cours ;
  - `viewId` : identifiant de la vue courante.

### Exemple de resolver pour la query `getCustomer`

:::CodeblockTabs
getCustomer.mjs

```javascript
export const getCustomer = async (_args, context) => {
  const { projectId, viewId } = context.process;

  // Resolve query fields
  let firstName;
  let lastName;

  // Send back query fields
  return {
    firstName,
    lastName
  };
};

export default getCustomer;
```
:::

### Exemple de resolver pour la mutation `createCustomer`

:::CodeblockTabs
createCustomer.mjs

```javascript
export const createCustomer = async (args, context) => {
  const { projectId, viewId } = context.process;
  const { firstName, lastName } = args;

  try {
    // Resolve mutation

    // Send OK to inform that everything went smoothly
    return { ok: true, error: null };
  } catch (error) {
    // Send KO to inform that an error occurred
    return { ok: false, error: error.message };
  }
};

export default createCustomer;
```
:::

## Partie client

Pour la partie client de chaque vue, les éléments suivants sont générés :

- un fichier squelette pour le **composant principal** de la vue ;
- un fichier squelette de **test** pour ce composant ;
- un dossier `graphql` qui contient la définition client de chaque **query** et **mutation** GraphQL ;
- un dossier `hooks` qui contient un **hook React** pour chaque **query** et **mutation** déclarée.

### Hooks générés

:::BlockQuote
**\[info]** Les hooks générés servent à appeler les **queries** et **mutations** GraphQL depuis les composants de la vue.
:::

- Pour une **query**, le hook suit la convention `use<ResolverName>Query`. Exemple : `useGetCustomerQuery` ;
- Pour une **mutation**, le hook suit la convention `use<ResolverName>Mutation`. Exemple : `useCreateCustomerMutation`.
