Commandes
init
Présentation
La commande init initialise un nouveau projet. Elle permet de générer l'ensemble minimal des fichiers requis pour un démarrage rapide.
Par ailleurs, pour répondre au besoin minimal requis lors du décrochage, le modèle de données du projet est initialisé avec une unique entité Project qui possède une unique propriété externalId de type string.
Options
--oav-name
Nom de l'OAV attendu en valeur.
--first-view-name
Nom de la première vue du parcours attendu en valeur.
Fichiers générés
Arborescence des fichiers générés à l'exécution de la commande :
Project Root/
├── config/
│ ├── entities/
│ │ └── entities.config.mjs
│ └── views/
│ └── 0000-MY-FIRST-VIEW.yml
├── entities/
│ ├── Project/
│ │ └── index.mjs
│ └── entities.mjs
├── migrations/
│ └── 0000000000000_migration.js
├── transitions/
│ └── MY_FIRST_VIEW.mjs
├── views/
│ └── my-first-view/
│ ├── client/
│ │ └── ...
│ └── server/
│ └── ...
├── .env
└── index.htmlExplication des fichiers générés :
- Les fichiers relatifs au modèle de données du projet, à savoir :
- le fichier de configuration des entités config/entities/entities.config.mjs ;
- les fichiers de manipulation des entités dans le dossier entities ;
- les fichiers de migration initiaux du modèle de données du projet dans le dossier migrations.
- Les fichiers relatifs à la première vue du parcours (si l'option --first-view-name est utilisée) :
- le fichier de configuration de la vue initiale config/views/0000-MY-FIRST-VIEW.yml ;
- les fichiers client et serveur de la vue initiale dans le dossier views/MY-FIRST-VIEW ;
- le fichier de transition de la vue initiale transitions/MY_FIRST_VIEW.mjs.
- Le fichier .env (généré à partir du fichier .env.dist) : les valeurs des variables d'environnement OAV_ID et OIP_API_KEY sont générées et injectées.
- Injection du nom de l'OAV dans la balise <title> du fichier index.html à la racine du projet.
- Le fichier de migration qui initialise le modèle de données du projet migrations/0000000000000_migration.js.
entities generate
Présentation
La commande entities generate permet de générer à partir du fichier de configuration des entités :
- d'une part les fichiers de manipulation des entités, générés dans le dossier entities à la racine du projet ;
- d'autre part les fichiers de migration du modèle de données du projet (si nécessaire), générés dans le dossier migrations à la racine du projet.
Options
--oas-config
Type boolean, valeur par défaut : false.
Génère les fichiers relatifs aux entités à partir d'un fichier de configuration au format Open API.
Nom du fichier de configuration attendu : entities.openapi.[ext]
Extensions supportées : yml, yaml et json
Fichier de configuration des entités
Chemin du fichier de configuration :
Project Root/
└── config/
└── entities/
└── entities.openapi.ymlUn unique fichier de configuration des entités est attendu dans le dossier config/entities à la racine du projet :
- Si la commande est exécutée sans l'option --oas-config, le fichier entities.config.mjs est attendu. Ce fichier peut être généré à partir de l'outil OIP Data ;
- Si la commande est exécutée avec l'option --oas-config, le fichier entities.openapi.yml|yaml|json est attendu. Ce fichier vous est fournit par l’architecte responsable de votre projet.
Exemple de fichiers de configuration
export default {
Project: {
properties: {
name: { type: 'string' },
externalId: { type: 'string' },
},
relations: ['Company', 'Customer'],
},
Company: {
properties: {
name: { type: 'string' },
siret: { type: 'string' },
},
},
Customer: {
properties: {
firstName: { type: 'string' },
lastName: { type: 'string' },
},
},
};Fichiers générés
Arborescence des fichiers générés à l'exécution de la commande :
Project Root/
├── entities/
│ ├── Company/
│ │ └── index.mjs
│ ├── Customer/
│ │ └── index.mjs
│ ├── Project/
│ │ └── index.mjs
│ └── entities.mjs
└── migrations/
├── 0000000000000_migration.js
└── 1773757038683_migration.jsExplication des fichiers générés :
- les fichiers de manipulation des entités dans le dossier entities ;
- si des changements sont détectés au niveau du modèle de données du projet, ex. l'ajout d'une entité, un fichier de migration est généré dans le dossier migrations à la racine du projet. Le nom d'un fichier de migration généré est de la forme : [timestamp]_migration.js.
views generate
Présentation
La commande views generate permet de générer à partir des fichiers de configuration des vues, les fichiers client et serveur de chaque vue dans le dossier views à la racine du projet.
[warn] De nombreux fichiers générés par cette commande ne doivent pas être modifiés directement.Ces fichiers sont identifiés grâce à au commentaire d'en-tête : « Code generated by gen. DO NOT EDIT. »
Cette commande vérifie également la conformité des fichiers de transition des vues définis dans le dossier transitions à la racine du projet.
Options
--clean-unused-files
Type boolean, valeur par défaut : false.
Supprime les fichiers générés qui ne sont plus utilisés.
--ext-file-backend
Type string, valeur par défaut : mjs.
Définit l'extension des fichiers serveur générés.
--gen-test-files
Type boolean, valeur par défaut : true.
Active ou désactive la génération des fichiers de test des vues.
--tree-structure
Type string, valeurs possibles : ['legacy', 'standard'], valeur par défaut : standard.
Choix de l'arborescence générée dans le cas des vues définies dans des sous-dossiers.
Standard (défaut)
views/
└── some-dir/
└── my-view/
├── client/
│ └── ...
└── server/
└── ...Legacy
views/
└── some-dir/
├── client/
│ └── my-view/
│ └── ...
└── server/
└── my-view/
└── ...--gen-secure-resolvers
Type boolean, valeur par défaut : false.
Sécurise ou non les resolvers graphQL générés. Si true, seuls les resolvers associés à la vue actuelle du contexte de l'application peuvent être appelés.
Fichiers de configurations des vues
Les fichiers de configuration des vues sont attendus dans le dossier config/views à la racine du projet.
Project Root/
└── config/
└── views/
├── 00-home.yml
├── 01-customer.yml
└── 02-company.ymlUn fichier de configuration YAML est attendu pour la définition de chaque vue.
Structure d'un fichier de configuration
Le fichier de configuration d'une vue 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.
Par exemple, pour une vue customer qui serait la 2ème vue du parcours, le nom de son fichier de configuration est 01-customer.yml.
Exemple d'un fichier de configuration
customer:
viewId: customer
pathname: /customer
directory: customer
graphql:
queries:
- type: Customer
fields:
firstName: String
lastName: String
- type: GetCustomers
fields:
customers: "[Customer]"
resolver: getCustomers
mutations:
- type: Customer
inputs:
firstName: String
lastName: String
resolver: createCustomerFichiers générés
Arborescence des fichiers générés pour une vue à l'exécution de la commande :
Project Root/
└── views/
└── customer/
├── client/
│ ├── graphql/
│ │ ├── mutations/
│ │ │ └── CreateCustomerMutation.js
│ │ └── queries/
│ │ └── GetCustomersQuery.js
│ ├── hooks/
│ │ ├── useCreateCustomerMutationQuery.js
│ │ └── useGetCustomersQuery.js
│ └── Customer.jsx
└── server/
└── graphql/
├── resolver/
│ ├── createCustomer.mjs
│ ├── getCustomers.mjs
│ └── index.mjs
└── type/
├── MutationType.mjs
├── QueryType.mjs
└── queryTypeResolvers.mjsFichiers de transition des vues
Pour chaque vue, il est attendu de définir son fichier de transition associé dans le dossier transitions à la racine du projet.
Project Root/
└── transitions/
├── home.mjs
├── company.mjs
└── customer.mjsLors de l'exécution de la commande, si le fichier de transition associé d'une vue n'est pas trouvé ou qu'il comporte des erreurs, une erreur est jetée.
Structure d'un fichier de transition
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.
Propriété hooks (optionnelle)
hooks est un objet regroupant des fonctions qui sont appelées :
- avant l’évaluation des conditions (before) ;
- après l’évaluation des conditions (after).
Exemple d'un fichier de transition
const prev__home = () => {
return true;
};
const next__company = () => {
return true;
};
export default {
prev: {
transitions: [{ viewId: 'home', handler: prev__home }]
},
next: {
transitions: [{ viewId: 'company', handler: next__company }]
}
};