feat: #365 allow unlimited attempt for quizzes

Author: payamnj

django_email_learning/migrations/0009_quiz_limited_attempts.py

@@ -0,0 +1,17 @@
+# Generated by Django 6.0.4 on 2026-04-20 07:55
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("django_email_learning", "0008_organization_is_public"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="quiz",
+            name="limited_attempts",
+            field=models.BooleanField(default=True),
+        ),
+    ]

django_email_learning/models.py

@@ -342,6 +342,7 @@ class Quiz(models.Model):
         help_text="Time limit to complete the quiz in days. Minimum is 1 day and maximum is 30 days.",
         validators=[MinValueValidator(1), MaxValueValidator(30)],
     )
+    limited_attempts = models.BooleanField(default=True)
 
     class Meta:
         verbose_name_plural = "Quizzes"
@@ -437,6 +438,12 @@ def title(self) -> str:
             return self.quiz.title
         return "Untitled Content"
 
+    @property
+    def limited_attempts(self) -> Optional[bool]:
+        if self.type == "quiz" and self.quiz:
+            return self.quiz.limited_attempts
+        return None
+
     def human_readable_waiting_period(self) -> str:
         if self.waiting_period < 60:
             return ngettext(
@@ -911,7 +918,10 @@ def save(self, *args, **kwargs) -> None:  # type: ignore[no-untyped-def]
         already_submitted = QuizSubmission.objects.filter(
             delivery=self.delivery
         ).count()
-        if already_submitted >= self.delivery.times_delivered:
+        if (
+            self.delivery.course_content.quiz.limited_attempts  # type: ignore[union-attr]
+            and already_submitted >= self.delivery.times_delivered
+        ):
             raise ValidationError(
                 "Quiz submission count exceeds the number of times the quiz was sent."
             )

django_email_learning/personalised/api/views.py

@@ -82,39 +82,47 @@ def post(self, request, *args, **kwargs):  # type: ignore[no-untyped-def]
             score=score,
             is_passed=passed,
         )
-        # Updating the ContentDelivery hash value to invalidate the quiz link
-        delivery.update_hash()
 
         if passed:
+            delivery.update_hash()  # Invalidate the quiz link after successful submission
             message = _("Congratulations! You have passed the quiz.")
             delivery = delivery.schedule_next_delivery()
+
             if not delivery:
                 enrollment.graduate()
         else:
-            # Check if it's the second attempt failing
             failed_submissions_count = QuizSubmission.objects.filter(
                 delivery=delivery,
                 is_passed=False,
             ).count()
 
-            if failed_submissions_count > 1:
-                message = _(
-                    "You have failed the quiz twice. Unfortunately, you cannot continue this course with this enrollment. You can enroll again to retake the course."
-                )
-                logger.info(
-                    f"Learner ID {enrollment.learner.id} has failed the quiz twice for Course {enrollment.course.title}. "
-                    f"Marking enrollment as failed."
-                )
-                enrollment.fail()
+            if quiz.limited_attempts:
+                delivery.update_hash()
+
+                # Check if it's the second attempt failing
+
+                if failed_submissions_count > 1:
+                    message = _(
+                        "You have failed the quiz twice. Unfortunately, you cannot continue this course with this enrollment. You can enroll again to retake the course."
+                    )
+                    logger.info(
+                        f"Learner ID {enrollment.learner.id} has failed the quiz twice for Course {enrollment.course.title}. "
+                        f"Marking enrollment as failed."
+                    )
+                    enrollment.fail()
+                else:
+                    message = _(
+                        "You have failed the quiz. You will receive another chance to retake it tomorrow."
+                    )
+                    logger.info(
+                        f"Learner ID {enrollment.learner.id} has failed the quiz for Course {enrollment.course.title}. "
+                        f"Scheduling a retry for the next day."
+                    )
+                    delivery.repeat_delivery_in_days(1)
             else:
                 message = _(
-                    "You have failed the quiz. You will receive another chance to retake it tomorrow."
-                )
-                logger.info(
-                    f"Learner ID {enrollment.learner.id} has failed the quiz for Course {enrollment.course.title}. "
-                    f"Scheduling a retry for the next day."
+                    f"You have failed the quiz with score {score}. Please review the material and try again."
                 )
-                delivery.repeat_delivery_in_days(1)
 
         METRIC_SERVICE.quiz_submitted(
             course_slug=enrollment.course.slug,
@@ -128,6 +136,7 @@ def post(self, request, *args, **kwargs):  # type: ignore[no-untyped-def]
                 "passed": passed,
                 "required_score": quiz.required_score,
                 "message": message,
+                "is_invalidated": quiz.limited_attempts and not passed,
             },
             status=200,
         )

django_email_learning/personalised/views.py

