[[PageOutline]] = 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 file or PHP script. 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.birth_year; $student.country; $student.name; $student.bandwidth; // 1: <100Kb; 2: <1Mb; 3: <10Mb etc. $student.has_audio_output; // 1: no, 2: yes $student.has_audio_input; }}} For example, suppose you want to use a larger font for students over 50: {{{ if ($student.age > 50) { echo " "; } }}} An alternative way to vary content based on student attributes is to use separate lesson files, selected in the course document. == Exercises == Exercises are PHP scripts that call Bolt API functions. Here's an example consisting of a multiple-choice question: {{{ }}} The correct choice is the first element of the array. Each time the question is shown, the choices are presented in a random order. 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 PHP script called a '''course document'''. The script calls Bolt API functions to create a hierarchy of "units" of two types: * '''Basic units''': lessons and exercises * '''Control structures''' representing sets of units, together with rules the govern their use. The function '''lesson()''' specifies a lesson. For example, the following course consists of a single lesson: {{{ }}} The parameters of the lesson are: || name || the "logical name", used as an internal identifier but not visible to students; see "Names and state" below || || title || a name shown to students || || filename || the file containing lesson content || || reading_level, detail_level || optional attributes of the lesson || Similarly, '''exercise()''' specifies an exercise: {{{ }}} There are various control structures; see below. The simples one is a 'sequence', which specifies a set of units that are shown in sequence. Here's an example of a course with two lessons followed by an exercise: {{{ }}} == Changing course documents == Course documents need not be static. You can change them whenever you want (that's the point of Bolt). What happens if a course changes while students are in the middle of it? The general answer is the Bolt recovers as gracefully as possible. For each student, Bolt maintains a "course state" - a set of data, for each control structure that the student has visited in the course, describing the student's "position" in that control structure. When a student clicks the Next button, or resumes the course after an interval, Bolt uses the course state to decide what item to display next. For example, suppose your course has a sequence with 3 elements, with logical names (red, yellow, blue). and a student is on the third. The course state for the sequence consists of two items: (blue, 2). 'blue' is the logical name of the third element, and the index number 2 (indicates that the student has completed 2 units in the sequence). If the student resumes the course, Bolt will find their place in the sequence first by looking up the logical name; if it is not found, then it will use the index number. For example: * If you change the sequence to (red, blue, green, yellow) then the student will be shown the units blue, green, and yellow. * If you change the sequence to (red, yellow, green) then the student will be shown the unit 'green'. * If you change the sequence to (red, yellow) then the student will have finished the sequence. == Nesting and functions == == Names and state == == Control structures == === Sequences === === Random === The '''random''' control structure selects randomly from a set of units. {{{ }}} === Select === The '''select''' structure takes a set of units and a 'valuator' function. The valuator function returns the 'value' (i.e. the likely benefit) of showing the unit to the student. The unit for which this value is greatest is shown. {{{ verbal_level - $unit->verbal_level); } return select( name('course'), valuator('value'), lesson( name('lesson 1'), filename('bolt_sample_lesson1.php') ), lesson( name('lesson 2'), filename('bolt_sample_lesson2.php') ), ); ?> }}} === Exercise set === The 'exercise_set' structure specifies a set of exercises and a value 'num_to_show'. This number of exercises is chosen randomly and administered. {{{ exercise_set( name('exer_set'), num_to_show(1), exercise( name('exercise 1'), filename('file_1.php') ), exercise( name('exercise 1'), filename('file_1.php') ), review(.3, basic_review()), review(.7, int_review()), refresh(array(7,14,28)) ); }}} == Review == Optionally, one or more '''review''' attributes can be given. Each specifies a grade threshold X and a list of review units. If the student's grade on the exercise set is less than some Y, == Memory refresh ==