wiki:BoltRef

Version 14 (modified by Nicolas, 17 years ago) (diff)

fix sample PHP code

  1. Bolt reference manual
    1. Lessons
    2. Exercises
    3. Course documents
      1. Changing course documents
      2. Nesting and functions
      3. Logical names and state
    4. Control structures
      1. Sequences
      2. Random
      3. Select
      4. Exercise set
    5. Review
    6. Memory refresh

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.

To use Bolt:

  • create a BOINC project.
  • Put your lessons, exercises and course document in the project's html/user directory
  • Edit and run the html/ops/bolt_setup_sample.php script to create one or more courses.

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

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: 

<?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.',
   ),
);
?>

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. 

<?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 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: 

<?php
return lesson(
    name('lesson 1'),
    title('The ecology of a conifer forest'),
    filename('lesson_1.php'),
    reading_level(11.0),
    detail_level(.5)
);
?>

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 can change over time. In fact, that's the whole point of Bolt: to constantly study the effectiveness of course materials, and change the course based on the results of that study.

If a course changes while students are in the middle of it, 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

Control structures may be nested. For example: 

sequence(
    name("x");
    lesson(...),
    sequence(
        name("y"),
        lesson(...),
        exercise(...)
    )
);

You can also use PHP functions as a way of organizing course structure: 

function my_unit() {
    return sequence(
        name("y"),
        lesson(...),
        exercise(...)
    )
}

sequence(
    name("x"),
    lesson(...),
    my_unit()
);

Logical names and state

In general, units must have unique logical names. However, two units may have the same logical name if they are identical. For example: 

function my_unit() {
    return random(
        name("y"),
        lesson(...),
        lesson(...)
    )
}

return sequence(
    name("x"),
    my_unit(),
    exercise_set(
        name("z"),
        exercise(...),
        review(.5, my_unit())
    )
);

This specifies a course in which my_unit() is displayed, then an exercise is given. If the student scores below .5 on the exercise, he is shown my_unit() again and the exercise is repeated.

So there are two units with logical name 'y' in this course, but they are identical, so this is allowed.

When there are multiple units with the same logical name, they share a single state.

Control structures

Sequences

Sequences were described above.

Random

The random control structure selects randomly from a set of units. 

<?php
return select(
    name('course'),
    lesson(
        name('lesson 1'),
        filename('bolt_sample_lesson1.php')
    ),
    lesson(
        name('lesson 2'),
        filename('bolt_sample_lesson2.php')
    ),
);
?>

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. 

<?php
function value($unit) {
    global $student;
    return abs($student->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

If a refresh() argument is given to exercise_set(), then when the set is completed by a student it is added to a "refresh schedule", to be repeated at a later time. The intervals (in days) are given as arguments to refresh().