@@ -158,6 +158,7 @@ def get(self, request, *args, **kwargs) -> HttpResponse:  # type: ignore[no-unty
                             ),
                             "cancel": _("Cancel"),
                             "submit": _("Submit"),
+                            "try_again": _("Try Again"),
                             "close_window_message": _("You can now close this window!"),
                         },
                     }
@@ -166,6 +167,23 @@ def get(self, request, *args, **kwargs) -> HttpResponse:  # type: ignore[no-unty
             )
 
         except ContentDelivery.DoesNotExist as e:
+            if ContentDelivery.objects.filter(  # type: ignore[misc]
+                id=decoded_token.get("delivery_id")
+            ).exists():
+                return self.render_to_response(
+                    context={
+                        "appContext": {
+                            "errorMessage": _(
+                                "The quiz link has already been used and is not valid anymore."
+                            ),
+                            "localeMessages": {
+                                "error": _("Error"),
+                            },
+                        },
+                        "page_title": _("Quiz Link Expired"),
+                    },
+                    status=410,
+                )
             return self.error_response(
                 message=_("An error occurred while retrieving the quiz"),
                 exception=e,

django_email_learning/platform/api/serializers.py

@@ -554,12 +554,13 @@ def serialize_answers(self, answers: Any) -> list[dict]:
 
 
 class UpdateQuiz(BaseModel):
-    questions: Optional[list[QuestionUpdate]] = Field(min_length=1)
+    questions: Optional[list[QuestionUpdate]] = Field(min_length=1, default=None)
     title: Optional[str] = None
     required_score: Optional[int] = Field(ge=0, examples=[80], default=None)
-    selection_strategy: QuizSelectionStrategy
-    deadline_days: int = Field(
-        ge=MIN_QUIZ_DEADLINE, le=MAX_QUIZ_DEADLINE, examples=[14]
+    selection_strategy: Optional[QuizSelectionStrategy] = None
+    limited_attempts: Optional[bool] = None
+    deadline_days: Optional[int] = Field(
+        ge=MIN_QUIZ_DEADLINE, le=MAX_QUIZ_DEADLINE, examples=[14], default=None
     )
 
     model_config = ConfigDict(extra="forbid")
@@ -574,6 +575,7 @@ class QuizCreate(BaseModel):
     )
     questions: list[QuestionCreate] = Field(min_length=1)
     type: Literal["quiz"] = "quiz"
+    limited_attempts: bool = Field(default=True, examples=[True])
 
 
 class QuizResponse(BaseModel):
@@ -583,6 +585,7 @@ class QuizResponse(BaseModel):
     selection_strategy: str
     deadline_days: int = Field(ge=MIN_QUIZ_DEADLINE, le=MAX_QUIZ_DEADLINE)
     questions: Any  # Will be converted to list in field_serializer
+    limited_attempts: bool
 
     @field_serializer("questions")
     def serialize_questions(self, questions: Any) -> list[dict]:
@@ -827,6 +830,7 @@ def to_django_model(self, course: Course) -> CourseContent:
                 required_score=self.content.required_score,
                 selection_strategy=self.content.selection_strategy.value,  # type: ignore[misc]
                 deadline_days=self.content.deadline_days,  # type: ignore[misc]
+                limited_attempts=self.content.limited_attempts,  # type: ignore[misc]
             )
             quiz.save()
             for question_data in self.content.questions:
@@ -905,6 +909,7 @@ class CourseContentSummaryResponse(BaseModel):
     waiting_period: int
     is_published: bool
     type: str
+    limited_attempts: Optional[bool] = None
 
     @field_serializer("waiting_period")
     def serialize_waiting_period(self, waiting_period: int) -> dict:

django_email_learning/platform/api/views.py

