Clickable Area¶

The clickablearea directive defines an assessment that interprets mouse clicks in the content area.

Synopsis¶

The general format of the clickablearea directive is:

.. clickablearea:: unique_id
   :required: parameter value

   + --- Content area ---
   |
   | A table in docutils 'grid table format'
   |
   | or
   |
   | text with :click-correct: text :endclick:
   | and
   | text with :click-incorrect: text :endclick:
   | markup
   |
   + --------------------

Required Arguments¶

unique id

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

content area

The clickablearea directive must contain at least one line of content.

The content area has relatively strict formatting requirements. The content area must contain either a table in grid table format or text with special formatting options embedded in the text.

If the content area contains a table, the :table: option must be set.

If the content area contains anything else, the :iscode: option must be set.

A space must separate the last directive option from the content area.

question

String. Instructions describing what is expected for a correct response.

iscode

Boolean. If present, the content area will expect text with special format strings

:click-correct: – define the start of a correct section of text.
:click-incorrect: – define the start of an incorrect section of text.
:endclick: – define the end of a marked section of text, either correct or incorrect.

Each click must end with a matching :endclick:

For example:

.. clickablearea:: question1
   :question: Click the rainbow color(s)
   :iscode:

   :click-correct:Red:endclick:
   :click-incorrect:Gold:endclick:
   :click-correct:Blue:endclick:
   :click-incorrect:Black:endclick:

table

Boolean. If present, the content area must contain a grid table and the directive must set the :correct: and :incorrect: options.

For example:

.. clickablearea:: question2
   :question: Click the rainbow color(s)
   :table:
   :correct: 1,0;2,2;3,1;3,3;4,2
   :incorrect: 2,1;2,3;3,2;4,1;4,3

   +-------+---------+--------+
   |  Red  |  Orange | Yellow |
   +-------+---------+--------+
   | White |  Green  | White  |
   +-------+---------+--------+
   |  Blue |  White  | Indigo |
   +-------+---------+--------+
   | White |  Violet | White  |
   +-------+---------+--------+

Table location numbering begins at 1. When referring to table cells, the upper left cell (‘Red’ in this example) is location 1, 1. The bottom right cell is at location 4, 3.

correct

Formatted List. A list of table coordinates that are marked as correct when clicked.

incorrect

Formatted List. A list of table coordinates that are marked as correct when clicked.

For both of the formatted lists, the list is built of cell coordinates.

The first number is the table row.
The second number is the table column.

A column coordinate equal to 0 means all columns are selected.
Each table coordinate is separated with ;.
No white space is allowed.

Optional Arguments¶

feedback

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

The default is:

Incorrect. You clicked on X of the Y correct elements and A of the B incorrect elements.

The feedback for correct responses is always:

You are Correct!

Languages supported¶

The clickablearea directive is language agnostic. Nothing is actually executed or interpreted. It is up to the author to ensure the syntax and grammar within a clickable area makes sense - no syntax checking is performed.

Sphinx configuration options¶

No directive specific configuration options exist.

Internationalization¶

tbd.

Known limitations¶

No syntax highlighting for :iscode: examples.

The text for all options (question, feedback, etc.) must appear on a single line. No newlines are allowed.

There is no way to suppress carriage returns in the source, which can make for long lines of text. If your text editor wraps, this can make the source difficult to read.

There is no way to set the width or alignment of a table rendered using :table:. Columns widths will automatically adjust to fill the available space.

Examples¶

A simple table example.

.. clickablearea:: ca-ex1
   :question: Click on all the vowels
   :table:
   :correct: 1,1
   :incorrect: 1,2;1,3;1,4

   +----+----+----+---+
   | a  | b  | c  | d |
   +----+----+----+---+

Does any content show up in the tab or is it just includes?

Q-1: Click on all the vowels

An :iscode: based example.

Note: - The content are can contain whitespace. - Multiple correct and incorrect sections can be specified on a single line.

.. clickablearea:: ca_ex2
   :question: Click on all of the variables of type ``int`` in the code below
   :iscode:
   :feedback: Remember input returns a ``str``

   :click-incorrect:seconds:endclick: = input("Please enter the number of seconds you wish to convert")
    
   :click-correct:hours:endclick: = int(seconds) / :click-incorrect:3600:endclick:
   :click-correct:secs_still_remaining:endclick: = :click-correct:total_secs:endclick: % 3600
   print(:click-correct:secs_still_remaining:endclick:)

Q-2: Click on all of the variables of type ``int`` in the code belowRemember input returns a ``str``

seconds = input("Please enter the number of seconds you wish to convert")

hours = int(seconds) / 3600
secs_still_remaining = total_secs % 3600
print(secs_still_remaining)

Another code-based example in which the complete text of every line is wrapped in either a correct or incorrect section. Note that the content area preserves white space everywhere it appears in the content area.

.. clickablearea:: ca-ex3
    :question: Click on all the statements that are part of the body of the while loop.  If you make a mistake you can click on the statement again to unhighlight it.
    :iscode:
    :feedback: Remember, the body of a loop is all the statements between the { and } after the while keyword or single statement following the while if there are no {}.
    
    :click-incorrect:int x = 5;:endclick:
    :click-incorrect:while (x > 0):endclick:
    :click-incorrect:{:endclick:
        :click-correct:System.out.println(x);:endclick:
        :click-correct:x = x - 1;:endclick:
    :click-incorrect:}:endclick:

Q-3: Click on all the statements that are part of the body of the while loop. If you make a mistake you can click on the statement again to unhighlight it.Remember, the body of a loop is all the statements between the { and } after the while keyword or single statement following the while if there are no {}.

int x = 5;
while (x > 0)
{
    System.out.println(x);
    x = x - 1;
}

.. clickablearea:: ca-ex4
   :question: Click on the values at index 1 and 3 in the following array.
   :feedback: Remember that the first value is at index 0.  Click on an area again to unselect it and try again.
   :table:
   :correct: 1,2;1,4
   :incorrect: 1,1;1,3;
        
   +----+----+----+----+
   | 3  | 2  | 1  | -3 |
   +----+----+----+----+

Q-4: Click on the values at index 1 and 3 in the following array.Remember that the first value is at index 0. Click on an area again to unselect it and try again.

-3

You have attempted of activities on this page