NAME

DragNDrop.pm - Drag-N-Drop Module

DESCRIPTION

DragNDrop.pm is a module which facilitates the implementation of 'Drag-And-Drop' in WeBWorK problems. It is meant to be used by other macros such as draggableProof.pl and draggableSubsets.pl

TERMINOLOGY

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

USAGE

Each macro aiming to implement drag-n-drop features must call at its initialization:

ADD_JS_FILE('node_modules/sortablejs/Sortable.min.js', 0, { defer => undef });
ADD_CSS_FILE('js/DragNDrop/dragndrop.css', 0);
ADD_JS_FILE('js/DragNDrop/dragndrop.js', 0, { defer => undef });
PG_restricted_eval('sub DraggableSubsets {draggableSubsets->new(@_)}');

To initialize a bucket pool call the constructor. For example,

my $dnd = new DragNDrop($answerName, $itemList);

$answerName is the HTML input 'name' for the corresponding answer. It should be generated with NEW_ANS_NAME.

$itemList is a reference to an array containing the HTML content of the draggable items.

For example,

$itemList = [
    'socrates is a man',
    'all men are mortal',
    'therefore socrates is mortal'
];

OPTIONS

There are a few options that you can supply to control the appearance and behavior of the DragNDrop JavaScript output, listed below. These are set as additional options to the constructor. For example,

DragNDrop($answerName, $itemList, allowNewBuckets => 1);

allowNewBuckets (Default: 0)

If this is set to 1 then a button is added to the HTML output which adds a new drag and drop bucket when clicked on.

bucketLabelFormat (Default: undef)

If the bucketLabelFormat option is defined, then buckets for which an explicit label is not provided will be will be created with the label with the %s in the string replaced with the bucket number in the pool. This also applies to new buckets that are added by the user via JavaScript if allowNewBuckets is 1. An example value for this option is 'Subset %s'.

resetButtonText (Default: 'Reset')

This is the text label for the reset button.

addButtonText (Default: 'Add Bucket')

This is the text label for the button shown that adds new buckets. The button is only shown if AllowNewBuckets is 1.

removeButtonText (Default: 'Remove')

This is the text label for any remove buttons that are added to removable buckets.

multicolsWidth (Default: '300pt')

This sets the size for which the TeX output for hardcopy uses two columns or not. If the current \linewidth is greater than or equal to this size then two columns will be used, otherwise only single column is used.

showUniversalSet (Default: 0)

If 1 then the set of all elements passed in the $itemList will be shown in a separate bucket. Elements can be dragged from this set and into other buckets, but not into it.

universalSetLabel (Default: 'Universal Set')

Label shown for the universal set bucket if showUniversalSet is 1.

addFromUniversalText

The aria announcement text format that is used when a universal set item is added to a bucket via keyboard controls. The default format for this text is 'Item %1s in the universal set added as item %2s to list %3s.'. Note that if this is customized it must contain %1s, %2s, and %3s as in the default value.

removeUniversalItemText

The aria announcement text format that is used when an item from the universal set that is in a bucket is removed via keyboard controls. The default format for this text is 'Item %1s removed from list %2s.'. Note that if this is customized it must contain %1s and %2s as in the default value.

reorderText

The aria announcement text format that is used when an item is moved up or down in a bucket via keyboard controls. The default format for this text is 'Moved item %1s in list %2s to item %3s.'. Note that if this is customized it must contain %1s, %2s, and %3s as in the default value.

moveText

The aria announcement text format that is used when an item is moved from one bucket to another via keyboard controls. The default format for this text is 'Moved item %1s in list %2s to item %3s in list %4s.'. Note that if this is customized it must contain %1s, %2s, %3s, and %4s as in the default value.

helpButtonText (Default: 'Drag and Drop Help')

The text shown on the button that opens the drag and drop help.

closeHelpButtonText (Default: 'Close Help')

The text shown on the button that closes the drag and drop help.

dragAndDropHelpText

The help that is shown when the drag and drop help button is pressed.

The default text is

Drag to reorganize items within lists or to move items to a different list. Tab and shift-tab can be used to focus list items. The left and right arrow keys move a focused list item to the list to the left or right. The up and down arrow keys move a focused list item up and down inside a list.

universalSetHelpText

If the option showUniversalSet is set to 1, then this is shown before the dragAndDropHelpText in the help.

The default text for this is

Drag items in the universal set to copy them to a list. Tab and shift-tab can be used to focus universal set items. A focused item in the universal set can be added to the first list with the right or down arrow keys, or added to the last list with the left or up arrow keys. A focused item in a list can be removed by using the left or right arrow key until it returns to the universal set.

METHODS

The following are methods that can be called with the constructed DragNDrop object.

$dnd->HTML()

This outputs the bucket pool to HTML.

$dnd->TeX()

This outputs the bucket pool to LaTeX.

EXAMPLES

See draggableProof.pl and draggableSubsets.pl