@@ -291,6 +291,8 @@ def _update_course_content_atomic(
                 quiz.selection_strategy = quiz_serializer.selection_strategy.value
             if quiz_serializer.deadline_days is not None:
                 quiz.deadline_days = quiz_serializer.deadline_days
+            if quiz_serializer.limited_attempts is not None:
+                quiz.limited_attempts = quiz_serializer.limited_attempts
             if quiz_serializer.questions is not None:
                 question_ids = set()
                 for question_data in quiz_serializer.questions:

django_email_learning/platform/views.py

@@ -247,6 +247,9 @@ def get_context_data(self, **kwargs) -> dict:  # type: ignore[no-untyped-def]
         context["appContext"]["courseTitle"] = course.title
         context["appContext"]["courseLanguage"] = course.language
         context["appContext"]["customComponent"] = None
+        context["appContext"]["quizDefaults"] = {
+            "limitedAttempts": True,
+        }
         context["appContext"]["direction"] = (
             "rtl" if get_language_info(course.language)["bidi"] else "ltr"
         )
@@ -320,6 +323,20 @@ def get_locale_messages(self) -> Dict[str, str]:
             "add_question": _("Add Question"),
             "quiz_settings": _("Quiz Settings"),
             "waiting_period": _("Waiting Period"),
+            "limited_attempts": _("Limited Attempts"),
+            "unlimited_attempts": _("Unlimited Attempts"),
+            "two_attempts": _("2 Attempts"),
+            "limited_attempts_tooltip": _(
+                "If limited attempts is enabled, learners only have 2 attempts to pass the quiz. "
+                "After 2 failed attempts, they will fail the course and need to restart it. If limited attempts is disabled, "
+                "learners can retry the quiz as many times as needed until they pass."
+            ),
+            "quiz_2_attempts_sub_note": _(
+                "Learners only have 2 attempts to pass the quiz. After 2 failed attempts, they will fail the course and need to restart it."
+            ),
+            "quiz_unlimited_attempts_sub_note": _(
+                "Learners can retry the quiz as many times as needed until they pass."
+            ),
             "quiz_waiting_tooltip": _(
                 "Time to wait after the previous content delivery before sending this quiz"
             ),

frontend/personalised/quiz_public/Quiz.jsx

@@ -1,7 +1,7 @@
 import render, { useAppContext } from '../../src/render.jsx';
 import { use, useEffect, useState } from 'react';
 import Layout from '../../public/components/Layout.jsx';
-import { Alert, Box, Button, Checkbox, FormControlLabel, Typography, Dialog } from '@mui/material';
+import { Alert, Box, Button, Checkbox, FormControlLabel, Typography, Dialog, Link } from '@mui/material';
 import CelebrationIcon from '@mui/icons-material/Celebration';
 import SentimentVeryDissatisfiedIcon from '@mui/icons-material/SentimentVeryDissatisfied';
 
@@ -14,6 +14,7 @@ const Quiz = () => {
     const [showQuestions, setShowQuestions] = useState(true);
     const [isPassed, setIsPassed] = useState(null);
     const [message, setMessage] = useState("");
+    const [isInvalidated, setIsInvalidated] = useState(true);
     const [score, setScore] = useState(null);
 
 
@@ -46,6 +47,7 @@ const Quiz = () => {
            setIsPassed(data.passed);
            setScore(data.score);
            setMessage(data.message);
+           setIsInvalidated(data.is_invalidated);
         })
         .catch(() => {
             console.error("Error submitting quiz");
@@ -88,8 +90,10 @@ const Quiz = () => {
         </Box>
         </Box></> : <Box textAlign="center">
             {isPassed !== null && (isPassed ? <><CelebrationIcon sx={{mb: 2, color: 'primary.main', fontSize: '3rem'}}/><Alert severity="success" sx={{justifyContent: 'center', alignItems: 'center'}} ><Typography variant='h6'>{message} {localeMessages['your_score']}: {score}%</Typography></Alert></> :
-            <Alert severity="error" sx={{ justifyContent: 'center', alignItems: 'center' }} ><Typography variant="h6">{message} {localeMessages['your_score']}: {score}%</Typography></Alert>)}
-            <Box sx={{mt: 6, fontSize: '0.8rem'}}><Typography>{localeMessages['close_window_message']}</Typography></Box>
+            <><Alert severity="error" sx={{ justifyContent: 'center', alignItems: 'center' }} ><Typography variant="h6">{message} {localeMessages['your_score']}: {score}%</Typography></Alert>
+            {!isInvalidated && <Box mt={3} textAlign="center"><Button onClick={() => window.location.reload()} variant="contained">{localeMessages['try_again']}</Button></Box>}
+            </>)}
+            <Box sx={{mt: 6, fontSize: '0.8rem'}}>{ isInvalidated && <Typography>{localeMessages['close_window_message']}</Typography>}</Box>
         </Box>}
         </Box> : <Alert severity="error"><Typography variant="h6">{localeMessages['error']}: {errorMessage} {ref && `(Ref: ${ref})`}</Typography></Alert>}
         <Dialog open={dialogOpen} onClose={() => setDialogOpen(false)} fullWidth maxWidth="sm">

frontend/platform/course/Course.jsx

@@ -233,6 +233,7 @@ function Course() {
                                 initialWaitingPeriod={content.waiting_period}
                                 initialStrategy={content.quiz.selection_strategy}
                                 initialDeadlineDays={content.quiz.deadline_days}
+                                initialLimitedAttempts={content.quiz.limited_attempts}
                                  /></Suspense>);
             }
         }

frontend/platform/course/components/ContentTable.jsx

