wiki:BoltRef

Version 3 (modified by davea, 17 years ago) (diff)

--

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 <html> or <body> 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 "<style>
        body {font-size: large;}
        </style>
    ";
}

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: 

<?php
echo 'Conifers are so named because:';
bolt_exclusive_choice(
   array(
      'They carry their seeds in cones.'
      'They are cone-shaped.',
      'They originated during the Coniceous era.',
   ),
);
?>

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. 

<?php
echo "Click on the dog's nose:<p>";
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 ​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.