= Implementation notes =

== Source code ==

The Bolt source code is part of
[SourceCode the BOINC source code distribution].
The files related to Bolt are:

Include files:

 * [source:trunk/boinc/html/inc/bolt.inc bolt.inc]: implementation of course document functions.
 * [source:trunk/boinc/html/inc/bolt_db.inc bolt_db.inc]: Bolt-specific DB abstraction layer.
 * [source:trunk/boinc/html/inc/db_conn.inc db_conn.inc]: General DB abstraction layer.
 * [source:trunk/boinc/html/inc/bolt_ex.inc bolt_ex.inc]: Exercise API functions.
 * [source:trunk/boinc/html/inc/bolt_util.inc bolt_util.inc]: Miscellaneous HTML.

User-visible files:

 * [source:trunk/boinc/html/user/bolt.php bolt.php]: List of courses.
 * [source:trunk/boinc/html/user/boltcourse_sample.php bolt_course_sample.php]: Example course document.
 * [source:trunk/boinc/html/user/bolt_course.php bolt_course.php]: Home page for a particular course.
 * [source:trunk/boinc/html/user/bolt_sched.php bolt_sched.php]: Scheduler: makes sequencing decisions and adds navigation.

Administrative files:

 * [source:trunk/boinc/html/ops/bolt_refresh.php bolt_refresh.php]: Periodic task to send refresh emails.
 * [source: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.