Changes between Version 1 and Version 2 of BoltImpl

Timestamp:

Dec 17, 2007, 8:48:30 AM (16 years ago)

Author:

davea

Comment:

--

BoltImpl

@@ -1 @@
-== Identification of course elements ==
+= Implementation notes =
 
-A course can change over time.
-Elements (lessons, exercises, sets) may be added, deleted, or reordered.
+== Source code ==
 
-A student has a "context" in a course - a sequential position,
-and a set of review items.
-What if the course changes, and these items change or disappear?
+The Bolt source code is part of
+[SourceCode the BOINC source code distribution].
+The files related to Bolt are:
 
-Each element may be given a "logical name".
-For items, this defaults to the file name.
+Include files:
 
-A user's sequential position is stored in the DB as the logical name
-or last item viewed.
-On continuation, Bolt looks up that item.
+ * [/trac/browser/trunk/boinc/html/inc/bolt.inc bolt.inc]: implementation of course document functions.
+ * [/trac/browser/trunk/boinc/html/inc/bolt_db.inc bolt_db.inc]: Bolt-specific DB abstraction layer.
+ * [/trac/browser/trunk/boinc/html/inc/db_conn.inc db_conn.inc]: General DB abstraction layer.
+ * [/trac/browser/trunk/boinc/html/inc/bolt_ex.inc bolt_ex.inc]: Exercise API functions.
+ * [/trac/browser/trunk/boinc/html/inc/bolt_util.inc bolt_util.inc]: Miscellaneous HTML.
 
-== Implementation notes ==
+User-visible files:
 
-At the implementation level, an exercise has three functions:
+ * [/trac/browser/trunk/boinc/html/user/bolt.php bolt.php]: List of courses.
+ * [/trac/browser/trunk/boinc/html/user/boltcourse_sample.php bolt_course_sample.php]: Example course document.
+ * [/trac/browser/trunk/boinc/html/user/bolt_course.php bolt_course.php]: Home page for a particular course.
+ * [/trac/browser/trunk/boinc/html/user/bolt_sched.php bolt_sched.php]: Scheduler: makes sequencing decisions and adds navigation.
 
- * When invoked with $mode_show set, it shows the exercise.
- * When invoked with $mode_score set, it computes a score based on the responses stored in $_GET, and assigns the score to $score.  Its text output, if any, is ignored.
- * When invoked with $mode_answer, it shows and "answer sheet" based on the responses stored in $_GET.  If the response is correct and no answer sheet is to be shown, it sets $no_answer_sheet.
+Administrative files:
 
-Bolt's exercise primitives perform all these functions for you;
-however, you're free to implement your own exercises.
+ * [/trac/browser/trunk/boinc/html/ops/bolt_refresh.php bolt_refresh.php]: Periodic task to send refresh emails.
+ * [/trac/browser/trunk/boinc/html/ops/bolt_setup_sample.php bolt_setup_sample.php]: Example script to create a course.
+
+== How exercises are implemented ==
+
+The following information is intended for those who want to add new exercise types.
+
+An exercise is a function that is called with three global variables:
+
+ * '''$bolt_ex_mode'''
+ * '''$bolt_ex_index'''
+ * '''$bolt_ex_score'''
+
+If '''$bolt_ex_mode''' is BOLT_MODE_SHOW, the function should display the exercise,
+typically generating some "form" input items.
+'''$bolt_ex_index''' is a sequential index (0, 1, ...) indicating the order of this
+question in a file containing multiple questions;
+it should be included in form variable names.
+
+If '''$bolt_ex_mode''' is BOLT_MODE_SCORE, the function should score the student's response
+(based on $_GET values) and should store the result (a floating-point number in [0..1])
+in '''$bolt_ex_score'''.
+
+If '''$bolt_ex_mode''' is BOLT_MODE_ANSWER, the function should display an "answer page"
+that shows the students the correct answers,
+and whether the student's responses were right or wrong.