= Bolt reference manual = A Bolt course consists of: * '''Lessons''': any web-based teaching material * '''Exercises''', used for reinforcement and/or assessment. * A '''course document''' describing the order in which lessons and exercises are shown. == Lessons == A '''Lesson''' contains instructional material. It may be either an HTML or PHP file. It may contain embedded audio, video, Flash, or any other content. Some restrictions: * It shouldn't contain enclosing or tags (Bolt will supply these, as well as navigational header and footer). * It shouldn't contain any hyperlinks (Bolt will supply navigational links). If a lesson is implemented as a PHP script, information about the student is available to it in a global variable $student, This information may be used to customize the page. The available information is: {{{ $student.sex; // 0=unknown, 1=male, 2=female $student.age; // in years $student.country; }}} For example, suppose you want to use a larger font for students over 50: {{{ if ($student.age > 50) { echo " "; } }}} Note: an alternative way to vary content based on student attributes is to use separate lesson files, selected in the course document. == Creating exercises == A Bolt exercise is a PHP script. Here's an example consisting of a multiple-choice question: {{{ }}} Each time the question is shown, the choices are shown in a random order. The correct choice is the first element of the array. Here's an example that shows an image; a correct answer is a click in the indicated subrectangle. {{{ "; bolt_image_rect( 'dog.jpg', array(100, 60, 110, 70) ); ?> }}} Bolt supplies functions for other types of questions, such as inclusive multiple-choice and fill-in-the-blank. An exercise can include multiple questions. == Course documents == The structure of a Bolt course is defined by a [RFC:4627 JSON] document. Here's an example of a course with two lessons followed by an exercise: {{{ { "name": "Identifying Sierra Conifers", "description: "Learn to identify the major conifers of California's Sierra Nevada", "items": [ { "type": "lesson", "name": "Introduction", "file": "intro.html" }, { "type": "lesson", "name": "The Linnaean hierarchy", "file": "linnaean.html" }, { "type": "exercise", "file": "linnaean.php" } ] } }}} Course items can be grouped into '''sets'''; for example: {{{ { "type": "set", "show_n": 1, "order": "random", "items": { { ... } } } }}} The attributes of a set include: * show_n: the number of items in the set to show * order: whether to show the items sequentially or randomly Items (lessons, exercises, and sets) can include '''properties''', e.g.: {{{ { "type": "lesson", "name": "The Linnaean hierarchy", "file": "linnaean.html" "properties": { "verbal_level": 12, "detail_level": 0.8 } }, }}} When Bolt has a choice of items (e.g. when it encounters a set from which a single item is to be shown) it calls, for each item, a course-supplied '''matchmaking function''', passing to it the student object (which includes demographics such as age) and the item's properties (represented as a PHP object). The matchmaking function returns a number representing the estimated effectiveness of that item for that student, and Bolt chooses the item with the highest value. == Memory refresh == Bolt offers a ''memory refresh'' system that periodically repeats exercises and, if necessary, lessons. Memory research suggests that this is necessary for students to shift learning to long-term memory. This mechanism works as follows: * A sequence of ''inter-refresh intervals'' is defined. For example, (7, 28) means that an exercise should be repeated 7 days after it is first taken, and then every 28 days thereafter. * Bolt provides a function that returns the set of items, for a given student, for which refresh is due. Your course can use this function to implement a "Review now" button on web pages. * Bolt provides a "review mode" in which the student is presented with exercises due for review.