NAME

parserCheckboxList.pl - Multiple choice checkbox answers compatible with MathObjects, MultiAnswer objects, and PGML.

DESCRIPTION

This file implements a multiple choice checkbox object that is compatible with MathObjects, and in particular, with the MultiAnswer object, and with PGML.

To create a CheckboxList object, use

$checks = CheckboxList([choices, ...], [correct_choices, ...], options);

where "choices" are the label value strings for the checkboxes, "correct_choices" are the choices that are the correct answers (or their indices, with 0 being the first one), and options are chosen from among those listed below. If the correct answer is a number, it is interpreted as an index, even if the array of choices are also numbers. (See the noindex below for more details.)

The entries in the choices array can either be strings that are the text to use for the choice buttons, or { label => text } where label is a label to use for the choice when showing the student or correct answers and text is the text to use for the choice, or { label => [ text, value ] } where label and text are as described above and value is the value to for the checkbox input for this choice.

See below for options controlling how the labels will be used. If a choice includes mathematics, you should use labels as above or through the labels option below in order to have the student and correct answers display properly in the results table when an answer is submitted. Use the displayLabels option to make the labels be part of the choice as it is displayed following the checkbox.

The values set as described above are the answers that will be displayed in the past answers table. See the values option below for more information. Problem authors are encouraged to set these values either as described above, or via the values option. This is useful for instructors viewing past answers.

By default, the choices are left in the order that you provide them, but you can cause some or all of them to be ordered randomly by enclosing those that should be randomized within a second set of brackets. For example

$checks = CheckboxList(
    [
        "First Item",
        [ "Random 1", "Random 2", "Random 3" ],
        "Last Item"
    ],
    ["First Item", "Random 3"]
);

will make a list of checkboxes that has the first item always on top, the next three ordered randomly, and the last item always on the bottom. In this example

$checks = CheckboxList([[ "Random 1", "Random 2", "Random 3" ]], 2);

all the entries are randomized, and the correct answer is "Random 3" (the one with index 2 in the original, unrandomized list). You can have as many randomized groups, with as many static items in between, as you want.

The options are taken from the following list:

labels => "123", "abc", "ABC", "roman", "Roman", "text", or [label1, ...]

Labels are used to replace the text of the choice in the student and correct answers, and can also be shown just before the choice text (if displayLabels is set). If the value is "123" then the choices will be labeled with numbers (the choices will be numbered sequentially after they have been randomized). If the value is "abc" or ABC" then the choices will be labeled with lowercase or capital letters after they have been randomized. You can only have up to 26 choices. If the value is "roman" or "Roman" then the choices will be labeled with lowercase or capital Roman numerals, also capped at 26 for symmetry. If the value is "text" then the button text is used (note, however, that if the text contains things like math or formatting or special characters, these may not display well in the student and correct answer columns of the results table).

If any choices have explicit labels (via { label => text }), those labels will be used instead of the automatic number or letter (and the number or letter will be skipped). The [label1, ...] form allows you to specify labels for each of the choices in their original order (though the { label => text } form is preferred).

Default: labels are the text of the choice when they don't include any special characters, and "Choice 1", "Choice 2", etc., otherwise.

values => array reference

Values are the form of the student answer that will be displayed in the past answers table for this answer. By default these are B0, B1, etc. However, that can be changed either with this option or by specifying the choices with { label => [ text, value ] } as described previously. If this option is used, then the value of the option should be a reference to an array containing the values for the choices. For example:

values => [ 'first choice', 'second choice', ... ]

If a choice is not represented in the hash, then Bn will be used for the value instead where n is the 0 based index of the choice.

These values can be any descriptive string that is unique for the choice, but care should be taken to ensure that these values do not indicate which choice is the correct answer.

Note that values given via { label => [ text, value ] } will override any values given by this option if both are provided for a particular choice.

Also note that due to the way that checkbox values are passed in HTML forms, all checked values will be concatenated into a single string for the original student answer with no separator. So it is advisable to end each value with a comma or semicolon to provide a separator for the parts of the answer that were checked.

displayLabels => 0 or 1

Specifies whether labels should be displayed after the checkbox and before its text. This makes the association between the choices and the label used as an answer more explicit. Default: 1

labelFormat => string

Specifies a format string to use when displaying labels before the choice text. It is an sprintf string that contains %s where the label should go. By default, it is ${BBOLD}%s. ${EBOLD}, which produces the label in bold followed by a period and a space.

forceLabelFormat => 0 or 1

When displayLabels is set, this controls how blank labels are handled. When set to 0, no label is inserted before the choice text for blank labels, and when 1, the labelFormat is applied to the empty string and the result is inserted before the choice text. Default: 0.

separator => string

Specifies the text to put between the checkboxes. Default: $BR

checked => choice

A list of texts or indices (starting at zero) of the checkboxes to be checked initially. Default: [] (none checked)

maxLabelSize => n

The approximate largest size that should be used for the answer strings to be generated by the checkboxes (if the choice strings are too long, they will be trimmed and "..." inserted) Default: 25

noindex => 0 or 1

Determines whether a numeric value for the correct answer is interpreted as an index into the choice array or not. If set to 1, then the number is treated as the literal correct answer, not an index to it. Default: 0

showInStatic => 0 or 1 In static output, such as PDF or PTX, this controls whether or not the list of answer options is displayed. (The text preceding the list of answer options might make printing the answer option list unnecessary in a static output format.) Default: 1

To insert the checkboxes into the problem text use

BEGIN_PGML
[_]{$checks}
END_PGML

with PGML, or

BEGIN_TEXT
\{$checks->checks\}
END_TEXT

ANS($checks->cmp);

with basic PG.

You can use the CheckboxList object in MultiAnswer objects. This is the reason for the CheckboxList's ans_rule method (since that is what MultiAnswer calls to get answer rules). Just pass a CheckboxList object as one of the arguments of the MultiAnswer constructor.

When writing a custom answer checker involving a CheckboxList object (e.g. if it is part of a MultiAnswer and its answer depends on, or affects, the answers given to other parts), note that the actual answer strings associated to a CheckboxList object (which are those appearing in the "student answer" argument passed to a custom answer checker) are neither the supplied choice strings nor the supplied labels, but are the checkbox input values. These are the values given by the values option or { label => [ text, value ] } choice format if provided. Otherwise they are an internal implementation detail whose format should not be depended on. In any case, you can convert these value strings to a choice string or a label with the methods answerChoice or answerLabel.