Configurer des vues

21 min

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.

[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

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.

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.

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.

[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) :

Le fichier de transitions de la vue courante est lu.

Les handlers définis dans next.transitions (ou prev.transitions) sont évalués dans l’ordre.

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

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.

npm run views:gen

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

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

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 :

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.

[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é.

[info] Vous 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 :

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

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

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

[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.