diff options
Diffstat (limited to 'doc/quiz-api.rst')
| -rw-r--r-- | doc/quiz-api.rst | 113 |
1 files changed, 42 insertions, 71 deletions
diff --git a/doc/quiz-api.rst b/doc/quiz-api.rst index ba7e212..5ce1634 100644 --- a/doc/quiz-api.rst +++ b/doc/quiz-api.rst @@ -1,11 +1,8 @@ -.. vim:filetype=rst:tw=76: - -================================= Sugar Quiz API Preliminary Design ================================= Motivation -========== +---------- In the RIT class working on the Math4 projects, many proposed activities require a question database of some kind. A common API or library for @@ -21,7 +18,7 @@ grouping, difficulty, and subject matter that would be part of the base system. Envisioned Usage -================ +---------------- Consider a simple flash-card-like activity. It presents a question from a list of questions, allows the student to select an answer from the provided @@ -30,7 +27,7 @@ answer is revealed and the student it told whether their answer is correct. If the question has an explanation of the correct answer, the flash-card activity will show the explanation of the correct answer. (Note that this is just a simple usage example, the interaction design of a drilling -activity could be markedly different.) +activity could be very different.) The flash-card activity would use this proposed Quiz API for the following: @@ -41,9 +38,6 @@ The flash-card activity would use this proposed Quiz API for the following: - Determining whether the student has entered a correct answer. - - Rendering the question to a simple widget/canvas. (i.e. pass the - library a GtkCanvas or similar and tell it to display the question) - To start with, the library would simply be a time-saving tool for developers needing similar functionality, but as the XS (School Server) becomes more fully developed the library should integrate the functions provided by the @@ -52,23 +46,22 @@ study so the students can drill material using any tool they prefer, while still reporting progress to the instructor using the XS services. Proposed API -============ +------------ -The Quiz API would be a python library, to act mostly as glue between -various file formats (and local or remote resources) for question data and -the Gtk graphical environment, providing a simple way to consistently -present and layout questions. +The Quiz API would be a python library, to act mostly as glue between various +file formats (and local or remote resources) for question data and the client +Activity. :quizdata.open(uri, [cache=False]): Opens a URI, returning a list of quizdata.Question instances. A standard method of filtering question data based on parameters should be specified. Examples of URIs that might be used:: - http://xs-server/math4class/current_topic?level=4&difficulty=hard&format=moodle + http://xs-server/math4class/current_topic?format=gift - file:///var/lib/mathquestions/quiz1?level=4&difficulty=hard&format=xml + file:///var/lib/mathquestions/quiz1?format=moodlexml - xmpp://teacheraccount@xs.server/classname?difficulty=hard&level=4 + xmpp://teacheraccount@xs.server/classname?format=gift&difficulty=hard&level=4 The cache parameter would locally save the retrieved questions to a persistent storage so requests from the same URI (with cache=True) @@ -79,8 +72,9 @@ present and layout questions. - The question text - The style of answer (incl. multiple-choice, numeric, free response, etc.) - - The correct answer (or if the question is subjective, that - there *is* no correct answer). + - The correct answer (or if the question is subjective, that there + *is* no correct answer). This includes answers for which the + student may receive partial credit. - Question difficulty - Grade level - Tags (for free-form grouping by topic, course, instructor, @@ -88,68 +82,45 @@ present and layout questions. The question text and answers should support at least minimal markup, like that supported by pango, in addition to markup - rendering with MathML/LaTeX syntax. + rendering with MathML/LaTeX syntax. (This requires a markup_type + parameter of some kind.) .. note:: The attributes listed above will should grow standardized names and be documented as part of the interface to the Question - class, to allow for fine-grained for activity controlled - rendering of the Question, if the simple show() call is not - appropriate. - - :Question.show(surface, x, y, [width=-1, [height=-1]]): - Draw the question to the drawing surface at coordinates (x,y) - limited to the optionally specified width/height. - - This also should set up the appropriate input widgets for the - type of question (multiple-choice/free-response) and handle the - vents for those widgets. - - :Question.response: - The answer the student has currently selected, or None if no - answer has been entered. - - :Question.submitted: - True if the student has submitted an answer for the Question, - False otherwise. + class. - :Question.answered(): + :Question.answered: Returns True if the student has provided an answer for the Question. - :Question.correct(): + :Question.submitted: + Returns True if the student has submitted an answer for the + Question. XXX: Useful to make a distinction between answered and + submitted? + + :Question.correct: Returns True if the currently selected answer is correct for the - Question. + Question. XXX: What to do about partial credit? Value between 0 and + 1? - :Question.clear(): - Removes the widgets and drawings that show() set up, preparing - the surface to receive the next question or other widgets. + :Question.answer: + Returns the answer the student has currently selected, or None + if no answer has been entered. Implementation Issues -====================== - -The implementation of this (deceptively simple) library will take some -effort, in that it will be closely tied to the windowing/graphical toolkit, -PyGtk/Cairo/Pango rather directly, due to the high level of abstraction. -Additionally the URI lookup and question filtering based on parameters will -be necessary, as will interpreter the various format parsers necessary to -build the Question objects. - -For MathML support, the GtkMathView widget will need to be available, so a -certain amount of effort may be involved in packaging the library in a -simple way for activity developers. - -Next Steps -========== - -Firstly, this API is being proposed and posted to the Math4 mailing list for -feedback and changes before any commitments to this interface is decided. -For any activity developers who are currently working on an activity that -could take advantage of such a system, or who have written similar -functionality in an activity, your input on usage and the naturalness of the -API. - -Secondly, anyone who is interested in doing work on this library or using -the library in their activity should chime in, along with the expected usage -or how you can contribute. +---------------------- + +The URI lookup and question filtering based on parameters will be necessary. +Further design and discussion is required. + +Parsing the various format parsers necessary to build the Question objects. + +For markup support, some simple way to give the client activities and easy way +to display it would be desirable. (Restrict the list of markup formats? Require +supplying plain text in addition?) + +.. note:: + File URI handling right now is weird, as the python urlparse stuff doesn't + parse file:// scheme URI's with query parameters. |