Changes between Initial Version and Version 1 of BoltRef

Timestamp:

Dec 3, 2007, 8:58:18 PM (16 years ago)

Author:

davea

Comment:

--

BoltRef

@@ +1 @@
+== 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 [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.