NAME

problemPanic.pl - Allow for a PANIC button that gives additional hints, possibly costing some points.

DESCRIPTION

This file implements a mechanism for you to provide one or more "panic button" that your students can use to get additional hints, at the cost of a portion of their score.

To include the button, use the command Panic::Button command within a BEGIN_TEXT/END_TEXT block. E.g.,

BEGIN_TEXT
\{Panic::Button(label => "Request a Hint", penalty => .25)\}
(you will lose 25% of your points if you do)
END_TEXT

When the student presses the hint button, the button will not longer be available, and the "panic level" will be increased. This sets the variable $panicked, which you can use to determine whether to include the hints or not. For example

if ($panicked) {
  BEGIN_TEXT
    Hint:  You should factor the numerator and cancel
    one of the factors with the denominator.
  END_TEXT
}

Note that you can create a "cascade" of hints by including a second panic button in the hint received from the first button. This will set $panic to 2 (panic level 2) and you can use that to include the second hint.

if ($panicked) {
  BEGIN_TEXT
    Hint:  You should factor the numerator and cancel
    one of the factors with the denominator.
    $PAR
    \{Panic::Button(label => "Another Hint", penalty => .25)\}
    (costing an additional 25%)
  END_TEXT

  if ($panicked > 1) {
    BEGIN_TEXT
    Additional Hint: one of the factors is \(x+$a)\).
    END_TEXT
  }
}

You can add more buttons in a similar way. You can not have separate buttons for separate hints that are NOT cascaded, however. (That may be possible in future versions.)

The Panic::Button command takes two optional parameters:

label => "text"

Sets the text to use for the button. The default is "Request a Hint".

penalty => percent

Specifies the number points to lose (as a number from 0 to 1) if this hint is displayed. When more than one panic button is used, the penalties are cumulative. That is, two penalties of .25 would produce a total penalty of .5, so the student would lose half his points if both hints were given.

Once a hint is displayed, the panic button for that hint will no longer be shown, and the hint will continue to be displayed as the student submits new answers.

A professor will be given a "Reset problem hints" checkbox at the bottom of the problem, and can use that to request that the panic level be reset back to 0. This also sets the score and the number of attempts back to 0 as well, so this effectively resets the problem to its original state. This is intended for use primarily during problem development, but can be used to allow a student to get full credit for a problem even after he or she has asked for a hint.

To allow the grading penalties to work, you must include the command

Panic::GradeWithPenalty();

in order to install the panic-button grader. You should do this afer setting the grader that you want to use for the problem itself, as the panic grader will use the one that is installed at the time the Panic::GradWithPenalty command is issued.