Transitions
Vous pouvez trouver des informations complémentaires sur les transitions dans la documentation de l' OIP starter et dans la documentation OIP par l'exemple
Les transitions entre les vues d'un OAV sont gérés par des fonctions exposées par l'OIP Core.
Configuration
Deux fichiers sont nécessaires pour la configuration des transitions :
- viewsConfig/workflow.mjs
- viewsConfig/transitions.mjs
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
}
];Une transition est caractérisée par quatre éléments :
- L'identifiant de la vue source : srcViewId.
- L'identifiant de la vue cible : tgtViewId.
- Le type de la transition : next ou prev.
- Un ordre : conditionOrder.
Une transition prev caractérise un retour à la vue précédente.
Algorithme
L'algorithme permettant de passer d'une vue à une autre est trÚs simple et se base sur deux informations : la vue actuelle et l'action à réaliser (prev ou next). Etant donné ces deux informations, l'algorithme :
- RĂ©cupĂšre l'ensemble des transitions selon les critĂšres :
- La propriété srcViewId est égale à la vue actuelle.
- La propriété action est égale à l'action à réaliser.
- Trie les transitions correspondantes par la propriété conditionOrder.
- Evalue les transitions triées via les handlers définis par la propriété conditionLabel jusqu'à en trouver une qui est satisfaite (i.e. la condition qui est un prédicat est évaluée à true). Si une transition n'a pas de propriété conditionLabel alors elle est toujours sélectionnée.
- Renvoyer la propriété tgtViewId de la premiÚre transition satisfaisant les conditions.
Transitions conditionnelles
Une transition est conditionnelle si elle a la propriété conditionLabel.
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
}
];La déclarationconditionLabel: 'company_next_grantee' signifie qu'un handler nommé company_next_grantee est attaché à la transition Company => Grantee.
Fichier handler
export default {
company: {
hooks: {},
transitionConditions: {
company_next_grantee: (ctx) => ctx.form.isActive
}
}
};L'objet transitionConditions liste toutes les transitions conditionnelles d'une vue. Les clés de cet objet sont les valeurs des propriétés conditionLabel définies dans le fichier transitions.mjs, et les valeurs sont les handlers associés. Chaque handler a un objet ctx attaché qui peut contenir des informations sur la page en cours (ctx.form) ou des informations calculées dans les hooks before (ctx.setup).
L'objet hooks regroupent des handlers qui peuvent ĂȘtre appelĂ©s avant (hooks before) ou aprĂšs (hooks after) l'Ă©valuation des conditions. Les hooks before peuvent par exemple servir Ă rĂ©cupĂ©rer une seule fois des informations utilisĂ©es par plusieurs conditions. Les hooks next peuvent par exemple servir Ă exĂ©cuter des opĂ©rations de nettoyage une fois l'Ă©valuation des conditions terminĂ©e. Les hooks disponibles sont au nombre de quatre : beforeNext, beforePrev, afterNext, afterPrev. Les hooks beforeNext et afterNext (respectivement beforePrev et afterPrev) ne sont exĂ©cutĂ©s que dans le cadre de l'action next (respectivement prev). Ces hooks ont Ă©galement un objet ctx qui leur attachĂ©.
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)`
}
}
}
};Deux rĂšgles doivent ĂȘtre suivies :
- Chaque vue ayant au moins une transition conditionnelle doit avoir un fichier associé dans le dossier viewsConfig/transitions-handlers.
- Toutes les transitions conditionnelles d'une vue doivent ĂȘtre dĂ©clarĂ©es dans le mĂȘme fichier viewsConfig/transitions-handlers/${VIEW_NAME}.
Conventions
Nommage
- Dans le fichier transitions.mjs, le format de la propriété conditionLabel est : ${SRC_VIEW_ID}_${ACTION}_${TGT_VIEW_ID}.
- Les fichiers dans le dossier viewsConfig/transitions-handlers suivent la convention de nommage : ${VIEW_NAME}.mjs.
Organisation du code
Il est important de centraliser la déclaration des identifiants des vues pour faciliter la maintenance et l'évolution de l'OAV.
Ci-dessous un exemple d'organisation du code des vues d'un OAV :
export const getTransitionsContext = (project) => {
// Put your logic here
};
Par convention, le fichier view-ids.mjs centralise la déclaration de l'ensemble des identifiants des vues de l'OAV. Tout fichier ayant besoin d'un identifiant d'une vue utilise l'objet viewIds déclaré dans le fichier view-ids.mjs. Vous pouvez constater ce principe dans les fichiers workflow.mjs, transitions.mjs et risks.mjs.
Par convention, le fichier transitions-helpers.mjs centralise le code partagé par plusieurs vues. Dans l'exemple ci-dessus, ce fichier contient une méthode getTransitionsContext qui est utilisée par les vues pour récupérer un contexte avant d'évaluer les conditions.