Construction, Affichage et Évaluation

Le déroulement d'un exercice sous PLaTon se compose de 4 parties:

• La Construction, à l'aide d'une clé builder
• L'Affichage, à l'aide des clés title, statement, et form
• L'Évaluation, à l'aide d'une clé grader
• La Solution, à l'aide d'une clé solution

Environnment d'exécution : Sandbox

Les exercices sont executés dans un environnement isolé appelé sandbox. Il existe plusieurs types de sandbox, chacune ayant ses propres caractéristiques. Le choix de la sandbox se fait à l'aide de la clé sandbox dans la configuration de l'exercice.

Sandbox node

• Syntaxe : sandbox = "node"
• Description : Sandbox permettant d'exécuter du code javascript. Cette sandbox est utilisée par défaut et utilise l'api de sandboxing de nodejs.
• Librairies disponibles : Cette sandbox est pratique pour des exercices simples ne nécessitant pas d'opérations complexes ou de librairies système. Vous avez accès à l'API de base de javascript ainsi que quelques fonctions utilitaires (opens in a new tab).

Sandbox python

• Syntaxe : sandbox = "python"
• Description : Sandbox permettant d'exécuter du code python. Cette sandbox utilise des containers docker pour exécuter du code python.
• Libraries disponibles : Cette sandbox est plus complète que la sandbox node, et vous donne accès à un container Linux avec plusieurs librairies et outils pré-installés (python, gcc, java, postgresql...). Vous pouvez consulter la liste des librairies disponibles ici (opens in a new tab)

Construction: Builder

Afin de construire des exercices ayant une part d'aléatoire, ou de faciliter la création de type d'exercices réutilisables, il peut être nécessaire de passer par un script de construction de l'exercice.

Pour cela, il est possible de déclarer un script python/node (en fonction de la sandbox) dans une clé builder.

Par exemple :

builder == #!lang=js
 
max = 10
op1 = Math.round(Math.random() * max)
op2 = Math.round(Math.random() * max)
 
==

Pour utiliser de l'aléatoire sur les sandboxes python, vous devez utiliser la fonction random en l'initialisant avec une graine (seed) automatiquement disponible dans les variables globales du builder.

Par exemple:

import random
random.seed(seed)

Affichage: Title, Statement et Form

Pour afficher un exercice, il est nécessaire de déclarer 3 clés dans la configuration de l'exercice. La valeur de ces clés peut être du HTML et/ou du Markdown (opens in a new tab).

Il est possible d'afficher n'importe quelle variable de l'exercice à l'aide de la syntaxe {{ nomvariable }} dans le contenu de ces 3 clés. Si la variable affichée est un texte contenant d'autres affichage de variables, le processus de remplacement des variables s'appliquera récursivement.

La plateforme utilise en interne la librairie nunjunks (opens in a new tab) pour le rendu des variables. Il vous est donc possible d'utiliser les fonctionnalités de cette librairie dans vos exercices comme par exemple les filtres (opens in a new tab) ou les expressions (opens in a new tab).

Pour le rendu du markdown, la plateforme utilise la librairie nge-markdown (opens in a new tab) qui contient quelques extensions supplémentaires par rapport au markdown de base comme le support du latex et des onglets.

title

La clé title contient le titre de l'exercice. Par exemple :

title ==
Addition aléatoire
==

statement

La clé statement contient l'énoncé de l'exercice. Par exemple :

text ==
Quel est le **résultat** de: **{{ op1 }}** + **{{ op2 }}** ?
==

A l'affichage, après traitement du markdown, du HTML et des variables, en supposant que op1 contient 10 et op2 20, le texte suivant sera affiché:

Quel est le résultat de: 10 + 20 ?

form

La clé form contient le formulaire de l'exercice. Par exemple :

input = :wc-input-box
input.type = "number"
input.placeholder = "Entrez votre réponse ici"
 
form ==
{{ input }}
==

Évaluation: Grader

Le grader est le script qui va évaluer la réponse de l'apprenant. Il est possible de déclarer un script python/node (en fonction de la sandbox) dans une clé grader.

Ce script à accès à l'ensemble des variables de l'exercice: celles déclarées dans le ple, celles créés par le script de construction, celles modifiées par l'apprenant dans le formulaire (les composants).

En plus de vos variables, 2 variables spéciales sont disponibles :

• grade : La note de l'apprenant, entre 0 et 1 (-1 si l'exercice est en erreur)

• feedback : Un objet permettant de renvoyer un feedback à l'apprenant. Les clés de cet objet sont :

  • type : Le type de feedback à renvoyer à l'apprenant. Les valeurs possibles sont warning, error et success
  • content : Le message à afficher à l'apprenant (markdown|html)

Vous devez modifier la valeur de ces clés pour renvoyer un feedback à l'apprenant et lui attribuer une note en fonction de sa réponse.

Par exemple:

grader == #!lang=js
 
grade = 0
feedback.type = "error"
feedback.content = "Mauvaise réponse"
 
// input.value contient la réponse de l'apprenant
 
if (input.value === op1 + op2) {
  grade = 100
  feedback.type = "success"
  feedback.content = "Bonne réponse"
}
 
// A cet endroit vous pouvez modifer toutes les variables de l'exercice avant de les renvoyer à l'apprenant.
// Par exemple, vous pouvez afficher la bonne réponse dans input.value
 
==
 

Affichage de la solution : Solution

Il est possible d'afficher la solution d'un exercice à l'aide de la clé solution. Cette clé suit la même logique que la clé form, sauf qu'elle contient le HTML/Markdown à afficher à l'apprenant lorsqu'il demande la solution.

Par exemple:

inputSolution = :wc-input-box
inputSolution.type = "number"
inputSolution.disabled = true
inputSolution.placeholder = "Solution"
 
builder == #!lang=js
 
max = 10
op1 = Math.round(Math.random() * max)
op2 = Math.round(Math.random() * max)
inputSolution.value = op1 + op2
 
==
 
solution ==
{{ inputSolution }}
==