Overview of the Moodle question engine
- Goals
- Rationale
- How it currently works
- New system overview
- Detailed design
- Question Engine 2 Developer docs:
- Implementation plan
- Testing
This page summarises how the new question engine works.
Previous section: Design
Note: This page is a work-in-progress. Feedback and suggested improvements are welcome. Please join the discussion on moodle.org or use the page comments.
What does a question engine have to do?
We are in a question engine for online assessment. Clearly, we have questions, but we don't need to worry about them much here, they come from the question bank. We can take them as given.
We are really interested in what happens when a student attempts some questions (for example, when they attempt a quiz). We can handle this by thinking about the student's attempt at each question separately, and then aggregate those separate question attempts into the set of those that comprise the student's attempt at a particular activity.
For each question attempt, we need some notion of what state it is currently in (in-progress, completed correctly, ...) whether it has been graded, and if so, what mark was awarded. Also, there may be some state private to the question when it is started. For example the calculated question assigns random values to each variable when the question is attempted, and the choices for a multiple choice question may be shuffled.
Given the current state of a question, we need to be able to display it in HTML. The question may need to be displayed in various ways. For example, perhaps students are not allowed to see the information about the grades awarded yet, but if a teacher reviews it they should see the grades. Teachers may also need to see other bits of interface, like edit links. There may be one or more questions displayed embedded in a particular HTML page, for example a page of a quiz attempt.
Finally, the question needs to move from one state to another. There two sorts of way that can happen. First, the student may have interacted with some questions that have been displayed as part of a HTML page, and then submitted that page. That is, the question engine needs to directly process data submitted as part of a HTTP POST request. Second, the student may have performed some other action (for example clicked the Start attempt or Submit all and finish buttons in the quiz), and as a result, some other part of the Moodle code may wish to cause some questions to change state.
Not only to we need to consider the current state of each question. We also need a record of the whole history of what happened. For example a teacher may wish to review everything the student did. Or, when we regrade an interactive question, we need to play back the entire sequence of what the student did.
To be flexible, the question engine needs to cope with any question-type plug-in. It also needs to be flexible in the ways questions behave. For example some questions can only be graded manually by a teacher. Automatically graded questions can be configured to behave in different ways, for example in interactively with immediate feedback and multiple tries during a single question attempt, or with deferred feedback, where the questions are only graded when the student does submit all and finish.
The state of a question
As noted above, a key issues is representing the state of a question that is being attempted, and, indeed, the complete history of the states it has passed through. This is the responsibility of the question_attempt class. As we have noted, a ...
TODO
Within the quiz/question engine system we have to deal with three different types of grade/score/mark/whatever.
For any activity, say a quiz, it will eventually calculate a grade that is passed to the gradebook. For example, the quiz grade may be out of 100.
Within the quiz, there will be a number of questions. Let us suppose there are 6 questions each worth 3 marks, and 1 question worth 2 marks. Therefore, the quiz is out of 20 marks, and the student's mark is multiplied by 5 to get a grade out of 100 that is sent to the gradebook.
Finally, at the lowest level of the quiz, grades are stored on a scale of 0..1. We call this a fraction. So the student's mark for a question is their fraction, multiplied by the maxmark for the question. We do this so that it is easy to do things like change how many marks a question is worth within a quiz.
Therefore, we have the three words fraction, mark and grade that should be used consistently throughout the question engine code. Fractions are rarely shown in the user interface*, while I believe the quiz UI already uses the marks/grades terminology consistently.
When used as a verb - to assign a grade/mark/fraction - as in grade_response, regrade or manual_grade, the work grade is always used.
* the one place where fraction is displayed in the UI is on the question editing screens, where you set the 'grade' for a particular answer on a scale of 0 to 100%.
Key classes
TODO
Database tables
TODO
Key processes
These two sequence diagrams summarise what happens during the two key operations, displaying a page of the quiz, and processing the student's responses.
See also
In the next section, Developing a Question Interaction Model I describe what a developer will need to do to create a Question Interaction Model plugin for the new system.
- Back to Question Engine 2
