Changes between Version 9 and Version 10 of BoltRef

Timestamp:

Dec 12, 2007, 10:09:56 PM (16 years ago)

Author:

davea

Comment:

--

BoltRef

@@ -43 +43 @@
 }}}
 
-Note: an alternative way to vary content based on student attributes is
+An alternative way to vary content based on student attributes is
 to use separate lesson files, selected in the course document.
 
@@ -82 +82 @@
 An exercise can include multiple questions.
 
-
 == Course documents ==
 
-The structure of a Bolt course is defined by a PHP script.
-The script calls Bolt API functions to create a hierarchy of "units".
-Each unit has a "name", used to identify the unit within the course
-(it is now shown to students).
-
-The basic types of units are lessons and exercises.
-Each has accompanying filename.
+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:
 {{{
@@ -105 +104 @@
 }}}
 
+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:
+{{{
+<?php 
+return exercise(
+    name('exercise 1'),
+    filename('bolt_sample_exercise1.php')
+);
+?>
+}}}
+
+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:
+{{{
+<?php
+return sequence(
+    name('course'),
+    lesson(...),
+    lesson(...),
+    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 ===
 
-Course documents can also have various 'control structures'.
-The most basic of these is a 'sequence',
-which contains a set of units that are shown in sequence.
-Here's an example of a course with two lessons followed by an exercise:
-{{{
-<?php
-return sequence(
-    name('course'),
-    lesson(
-        name('lesson 1'),
-        filename('bolt_sample_lesson1.php')
-    ),
-    lesson(
-        name('lesson 2'),
-        filename('bolt_sample_lesson2.php')
-    ),
-    exercise(
-        name('exercise 1'),
-        filename('bolt_sample_exercise1.php')
-    ),
-);
-?>
-}}}
+
 
 === Random ===