NAME

parserRadioButtons.pl - Radio buttons compatible with MathObjects, specifically MultiAnswer objects.

DESCRIPTION

This file implements a radio button group object that is compatible with MathObjects, and in particular, with the MultiAnswer object, and with PGML.

To create a RadioButtons object, use

$radio = RadioButtons([choices,...],correct,options);

where "choices" are the strings for the items in the radio buttons, "correct" is the choice that is the correct answer for the group (or its index, 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 radio 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 radio button.

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

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

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

$radio = RadioButtons([["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", "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" then the choices will be labeled with capital letters after they have been randomized. 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 of letter (and the number of letter will be skipped). The third form allows you to specify labels for each of the choices in their random order. If you want to specify the labels for the choices in their original order the { label => text } form must be used.

Default: labels are the text of the choice when they don't include any special characters, and "Button 1", "Button 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.

displayLabels => 0 or 1

Specifies whether labels should be displayed after the radio button 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 radio buttons. Default: $BR

checked => choice

The text or index (starting at zero) of the button 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 radio buttons (if the choice strings are too long, they will be trimmed and "..." inserted) Default: 25

uncheckable => 0 or 1 or "shift"

Determines whether the radio buttons can be unchecked (requires JavaScript). To uncheck, click a second time; when set to "shift", unchecking requires the shift key to be pressed. Default: 0

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

The following options are deprecated, but are available for backward compatibility. This functionality can now be accomplished though grouping the items in the choice list.

randomize => 0 or 1

Specifies whether the order of the choices should be randomized or not. By default, the order is exactly as they appear in the choices array. If you select random order, you can use the first and last arrays to help organize the choices.

order => [choice,...]

Specifies the order in which choices should be presented. All choices must be listed. If this option is specified, the first and last options are ignored. The order can be given in terms of the indices of the choices (0 is the first one), or as the strings themselves.

first => [choice,...]

Specifies choices which should appear first, in the order specified, in the list of choices. Ignored if the order option is specified. The entries in this list are either indices of the choices (0 is the first one), or the strings themselves.

last => [choice,...]

Specifies choices which should appear last, in the order specified, in the list of choices. Ignored if the order option is specified. The entries in this list are either the indices of the choices (0 is the first one), or the strings themselves.

To insert the radio buttons into the problem text, use

BEGIN_TEXT
\{$radio->buttons\}
END_TEXT

and then

ANS($radio->cmp);

to get the answer checker for the radio buttons.

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

When writing a custom answer checker involving a RadioButtons 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 RadioButtons 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 radio button 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.