diff --git a/capytale/contracts/src/mode.ts b/capytale/contracts/src/mode.ts index f3fedc8..2de53ee 100644 --- a/capytale/contracts/src/mode.ts +++ b/capytale/contracts/src/mode.ts @@ -1,5 +1,15 @@ /** * Ce module définit la transmission du mode de l'activité. + * + * Les modes peuvent être : + * - `"create"` - Pour un enseignant en train de créer/modifier une activité. + * - `"assignment"` - Pour un élève/participant en train d'effectuer le travail demandé. + * - `"review"` - Pour un enseignant regardant la copie d'un élève.participant (que la + * copie soit finalisée ou non: voir le contrat `workflow`). + * - `"view"` - Pour un enseignant regardant une activité créée par un autre enseignant + * depuis la bibliothèque d'activité de Capytale. + * + * Souscription avec `mode:{v}`, où `{v}` est le numéro de version du contrat. */ type Mode = @@ -28,13 +38,14 @@ export type ModeV1 = { /** * L'interface qui expose l'*Application* au *MetaPlayer*. + * Toutes les méthodes sont asynchrones. */ application: { /** - * Le *MetaPlayer* appelle cette méthode pour indiquer le mode à l'*Application*. - * Ne devrait être appelé qu'une seule fois. + * Le *MetaPlayer* appelle systématiquement cette méthode pour indiquer le mode à l'*Application* + * avant d'avoir appelé la méthode `loadContent` des contrats `simple-content`. * - * @param mode le mode à appliquer. + * @param mode le mode utilisé actuellement pour l'activité. */ setMode(mode: Mode): void; }; diff --git a/capytale/contracts/src/reload.ts b/capytale/contracts/src/reload.ts index af36971..ad97fee 100644 --- a/capytale/contracts/src/reload.ts +++ b/capytale/contracts/src/reload.ts @@ -1,5 +1,14 @@ /** - * Ce module définit le mécanisme de rechargement de l'iFrame. + * Ce module définit le mécanisme de rechargement de l'iFrame: + * + * Si l'*Application* n'est pas une SWA (Single Web App), il peut lui être nécessaire de changer de page + * en cours d'utilisation. Dans ce cas, le *MetaPlayer* doit être notifié pour que l'iFrame soit détruite + * et reconstruite avec la nouvelle URL. + * Ce contrat permet également de transmettre les informations sur le contenu actuel de l'*Application* + * entre la page initiale et la nouvelle page, sans passer par le mécanisme de sauvegarde des contrats + * de type `simple-content`. + * + * Souscription au contrat avec `reload:{v}`, où `{v}` est le numéro de version. */ /** @@ -13,13 +22,24 @@ export type ReloadV1 = { */ metaplayer: { /** - * L'*Application* peut appeler cette méthode pour demander un rechargement. - * L'iFrame est détruite puis recréée. + * L'*Application* peut appeler cette méthode pour demander un rechargement avec l'url + * passée en argument. + * + * - L'iFrame est détruite puis recréée avec la nouvelle adresse. + * - Le *MetaPlayer* récupère un état (`state`) contenant toutes les données qui devront + * être ensuite passées à la nouvelle instance de l'*Application* (à minima, toutes les + * données liée à l'activité en cours). + * - Après chargement de la nouvelle page, l'*Application* souscrit aux différents contrats, + * mais le *MetaPlayer* n'appellera _PAS_ la méthode `loadContent` : c'est la la méthode + * `reloaded` du présent contrat qui sera appelée à la place. * * @param url l'URL à charger dans l'iFrame. - * Si null, l'URL actuelle est rechargée. + * Si `null`, l'URL actuelle est rechargée. + * ATTENTION: si la logique de l'*Application* repose sur des paramètres passés + * via l'URL, ne pas oublier de les rajouter à cet argument. * - * @param state un état éventuel à transmettre à l'application après le rechargement. + * @param state un état à transmettre à l'application après le rechargement. + * L'objet `state` doit être serializable avec JSON.stringify. * */ reload(url?: string | null, state?: any): void; @@ -27,11 +47,14 @@ export type ReloadV1 = { /** * L'interface qui expose l'*Application* au *MetaPlayer*. + * Toutes les méthodes sont asynchrones. */ application: { /** * Le *MetaPlayer* appelle cette méthode pour indiquer à l'*Application* qu'un - * rechargement a eu lieu. + * rechargement a eu lieu et lui passé le dernier état de l'*Ap^plication*. + * Cette méthode est appelée en lieu et place de `loadContent`, suite à une + * demande de rechargement. * * @param state l'état que l'application a transmis lors de l'appel à `reload`. */ diff --git a/capytale/contracts/src/simple-content-eval.ts b/capytale/contracts/src/simple-content-eval.ts index a3e22a3..6ac553d 100644 --- a/capytale/contracts/src/simple-content-eval.ts +++ b/capytale/contracts/src/simple-content-eval.ts @@ -11,6 +11,11 @@ type StringEvaluation = { score: string; } + +/**Représente l'évaluation d'un exercice de l'activité. + * - `evalLabel`: utiliser `"Exercice N" (sert d'identifiant pour enregistrer les données) + * - `evalTitle`: titre (optionnel) de l'exercice. + */ type Evaluation = { evalLabel: string; evalTitle?: string; @@ -35,19 +40,24 @@ export type SimpleContentEvalV1 = { */ metaplayer: { /** - * L'*Application* doit appeler cette méthode pour indiquer au *MetaPlayer* que le contenu a été modifié par l'utilisateur. + * L'*Application* doit appeler cette méthode pour indiquer au *MetaPlayer* que le contenu + * a été modifié par l'utilisateur (permettant par exemple d'activer le bouton de sauvegarde + * dans le bandeau supérieur de Capytale). */ contentChanged(): void; }; /** * L'interface qui expose l'*Application* au *MetaPlayer*. + * Toutes les méthodes sont asynchrones. */ application: { /** - * Le *MetaPlayer* appelle cette méthode pour envoyer les données à l'*Application*. + * Le *MetaPlayer* appelle cette méthode après la souscription au contrat, pour transmettre + * les données de l'activité à l'*Application*. * - * Si `content` est `null`, l'*Application* doit réinitialiser son contenu à la valeur par défaut initiale. + * Si `content` est `null`, l'*Application* doit réinitialiser son contenu à la valeur par + * défaut initiale. * Si l'*Application* n'est pas en mesure de charger le contenu, elle doit lever une exeption. * * @param content le contenu de l'activité @@ -55,9 +65,12 @@ export type SimpleContentEvalV1 = { loadContent(content: T | null): void; /** - * Le *MetaPlayer* appelle cette méthode pour récupérer les données de l'*Application* dans le mode create. + * Le *MetaPlayer* appelle cette méthode pour récupérer les données de l'*Application*, + * dans le mode create. + * + * L'*Application* peut retourner `null` si le contenu correspond à la valeur par défaut + * initiale. * - * L'*Application* peut retourner `null` si le contenu correspond à la valeur par défaut initiale. * * @returns le contenu de l'activité */ diff --git a/capytale/contracts/src/simple-content.ts b/capytale/contracts/src/simple-content.ts index b9461e1..13157da 100644 --- a/capytale/contracts/src/simple-content.ts +++ b/capytale/contracts/src/simple-content.ts @@ -1,10 +1,21 @@ /** - * Ce module définit le contrat d'échange des contenus. + * Ce module définit le contrat d'échange des contenus de l'activité. + * + * - Les données peuvent être `null` lorsqu'aucune donnée n'existe pour l'activité, + * côté Capytale (typiquement: au moment de la création de l'activité). + * - Les données pour une acivité doivent toujours être du même type, quel que soit + * le mode utilisé (create, assignment, ...). + * + * Souscription avec `"simple-content({type}):{v}"`, où : + * - `{v}` est le numéro de version du contrat. + * - `{type}` est le type de données utilisées par l'*Application*. Peut être: + * json + * text */ /** * Un contrat pour gérer un contenu simple : - * - un seul contenu de type `T` + * - un seul contenu de type `T|null` * - le mode assignment est le même que le mode create c'est à dire que * le contenu initial pour l'élève est celui qui a été préparé par l'enseignant. * @@ -18,36 +29,52 @@ export type SimpleContentV1 = { */ metaplayer: { /** - * L'*Application* doit appeler cette méthode pour indiquer au *MetaPlayer* que le contenu a été modifié par l'utilisateur. + * L'*Application* doit appeler cette méthode pour indiquer au *MetaPlayer* que le contenu + * a été modifié par l'utilisateur (permettant par exemple d'activer le bouton de sauvegarde + * dans le bandeau supérieur de Capytale). */ contentChanged(): void; }; /** * L'interface qui expose l'*Application* au *MetaPlayer*. + * Toutes les méthodes sont asynchrones. */ application: { /** - * Le *MetaPlayer* appelle cette méthode pour envoyer les données à l'*Application*. + * Le *MetaPlayer* appelle cette méthode après la souscription au contrat, pour transmettre + * les données de l'activité à l'*Application*. * - * Si `content` est `null`, l'*Application* doit réinitialiser son contenu à la valeur par défaut initiale. - * Si l'*Application* n'est pas en mesure de charger le contenu, elle doit lever une exeption. + * - Si `content` est `null`, l'*Application* doit initialiser son contenu à la valeur + * par défaut initiale. + * - Si l'*Application* n'est pas en mesure de charger le contenu, elle doit lever une + * exeption. * * @param content le contenu de l'activité */ loadContent(content: T | null): void; /** - * Le *MetaPlayer* appelle cette méthode pour récupérer les données de l'*Application*. + * Le *MetaPlayer* appelle cette méthode pour récupérer les données de l'*Application*, + * lorsque l'utilisateur effectue une action demandant d'enregistrer des données sur + * Capyale (typiquement, cliquer sur le bouton Enregsitrer dans le bandeau supérieur). * - * L'*Application* peut retourner `null` si le contenu correspond à la valeur par défaut initiale. + * L'*Application* peut renvoyer `null` si le contenu correspond à la valeur par défaut + * initiale. * * @returns le contenu de l'activité */ getContent(): T | null; /** - * Le *MetaPlayer* appelle cette méthode pour indiquer à l'*Application* que le contenu a été sauvegardé. + * Le *MetaPlayer* appelle cette méthode pour indiquer à l'*Application* que le contenu + * a été sauvegardé, côté Capytale. + * + * Cette notification peut être utile à l'*Application* si elle gère des états `dirty` + * (données non enregistrées dans Capytale) pour éviter que l'utilisateur ne puisse faire + * certaines actions qui lui ferait perdre ces données par mégarde. + * + * Cette méthode n'est appelée que si la sauvegarde a été un succès. */ contentSaved(): void; }; diff --git a/capytale/contracts/src/theme.ts b/capytale/contracts/src/theme.ts index 86cc35f..772b3f9 100644 --- a/capytale/contracts/src/theme.ts +++ b/capytale/contracts/src/theme.ts @@ -1,5 +1,5 @@ /** - * Ce module définit la transmission du thème d'affichage. + * Ce module définit la transmission du thème d'affichage (`"dark"|"light"`). */ /** @@ -23,6 +23,7 @@ export type ThemeV1 = { /** * L'interface qui expose l'*Application* au *MetaPlayer*. + * Toutes les méthodes sont asynchrones. */ application: { /** diff --git a/capytale/contracts/src/workflow.ts b/capytale/contracts/src/workflow.ts index 454295e..4b17923 100644 --- a/capytale/contracts/src/workflow.ts +++ b/capytale/contracts/src/workflow.ts @@ -1,5 +1,15 @@ /** - * Ce module définit la transmission du workflow de l'assignment. + * Ce module définit la transmission de l'état actuel du workflow de la copie d'un + * élève/participant. + * L'état workflow peut prendre l'une des valeurs suivantes : + * + * - `"current"` - L'élève n'a pas encore rendu la copie. + * - `"finished"` - L'élève a rendu la copie : il ne peut plus la modifier (il peut encore + * la consulter ou pas, selon le réglage du "mode d'accès" de l'activité, + * dans les paramètres de l'activité). + * - `"corrected"` - L'enseignant a marqué la copie comme corrigée/évaluée. + * + * Souscription avec `workflow:{v}`, où `{v}` est le numéro de version du contrat. */ type Workflow = 'current' | 'finished' | 'corrected'; @@ -24,13 +34,16 @@ export type WorkflowV1 = { /** * L'interface qui expose l'*Application* au *MetaPlayer*. + * Toutes les méthodes sont asynchrones. */ application: { /** * Le *MetaPlayer* appelle cette méthode pour indiquer le workflow à l'*Application*. - * Peut être appelé plusieurs fois. + * Cette méthode est appelée une première fois juste après un appel à `setMode` (si le contrat + * `mode` a été souscrit) pour indiqué l'état initial, puis elle est rappelée à chaque fois que + * l'état de la copie de l'élève/du participant est modifié. * - * @param mode le mode à appliquer. + * @param workflow: la nouvelle valeur du workflow à appliquer. */ setWorkflow(wf: Workflow): void; };