Drag and Drop

The dragndrop directive defines an assessment to match pairs of concepts using a drag and drop interface.

Synopsis

The general format of the dragndrop directive is:

.. dragndrop:: unique_id
   :optional: parameter value

   + --- Content area ---
   |
   | An optional question or instructions for the assessment.
   |
   + --------------------

Required Arguments

unique id

A unique identifier after a space and the :: in the dragndrop directive. Valid identifiers must not contain spaces. You should also avoid the characters `` ` , ``,, :, and *.

Optional Arguments

content area

The dragndrop directive may contain a content area. Plain text only. The content area is not processed in any way. No HTML or Sphinx markup is interpreted.

The content area is displayed before the drag and drop items.

feedback

String. Define incorrect feedback displayed when the Check Me button is pressed.

The default is:

Incorrect. You got X correct and Y incorrect out of Z. You left A blank.

If :feedback: is defined, it will appear after the default feedback. Otherwise, only the default feedback is displayed.

Only 1 feedback field is permitted and is displayed regardless of which matches are incorrect.

The feedback for correct responses is always:

You are correct!
match_N

String. Up to 20 source / destination pairs.

  • N is a value from 1 through 20.

  • The source / destination pairs are separated using: |||.

  • All other text is passed through without modification.

  • The order of match_N options does not matter. They will be randomly shuffled when rendered in your book.

For example:

:match_1: Draggable element text|||Dropzone to be matched with text

Languages supported

The dragndrop directive is language agnostic. Nothing is actually executed or interpreted.

Sphinx configuration options

No directive specific configuration options exist.

Internationalization

tbd.

Known limitations

The text for matches must appear on a single line. No newlines are allowed.

Examples

A simple example.

.. dragndrop:: dnd-ex-1
   :feedback: Feedback that is displayed if things are incorrectly matched.
   :match_1: Draggable element text|||Dropzone to be matched with text
   :match_2: Drag to Answer B|||Answer B
   :match_3: Draggable text|||Text of dropzone

   The question goes here.
    Q-1: The question goes here. Feedback that is displayed if things are incorrectly matched.
  • Draggable element text
  • Dropzone to be matched with text
  • Drag to Answer B
  • Answer B
  • Draggable text
  • Text of dropzone

A completely empty directive is permitted.

A dnd with no items compiles without warning.

.. dragndrop:: dnd-ex-2

But does not render anything useful.

    Q-2:

Numbers for ‘match’ options need not start at 1, however, they must be unique within a single dragndrop assessment.

.. dragndrop:: dnd-ex-3
    :match_11: C++|||cpp
    :match_12: Java|||java
    :match_13: Python|||py

    Match the language with its common file extension.
    Q-3: Match the language with its common file extension.
  • C++
  • cpp
  • Java
  • java
  • Python
  • py

If a duplicate match is used, the directive will not compile. The runestone compiler will display an error similar to:

WARNING: your_file.rst:173: (ERROR/3) Error in "dragndrop" directive:
invalid option data: duplicate option "match_1".
Next Section - Fill in the Blank