Changes between Version 9 and Version 10 of BoltRef


Ignore:
Timestamp:
Dec 12, 2007, 10:09:56 PM (17 years ago)
Author:
davea
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • BoltRef

    v9 v10  
    4343}}}
    4444
    45 Note: an alternative way to vary content based on student attributes is
     45An alternative way to vary content based on student attributes is
    4646to use separate lesson files, selected in the course document.
    4747
     
    8282An exercise can include multiple questions.
    8383
    84 
    8584== Course documents ==
    8685
    87 The structure of a Bolt course is defined by a PHP script.
    88 The script calls Bolt API functions to create a hierarchy of "units".
    89 Each unit has a "name", used to identify the unit within the course
    90 (it is now shown to students).
    91 
    92 The basic types of units are lessons and exercises.
    93 Each has accompanying filename.
     86The structure of a Bolt course is defined by a PHP script called a '''course document'''.
     87The script calls Bolt API functions to create a hierarchy of "units" of two types:
     88
     89 * '''Basic units''': lessons and exercises
     90 * '''Control structures''' representing sets of units, together with rules the govern their use.
     91
     92The function '''lesson()''' specifies a lesson.
    9493For example, the following course consists of a single lesson:
    9594{{{
     
    105104}}}
    106105
     106The parameters of the lesson are:
     107|| name || the "logical name", used as an internal identifier but not visible to students; see "Names and state" below ||
     108|| title || a name shown to students ||
     109|| filename || the file containing lesson content ||
     110|| reading_level, detail_level || optional attributes of the lesson ||
     111
     112Similarly, '''exercise()''' specifies an exercise:
     113{{{
     114<?php
     115return exercise(
     116    name('exercise 1'),
     117    filename('bolt_sample_exercise1.php')
     118);
     119?>
     120}}}
     121
     122There are various control structures; see below.
     123The simples one is a 'sequence',
     124which specifies a set of units that are shown in sequence.
     125Here's an example of a course with two lessons followed by an exercise:
     126{{{
     127<?php
     128return sequence(
     129    name('course'),
     130    lesson(...),
     131    lesson(...),
     132    exercise(...),
     133);
     134?>
     135}}}
     136
     137== Changing course documents ==
     138
     139Course documents need not be static.
     140You can change them whenever you want (that's the point of Bolt).
     141
     142What happens if a course changes while
     143students are in the middle of it?
     144The general answer is the Bolt recovers as gracefully as possible.
     145For each student, Bolt maintains a "course state" - a set of data,
     146for each control structure that the student has visited in the course,
     147describing the student's "position" in that control structure.
     148When a student clicks the Next button, or resumes the course after an interval,
     149Bolt uses the course state to decide what item to display next.
     150
     151For example, suppose your course has a sequence with 3 elements,
     152with logical names (red, yellow, blue).
     153and a student is on the third.
     154The course state for the sequence consists of two items: (blue, 2).
     155'blue' is the logical name of the third element, and the index number 2
     156(indicates that the student has completed 2 units in the sequence).
     157
     158If the student resumes the course, Bolt will find their place in
     159the sequence first by looking up the logical name;
     160if it is not found, then it will use the index number.
     161For example:
     162 * If you change the sequence to (red, blue, green, yellow) then the student will be shown the units blue, green, and yellow.
     163 * If you change the sequence to (red, yellow, green) then the student will be shown the unit 'green'.
     164 * If you change the sequence to (red, yellow) then the student will have finished the sequence.
     165
    107166== Nesting and functions ==
    108167
     168
     169
    109170== Names and state ==
     171
    110172
    111173== Control structures ==
    112174=== Sequences ===
    113175
    114 Course documents can also have various 'control structures'.
    115 The most basic of these is a 'sequence',
    116 which contains a set of units that are shown in sequence.
    117 Here's an example of a course with two lessons followed by an exercise:
    118 {{{
    119 <?php
    120 return sequence(
    121     name('course'),
    122     lesson(
    123         name('lesson 1'),
    124         filename('bolt_sample_lesson1.php')
    125     ),
    126     lesson(
    127         name('lesson 2'),
    128         filename('bolt_sample_lesson2.php')
    129     ),
    130     exercise(
    131         name('exercise 1'),
    132         filename('bolt_sample_exercise1.php')
    133     ),
    134 );
    135 ?>
    136 }}}
     176
    137177
    138178=== Random ===