NAME

draggableSubsets.pl - Creates visual items that can be dragged into various buckets.

DESCRIPTION

This macro helps the instructor create a drag-and-drop environment in which a pre-specified set of elements may be dragged to different "buckets", effectively partitioning the original set into subsets.

An HTML element into or out of which other elements may be dragged will be called a "bucket".

An HTML element which houses a collection of buckets will be called a "bucket pool".

To initialize a DraggableSubset bucket pool in a .pg problem, insert the line

$draggable = DraggableSubsets(
    $full_set,
    $answer_sets,
    option1 => $value1,
    option2 => $value2,
    ...
);

Then insert the draggable subset bucket pool into the problem text with

BEGIN_TEXT
\{$draggable->ans_rule\}
END_TEXT

for basic PG, or

BEGIN_PGML
[_]{$draggable}
END_PGML

for PGLM. Note the following also works, but is deprecated. However, if you want your problem to be compatible with previous versions of PG this must be used. Call

\{$draggable->Print\} (or [@ $draggable->Print @]* for PGML)

within the BEGIN_TEXT / END_TEXT (or BEGIN_PGML / END_PGML ) environment. Then call

ANS($draggable->cmp)

after END_TEXT (or END_PGML).

$full_set, e.g. ["statement1", "statement2", ...], is an array reference to the list of elements, given as strings, in the original full set.

$answer_sets, e.g. [[1, 2, 3], [4, 5], ...], is an array reference to a list of array references corresponding to the correct answer which is a set of subsets. Each subset element is specified via the index of the element in the $full_set, with the first element having index 0.

Available Options:

DefaultSubsets    => <array reference>
OrderedSubsets    => 0 or 1
cmpOptions        => <hash reference>

allowNewBuckets         => 0 or 1
bucketLabelFormat       => <string>
resetButtonText         => <string>
addButtonText           => <string>
removeButtonText        => <string>
showUniversalSet        => 0 or 1
universalSetLabel       => <string>
addFromUniversalText    => <string that must contain %1s, %2s, and %3s>
removeUniversalItemText => <string that must contain %1s and %2s>,
reorderText             => <string that must contain %1s, %s2, and %3s>
moveText                => <string that must contain %1s, %2s, %3s, and %4s>
helpButtonText          => <string>
closeHelpButtonText     => <string>
dragAndDropHelpText     => <string>

All of the options above except for the first three are really options of a DragNDrop object and are passed to that module on construction. See the DragNDrop options for details on those options. Note that AllowNewBuckets, BucketLabelFormat, ResetButtonText, AddButtonText, RemoveButtonText, ShowUniversalSet, and UniversalSetLabel are deprecated aliases for the corresponding option with the first letter lower case. Note that the default value of allowNewBuckets is 1 for this macro (it is 0 for the DragNDrop package).

The usage of the first three options is demonstrated in the example below.

SYNOPSIS

DOCUMENT();
loadMacros('PGstandard.pl', 'PGML.pl', 'draggableSubsets.pl', 'PGcourse.pl');

$draggable = DraggableSubsets(
    # Full set.  Make sure to use "\(...\)" for math and not "`...`" for correct display.
    [
        "\(e\)",    # index 0
        "\(r\)",    # index 1
        "\(r^2\)",  # index 2
        "\(s\)",    # index 3
        "\(sr\)",   # index 4
        "\(sr^2\)", # index 5
    ],

    # Reference to array of arrays of indices, corresponding to
    # the correct set of subsets.
    [ [0, 3], [1, 4], [2, 5] ],

    # Default instructor-provided subsets.
    # The default value if not given is [] which is interpreted to mean that
    # the full set will be the only subset initially shown.
    DefaultSubsets => [
        {
            # Label of the bucket.
            label     => 'coset 1',
            # Specifies pre-included elements in the bucket via their indices.
            indices   => [ 1, 3, 4, 5 ],
            # Specifies whether student may remove bucket.
            removable => 0
        },
        {
            label     => 'coset 2',
            indices   => [ 0 ],
            removable => 1
        },
        {
            label     => 'coset 3',
            indices   => [ 2 ],
            removable => 1
        }
    ],

    # 0 means order of subsets does not matter. 1 means otherwise.
    # (The order of elements within each subset never matters.)
    # The default value if not given is 0.
    OrderedSubsets => 0,

    # These are options that will be passed to the $draggable->cmp method.
    cmpOptions => { checker => sub { ... } }
);

BEGIN_PGML
Let [``G = D_3 = \{ e, r, r^2, s, sr, sr^2 \}``] be the Dihedral group of
order [`6`], where [`r`] is counter-clockwise rotation by [`2\pi/3`], and
[`s`] is the reflection across the [`x`]-axis.

Partition [`G = D_3`] into *right* cosets of the subgroup
[`H = \{ e, s \}`].

Give your result by dragging the following elements into separate buckets,
each corresponding to a coset.

[_]{$draggable}
END_PGML

ENDDOCUMENT();

CUSTOM CHECKERS

A custom checkers can also be used by passing the list_checker option to the cmp method. See https://wiki.openwebwork.org/wiki/Custom_Answer_Checkers_for_Lists for details on how to use a custom list checker. This follows the usual rules for the return value of the list_checker method.

Note that the correct and student answers will be Perl arrays containing MathObject Lists corresponding to all buckets in the answer.