= Bolt implementation notes =

== Source code ==

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

Include files:

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

User-visible files:

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

Administrative files:

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

== Structures ==

=== Database tables ===

|| Table name || What it represents ||
|| bolt_user || A student, their demographic info, and project-defined attributes ||
|| bolt_course || A course, and the name of its course structure file ||
|| bolt_enrollment || A student taking a course, and the ID of their last view ||
|| bolt_view || A view of an item, created when we show the item, and finalized when the student clicks on something ||
|| bolt_result || The result of a single exercise ||
|| bolt_xset_result || The result of a completed exercise set ||
|| bolt_select_finished || The completion of a select structure ||
|| bolt_refresh || The refresh/repeat of an exercise set, either pending or in progress ||
|| bolt_question || A question asked by a student ||

Each table has a corresponding PHP class with names like BoltUser etc.

=== PHP "unit" class hierarchy ===

A "course structure" is a tree of objects of the following types:

 * !BoltUnit
  * !BoltItem
   * !BoltLesson
   * !BoltExercise
  * !BoltSet
   * !BoltRandom
    * !BoltExerciseSet
   * !BoltSelect

Each !BoltUnit implements an abstract interface (see below).

=== Course state ===

A '''course state''' represents a student's position in a course.
It consists of an array that maps unit names to '''unit state''' structures.
The contents of a unit state structure depends on the unit.
Typically it includes the name of the current child,
and its order in the unit's subunits.

A course state is like a call stack,
and unit states are like stack frames.
One difference: a course state can include records for units
that the student is not currently in.

Each !BoltView record contains the course state when the view started.

=== !BoltIter ===

This object is the central data structure of the Bolt scheduler.
It includes:

'''top''': the root of the course structure.

'''state''': the course state (from the latest !BoltView record).

'''xset''': the xset we're currently in, if any.

'''item''': the current item

'''frac_done''': fraction of course completed so far

Its member functions are:

'''at()''': get current item and fraction done

'''next()''': move to next item

These are both implemented by calling walk() on the root unit.

=== The interface of !BoltUnit ===

!BoltUnit has an abstract function
{{{
walk(&$iter, $incr, &$frac_done);
}}}
where $iter is a !BoltIter object (see below).
It is implemented in different ways in the different derived classes.
For !BoltSet it does the following:

 * If there's no unit state record in the course state, set an initial state.
 * Otherwise, look up the current child unit, first by name, then by array index.
 * Add or replace a unit state record in the $iter->state
 * If child is a !BoltItem, set $iter->item; otherwise call child->walk().