Naviguer entre les vues
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
Les fichiers responsables de la logique de transition des vues se trouvent dans le dossier viewsConfig
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.mjsLe 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 :
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 :
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 associé à la transition.
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 srcViewId, la même action, mais avec un conditionOrder 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. Par convention, chaque fichier correspond à une vue et porte pour nom l’identifiant de cette vue.
Exemple : fichier du handler pour la vue start :
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. 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. 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 :
{
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 :
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 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. 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 :
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 :
- 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
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;- L'objet context passé en paramètre à la méthode onNext contient l'entité customer
- Deux transitions sont possibles pour l'action next depuis la vue start. Ces transitions sont définies comme suit dans le fichier transitions.mjs :
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
- 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
- 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
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
}
}
};- 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é.
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.
La fonction associée reçoit en paramètre l'entité customer définie depuis l'objet ctx
- 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
- 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
export default [
...
{
srcViewId: 'start',
tgtViewId: 'altSummary',
action: 'next',
conditionLabel: 'start_to_altSummary',
conditionOrder: 2
},
...
];- 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 :
- éditer le fichier workflow.mjs et ajouter l'identifiant de la nouvelle vue à la liste views
- éditer le fichier transitions.mjs et ajouter les transitions relatives à la nouvelle vue
- 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. :
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);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 :
- L'identifiant de la première vue de l'OAV.
- La liste des identifiants de l'ensemble des vues.
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.
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
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
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.
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)`
}
}
}
};