NAME

parserPopUp.pl - Drop-down lists compatible with MathObjects, specifically MultiAnswer objects.

DESCRIPTION

This file implements drop-down select objects that are compatible with MathObjects, and in particular, with the MultiAnswer object, and with PGML.

To create a PopUp, DropDown, or DropDownTF object, use

$popup     = PopUp([ choices, ... ], correct, options);
$dropdown  = DropDown([ choices, ... ], correct, options);
$truefalse = DropDownTF(correct, options);

where "choices" are the items in the drop-down list, "correct" is the 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.)

Note that drop-down menus can not contain mathematical notation, only plain text. This is because the browser's native menus are used, and these can contain only text, not mathematics or graphics.

The difference between PopUp() and DropDown() is that in HTML, the latter will have an unselectable placeholder value. This value is '?' by default, but can be customized with a placeholder option.

DropDownTF() is like DropDown with options being localized versions of "True" and "False". 1 is understood as "True" and 0 as "False". The initial letter of the localized word is understood as that word if those letter are different. All of this is not case sensitive. Also, in static output (PDF, PTX) showInStatic defaults to 0. It is assumed that text preceding the drop-down makes the menu redundant.

The entries in the choices array can either be the actual strings to be used in the drop-down menu (which is known as a "label" for the option input in HTML) or { label => value } where label is the text string to display in the drop-down list and value is the value to for the option input for this choice. The "value" is what is actually submitted when a student submits an answer, and this is what will appear in the past answers table, feedback messages, etc. If an option is not set as a hash in this way, the text of the option serves as both the label and the value.

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

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

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

$dropdown = DropDown([ [ "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 flattened list). You can have as many randomized groups as you want, with as many static items in between.

The options are taken from the following list:

values => array reference

Values are the form of the student answer that is actually submitted when the student submits an answer. They will be displayed in the past answers table for this answer, appear in feedback messages, etc. By default these are the option text (aka the option label). However, that can be changed either with this option or by specifying the choices as { label => value } as described previously. If this option is used, then it must be set as a reference to an array containing the values for the options. For example:

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

If a choice is not represented in the hash, then the option text will be used for the value instead.

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 => value } will override any values given by the values option if both are provided for a particular choice.

noindex => 0 or 1

Determines whether or not a numeric value for the correct answer is interpreted as an index for 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

placeholder => string

If nonempty, this will be the first option in the drop-down list. It will be unselectable and grayed out, indicating that it is not an option the user can/should actually select and submit. Default: '' for PopUp, '?' for DropDown and DropDownTF

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, except 0 for DropDownTF.

To insert the drop-down into the problem text when using PGML:

BEGIN_PGML
[_]{$dropdown}
END_PGML

Or when not using PGML:

BEGIN_TEXT
\{$dropdown->menu\}
END_TEXT

and then to get the answer checker for the drop-down:

ANS($dropdown->cmp);

You can use the PopUp, DropDown, and DropDownTF object in MultiAnswer objects. This is the reason for the ans_rule() method (since that is what MultiAnswer calls to get answer rules). Just pass the object as one of the arguments of the MultiAnswer constructor.

When writing a custom answer checker involving a PopUp, DropDown, or DropDownTF 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 one of these objects (which are those appearing in the "student answer" argument passed to a custom answer checker) are not the supplied option text (aka the labels), but rather they the option values. These are the values given by the values option or { label => 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 (aka label string) with the method answerLabel.