From WeBWorK

Jump to: navigation


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 interpretted 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. 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.

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 choiced have explicit labels (via {label=text}>), those labels will be used instead of the automatic numberof letter (and the number of letter will be skipped). The third 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 "Button 1", "Button 2", etc. otherwise.

displayLabels => 0 or 1

Specifies whether labels should be displayed after the radio butten 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 ot 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 interpretted 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

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 radion 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).