@@ -1,9 +1,10 @@
-import { Alert, CircularProgress, IconButton, Switch, TableContainer, Table, TableHead, TableRow, TableBody, TableCell, Paper, Tooltip, Typography } from '@mui/material';
+import { Alert, Box, CircularProgress, Chip, IconButton, Switch, TableContainer, Table, TableHead, TableRow, TableBody, TableCell, Paper, Tooltip, Typography } from '@mui/material';
 import { useState, useEffect } from 'react';
 import { getCookie } from '../../../src/utils.js';
 import DeleteIcon from '@mui/icons-material/Delete';
 import DragIndicatorIcon from '@mui/icons-material/DragIndicator';
 import ForwardToInboxOutlinedIcon from '@mui/icons-material/ForwardToInboxOutlined';
+
 import { useAppContext } from '../../../src/render.jsx';
 
 
@@ -23,6 +24,8 @@ const ContentTable = ({ courseId, eventHandler, loaded = false }) => {
     const { apiBaseUrl, userRole, localeMessages, direction } = useAppContext();
     const organizationId = localStorage.getItem('activeOrganizationId');
     const canSendLesson = userRole === 'admin' || userRole === 'editor';
+    const showQuizTwoAttemptNote = contentList.some((content) => content.type === 'quiz' && content.limited_attempts == true);
+    const showQuizUnlimitedAttemptsNote = contentList.some((content) => content.type === 'quiz' && content.limited_attempts == false);
 
     const formatPeriod = (period) => {
         if (!period) {
@@ -233,8 +236,11 @@ const ContentTable = ({ courseId, eventHandler, loaded = false }) => {
                         onMouseDown={(event) => startDrag(event, content.id)}
                         /></TableCell>}
                         <TableCell align={direction == 'rtl' ? 'right' : 'left'}><Typography
+                            component="span"
                             onClick={() => {let event = {type: 'content_clicked', content_id: content.id}; eventHandler(event);}}
-                            sx={{ cursor: 'pointer', color: theme => theme.palette.mode === 'dark' ? theme.palette.secondary.main : theme.palette.secondary.dark }}>{content.title}</Typography></TableCell>
+                            sx={{ cursor: 'pointer', color: theme => theme.palette.mode === 'dark' ? theme.palette.secondary.main : theme.palette.secondary.dark }}>{content.title}
+                            {content.limited_attempts !== null &&  ( content.limited_attempts ? <Chip label={localeMessages["two_attempts"]} size="small" sx={(theme) => ({ ml: 1, backgroundColor: theme.palette.mode === 'dark' ? 'rgba(255, 152, 0, 0.15)' : 'rgba(255, 203, 71, 0.5)', color: theme.palette.mode === 'dark' ? '#FF9800' : '#9a4208' })}
+                             /> : <Chip label={localeMessages["unlimited_attempts"]} size="small" sx={(theme) => ({ ml: 1, backgroundColor: theme.palette.mode === 'dark' ? 'rgba(76, 175, 80, 0.15)' : 'rgba(129, 199, 132, 0.5)', color: theme.palette.mode === 'dark' ? '#4CAF50' : '#256029' })} />)}</Typography></TableCell>
                         <TableCell align={direction == 'rtl' ? 'right' : 'left'}>{formatPeriod(content.waiting_period)}</TableCell>
                         <TableCell align={direction == 'rtl' ? 'right' : 'left'}>{localeMessages[content.type]}</TableCell>
                         <TableCell align={direction == 'rtl' ? 'right' : 'left'}><Switch checked={content.is_published}  onChange={() => TogglePublishContent(content.id, !content.is_published)} disabled={userRole == 'viewer'} /></TableCell>
@@ -265,6 +271,30 @@ const ContentTable = ({ courseId, eventHandler, loaded = false }) => {
             </TableBody>
           </Table>
         </TableContainer>
+        {(showQuizTwoAttemptNote || showQuizUnlimitedAttemptsNote) && (
+            <Box
+                sx={{
+                    mt: 1.5,
+                    px: 1.5,
+                    py: 1,
+                    borderRadius: 1,
+                    backgroundColor: 'action.hover',
+                    border: '1px solid',
+                    borderColor: 'divider',
+                }}
+            >
+                {showQuizTwoAttemptNote && (
+                    <Typography component="div" variant="caption" color="text.secondary" sx={{ display: 'block' }}>
+                        • <Box component="span" sx={{ fontWeight: 600 }}>{localeMessages["two_attempts"]}:</Box> {localeMessages["quiz_2_attempts_sub_note"]}
+                    </Typography>
+                )}
+                {showQuizUnlimitedAttemptsNote && (
+                    <Typography component="div" variant="caption" color="text.secondary" sx={{ display: 'block', mt: showQuizTwoAttemptNote ? 0.5 : 0 }}>
+                        • <Box component="span" sx={{ fontWeight: 600 }}>{localeMessages["unlimited_attempts"]}:</Box> {localeMessages["quiz_unlimited_attempts_sub_note"]}
+                    </Typography>
+                )}
+            </Box>
+        )}
         </>
     );
 }