Commit acad35bb by Mark Hoeber

Merge pull request #2614 from edx/sylvia/documentation/BLD-815

Sylvia/documentation/bld 815
parents 64f1cae6 32476219
...@@ -9,11 +9,12 @@ Additional Tools ...@@ -9,11 +9,12 @@ Additional Tools
Additional Tools Overview Additional Tools Overview
************************* *************************
Individual course teams frequently create tools and problem types that don't have templates in Studio. We want to make these tools available to all our course teams. We provide you with all the files and code that you need to create these problems in Studio. Individual course teams frequently create tools and problem types that don't have templates in Studio. We want to make these tools available to all our course teams.
Below, you'll find the information you need to create the following tools. Below, we provide you with all the files and code that you need to create the following tools and problem types.
* :ref:`Gene Explorer` * :ref:`Gene Explorer`
* :ref:`Chemical Equation`
* :ref:`Interactive Periodic Table` * :ref:`Interactive Periodic Table`
* :ref:`Molecule Editor` * :ref:`Molecule Editor`
* :ref:`Multiple Choice and Numerical Input` * :ref:`Multiple Choice and Numerical Input`
...@@ -41,18 +42,6 @@ Specifically, the Gene Explorer does the following: ...@@ -41,18 +42,6 @@ Specifically, the Gene Explorer does the following:
For more information about the Gene Explorer, see `The Gene Explorer <http://intro.bio.umb.edu/GX/>`_. For more information about the Gene Explorer, see `The Gene Explorer <http://intro.bio.umb.edu/GX/>`_.
.. _Create the Gene Explorer:
==========================
Create the Gene Explorer
==========================
#. In the unit where you want to create the problem, click **Problem** under **Add New Component**, and then click the **Advanced** tab.
#. Click **Blank Advanced Problem**.
#. In the component that appears, click **Edit**.
#. In the component editor, paste the code from below.
#. Click **Save**.
===================== =====================
Gene Explorer Code Gene Explorer Code
===================== =====================
...@@ -82,6 +71,76 @@ In this code: ...@@ -82,6 +71,76 @@ In this code:
* **genex_problem_number** specifies the number of the problem. This number is based on the five gene editor problems in the MITx 7.00x course--for example, if you want this problem to look like the second gene editor problem in the 7.00x course, you would set the **genex_problem_number** value to 2. The number must be 1, 2, 3, 4, or 5. * **genex_problem_number** specifies the number of the problem. This number is based on the five gene editor problems in the MITx 7.00x course--for example, if you want this problem to look like the second gene editor problem in the 7.00x course, you would set the **genex_problem_number** value to 2. The number must be 1, 2, 3, 4, or 5.
.. _Chemical Equation:
**************************
Chemical Equation Problem
**************************
The chemical equation problem type allows the student to enter chemical equations. The grader evaluates student responses by using a Python script that you create and embed in the problem.
.. image:: /Images/ChemicalEquationExample.png
:alt: Image of a chemical equation response problem
====================================
Create the Chemical Equation Problem
====================================
To create the above chemical equation problem:
#. In the unit where you want to create the problem, click **Problem** under **Add New Component**, and then click the **Advanced** tab.
#. Click **Blank Advanced Problem**.
#. In the component that appears, click **Edit**.
#. In the component editor, paste the code from below.
#. Click **Save**.
====================================
Chemical Equation Problem Code
====================================
.. code-block:: xml
<problem>
<startouttext/>
<p>Some problems may ask for a particular chemical equation. Practice by writing out the following reaction in the box below.</p>
\( \text{H}_2\text{SO}_4 \longrightarrow \text { H}^+ + \text{ HSO}_4^-\)
<customresponse>
<chemicalequationinput size="50"/>
<answer type="loncapa/python">
if chemcalc.chemical_equations_equal(submission[0], 'H2SO4 -> H^+ + HSO4^-'):
correct = ['correct']
else:
correct = ['incorrect']
</answer>
</customresponse>
<p>Some tips:</p>
<ul>
<li>Use real element symbols.</li>
<li>Create subscripts by using plain text.</li>
<li>Create superscripts by using a caret (^).</li>
<li>Create the reaction arrow (\(\longrightarrow\)) by using "->".</li>
</ul>
<endouttext/>
<solution>
<div class="detailed-solution">
<p>Solution</p>
<p>To create this equation, enter the following:</p>
<p>H2SO4 -> H^+ + HSO4^-</p>
</div>
</solution>
</problem>
.. _Interactive Periodic Table: .. _Interactive Periodic Table:
************************** **************************
...@@ -116,7 +175,7 @@ To create the periodic table, you need an HTML component. ...@@ -116,7 +175,7 @@ To create the periodic table, you need an HTML component.
#. In the component editor, switch to the **HTML** tab. #. In the component editor, switch to the **HTML** tab.
#. Open the PeriodicTable.txt file in any text editor. #. Open the PeriodicTable.txt file in any text editor.
#. Copy all of the text in the PeriodicTable.txt file, and paste it into the HTML component editor. (Note that the PeriodicTableHTML.txt file contains over 6000 lines of code. Paste all of this code into the component editor.) #. Copy all of the text in the PeriodicTable.txt file, and paste it into the HTML component editor. (Note that the PeriodicTableHTML.txt file contains over 6000 lines of code. Paste all of this code into the component editor.)
#. Make any changes that you want, and then click **Save**. #. Click **Save**.
.. _Molecule Editor: .. _Molecule Editor:
...@@ -151,15 +210,18 @@ To create the molecule editor that appears in the image above, you need an HTML ...@@ -151,15 +210,18 @@ To create the molecule editor that appears in the image above, you need an HTML
#. Upload all of the files listed above to the **Files & Uploads** page in your course. #. Upload all of the files listed above to the **Files & Uploads** page in your course.
#. Create the HTML component. #. Create the HTML component.
#. In the unit where you want to create the problem, click **HTML** under **Add New Component**, and then click **HTML**. #. In the unit where you want to create the problem, click **HTML** under **Add New Component**, and then click **HTML**.
#. In the component that appears, click **Edit**. #. In the component that appears, click **Edit**.
#. In the component editor, paste the HTML component code from below. #. In the component editor, paste the HTML component code from below.
#. Make any changes that you want, and then click **Save**. #. Make any changes that you want, and then click **Save**.
#. Create the Problem component.
3. Create the Problem component.
#. Under the HTML component, click **Problem** under **Add New Component**, and then click **Blank Advanced Problem**. #. Under the HTML component, click **Problem** under **Add New Component**, and then click **Blank Advanced Problem**.
#. In the component that appears, click **Edit**. #. In the component that appears, click **Edit**.
#. In the component editor, paste the Problem component code from below. #. In the component editor, paste the Problem component code from below.
#. Make any changes that you want, and then click **Save**. #. Click **Save**.
.. _EMC Problem Code: .. _EMC Problem Code:
...@@ -172,7 +234,7 @@ To create the molecule editor, you need an HTML component and a Problem componen ...@@ -172,7 +234,7 @@ To create the molecule editor, you need an HTML component and a Problem componen
HTML Component Code HTML Component Code
------------------- -------------------
:: .. code-block:: xml
<h2>Molecule Editor</h2> <h2>Molecule Editor</h2>
<p>The molecule editor makes creating and visualizing molecules easy. A chemistry professor may have you build and submit a molecule as part of an exercise.</p> <p>The molecule editor makes creating and visualizing molecules easy. A chemistry professor may have you build and submit a molecule as part of an exercise.</p>
...@@ -215,12 +277,12 @@ HTML Component Code ...@@ -215,12 +277,12 @@ HTML Component Code
</div> </div>
<div id="ap_listener_added">&nbsp;</div> <div id="ap_listener_added">&nbsp;</div>
Problem Component
-----------------
**Problem 1**
::
Problem Component Code
----------------------
.. code-block:: xml
<problem> <problem>
<p>The dopamine molecule, as shown, cannot make ionic bonds. Edit the dopamine molecule so it can make ionic bonds.</p> <p>The dopamine molecule, as shown, cannot make ionic bonds. Edit the dopamine molecule so it can make ionic bonds.</p>
...@@ -313,7 +375,7 @@ To create a multiple choice and numerical input problem: ...@@ -313,7 +375,7 @@ To create a multiple choice and numerical input problem:
Multiple Choice and Numerical Input Problem Code Multiple Choice and Numerical Input Problem Code
=================================================== ===================================================
:: .. code-block:: xml
<problem> <problem>
The numerical value of pi, rounded to two decimal points, is 3.24. The numerical value of pi, rounded to two decimal points, is 3.24.
...@@ -356,7 +418,7 @@ To create the protein builder: ...@@ -356,7 +418,7 @@ To create the protein builder:
Protein Builder Code Protein Builder Code
===================== =====================
:: .. code-block:: xml
<problem> <problem>
<p>The protein builder allows you string together the building blocks of proteins, amino acids, and see how that string will form into a structure. You are presented with a goal protein shape, and your task is to try to re-create it. In the example below, the shape that you are asked to form is a simple line.</p> <p>The protein builder allows you string together the building blocks of proteins, amino acids, and see how that string will form into a structure. You are presented with a goal protein shape, and your task is to try to re-create it. In the example below, the shape that you are asked to form is a simple line.</p>
......
...@@ -8,27 +8,62 @@ APPENDIX E: Problem and Tool XML ...@@ -8,27 +8,62 @@ APPENDIX E: Problem and Tool XML
This appendix provides information about the XML for most problem and tool types in Studio: This appendix provides information about the XML for most problem and tool types in Studio:
* :ref:`Checkbox` * :ref:`General`
* :ref:`Chemical Equation Response` * :ref:`Choice Response`
* :ref:`Chemical Equation Input`
* :ref:`Custom Response` * :ref:`Custom Response`
* :ref:`Formula Response` * :ref:`Formula Response`
* :ref:`Image Response` * :ref:`Image Response`
* :ref:`Multiple Choice` * :ref:`Multiple Choice Response`
* :ref:`Numerical Response` * :ref:`Numerical Response`
* :ref:`Option Response` * :ref:`Option Response`
* :ref:`Schematic Response` * :ref:`Schematic Response`
* :ref:`String Response` * :ref:`String Response`
.. _Checkbox:
Choice Response (Checkbox) .. _General:
---------------------------
Sample Problem: General
-------
Most problems have the following tags.
.. list-table::
:widths: 20 80
* - ``<problem> </problem>``
- These must be the first and last tags for any content created in the Advanced
Editor in a Problem component.
* - ``<startouttext/>``
- The ``<startouttext />`` tag indicates the beginning of a line or block of text.
* - ``<endouttext/>``
- The ``<endouttext />`` tag indicates the end of a line or block of text.
* - ``<solution> <div class="detailed-solution"> </div> </solution>`` (optional)
- If you want to include more information in the problem, such as a detailed explanation of the problem's answer, you'll enter the text between the two ``<div>`` tags, which are inside the ``<solution>`` tags. (These tags do not have to be on the same line.)
.. _Choice Response:
Choice Response (Checkbox Problems)
-----------------------------------
Although you can create checkbox problems by using the Simple Editor in Studio, you may want to see or change the problem's underlying XML.
**Sample Problem**
.. image:: ../Images/CheckboxExample.gif .. image:: ../Images/CheckboxExample.gif
:alt: Image of a checkbox problem :alt: Image of a checkbox problem
**Tags**
.. list-table::
:widths: 20 80
* - ``<choiceresponse>``
- Specifies that the problem lists answer options for students to choose from.
* - ``<checkboxgroup>``
- A child of ``<choiceresponse>``. Specifies that the problem is a checkbox problem.
* - ``<choice>``
- A child of ``<checkboxgroup>``. Designates an answer option. Each choice must include the ``correct`` attribute, set to ``true`` (for a correct answer) or ``false`` (for an incorrect answer). For checkbox problems, more than one option can be a correct answer.
**Sample Problem XML** **Sample Problem XML**
...@@ -36,20 +71,31 @@ Sample Problem: ...@@ -36,20 +71,31 @@ Sample Problem:
<problem> <problem>
<startouttext/> <startouttext/>
<p>Learning about the benefits of preventative healthcare can be particularly difficult. Check all of the reasons below why this may be the case.</p> <p>Learning about the benefits of preventative healthcare can be particularly
difficult. Check all of the reasons below why this may be the case.</p>
<choiceresponse> <choiceresponse>
<checkboxgroup> <checkboxgroup>
<choice correct="true"><text>A large amount of time passes between undertaking a preventative measure and seeing the result.</text></choice> <choice correct="true"><text>A large amount of time passes between undertaking
<choice correct="false"><text>Non-immunized people will always fall sick.</text></choice> a preventative measure and seeing the result.</text></choice>
<choice correct="true"><text>If others are immunized, fewer people will fall sick regardless of a particular individual's choice to get immunized or not.</text></choice> <choice correct="false"><text>Non-immunized people will always fall sick.</text>
<choice correct="true"><text>Trust in healthcare professionals and government officials is fragile.</text></choice> </choice>
<choice correct="true"><text>If others are immunized, fewer people will fall
sick regardless of a particular individual's choice to get immunized or not.
</text></choice>
<choice correct="true"><text>Trust in healthcare professionals and government
officials is fragile.</text></choice>
</checkboxgroup> </checkboxgroup>
<solution> <solution>
<div class="detailed-solution"> <div class="detailed-solution">
<p>Explanation</p> <p>Explanation</p>
<p>People who are not immunized against a disease may still not fall sick from the disease. If someone is trying to learn whether or not preventative measures against the disease have any impact, he or she may see these people and conclude, since they have remained healthy despite not being immunized, that immunizations have no effect. Consequently, he or she would tend to believe that immunization (or other preventative measures) have fewer benefits than they actually do.</p> <p>People who are not immunized against a disease may still not fall sick from the
disease. If someone is trying to learn whether or not preventative measures
against the disease have any impact, he or she may see these people and conclude,
since they have remained healthy despite not being immunized, that immunizations
have no effect. Consequently, he or she would tend to believe that immunization
(or other preventative measures) have fewer benefits than they actually do.</p>
</div> </div>
</solution> </solution>
</choiceresponse> </choiceresponse>
...@@ -73,28 +119,40 @@ Sample Problem: ...@@ -73,28 +119,40 @@ Sample Problem:
<solution> <solution>
<div class="detailed-solution"> <div class="detailed-solution">
<p>Explanation</p> <p>Solution or Explanation Heading</p>
<p>Explanation text</p> <p>Solution or explanation text</p>
</div> </div>
</solution> </solution>
</choiceresponse> </choiceresponse>
</problem> </problem>
.. _Chemical Equation Input:
Chemical Equation Input (Chemical Equation Problems)
----------------------------------------------------
.. _Chemical Equation Response: In chemical equation problems, students enter text that represents a chemical equation into a text box. The LMS converts that text into a chemical equation below the text box.
Chemical Equation Response
--------------------------
The chemical equation problem type allows the student to enter chemical equations. The grader evaluates student responses by using a Python script that you create and embed in the problem.
**Sample Problem** **Sample Problem**
.. image:: ../Images/ChemicalEquationExample.png .. image:: ../Images/ChemicalEquationExample.png
:alt: Image of a chemical equation response problem :alt: Image of a chemical equation response problem
**Required Tags**
.. list-table::
:widths: 20 80
* - ``<customresponse>``
- Indicates that this problem has a custom response. The ``<customresponse>`` tags must surround the ``<chemicalequation>`` tags.
* - ``<chemicalequationinput>``
- A child of ``<customresponse>``. Indicates that the answer to this problem is a chemical equation.
* - ``<answer type=loncapa/python>``
- A child of ``<chemicalequationinput>``. Contains the Python script that grades the problem.
Chemical equation problems use MathJax to create formulas. For more information about using MathJax in Studio, see :ref:`MathJax in Studio`.
**Sample Problem XML**: **Sample Problem XML**:
.. code-block:: xml .. code-block:: xml
...@@ -135,19 +193,60 @@ The chemical equation problem type allows the student to enter chemical equation ...@@ -135,19 +193,60 @@ The chemical equation problem type allows the student to enter chemical equation
</solution> </solution>
</problem> </problem>
**Problem Template**:
.. code-block:: xml
<problem>
<startouttext/>
<p>Problem text</p>
<customresponse>
<chemicalequationinput size="50"/>
<answer type="loncapa/python">
if chemcalc.chemical_equations_equal(submission[0], 'TEXT REPRESENTING CHEMICAL EQUATION'):
correct = ['correct']
else:
correct = ['incorrect']
</answer>
</customresponse>
<endouttext/>
<solution>
<div class="detailed-solution">
<p>Solution or Explanation Header</p>
<p>Solution or explanation text</p>
</div>
</solution>
</problem>
.. _Custom Response: .. _Custom Response:
Custom Response ("Write-Your-Own-Grader") Custom Response ("Custom Python-Evaluated Input") Problems
------------------------------------------ -----------------------------------------------------------
In write-your-own-grader problems (also called “custom Python-evaluated input” problems), the grader evaluates a student’s response using a Python script that you create and embed in the problem. Students can enter more than one line of text. In custom Python-evaluated input (also called “write-your-own-grader”) problems, the grader evaluates a student’s response using a Python script that you create and embed in the problem.
**Sample Problem** **Sample Problem**
.. image:: ../Images/CustomPythonExample.png .. image:: ../Images/CustomPythonExample.png
:alt: Image of a custom response problem :alt: Image of a custom response problem
.. list-table::
:widths: 20 80
* - ``<script type="loncapa/python">``
- Indicates that the problem contains a Python script.
* - ``<customresponse cfn="test_add_to_ten">``
-
* - ``<customresponse cfn="test_add" expect="20">``
-
* - <textline size="10" correct_answer="3"/>
- This tag includes the ``size`` and ``correct_answer`` attributes. The ``correct_answer`` attribute is optional.
**Sample Problem XML**: **Sample Problem XML**:
...@@ -194,7 +293,7 @@ In write-your-own-grader problems (also called “custom Python-evaluated inputâ ...@@ -194,7 +293,7 @@ In write-your-own-grader problems (also called “custom Python-evaluated inputâ
**Templates** **Templates**
The following template includes suggested correct answers (to include these, add a ``correct_answer`` attribute to the ``<textline>`` tag). The following template includes answers that appear when the student clicks **Show Answer**.
.. code-block:: xml .. code-block:: xml
...@@ -208,7 +307,7 @@ The following template includes suggested correct answers (to include these, add ...@@ -208,7 +307,7 @@ The following template includes suggested correct answers (to include these, add
</script> </script>
<p>Enter two real numbers that sum to 20: </p> <p>Problem text</p>
<customresponse cfn="test_add" expect="20"> <customresponse cfn="test_add" expect="20">
<textline size="10" correct_answer="11"/><br/> <textline size="10" correct_answer="11"/><br/>
<textline size="10" correct_answer="9"/> <textline size="10" correct_answer="9"/>
...@@ -216,11 +315,13 @@ The following template includes suggested correct answers (to include these, add ...@@ -216,11 +315,13 @@ The following template includes suggested correct answers (to include these, add
<solution> <solution>
<div class="detailed-solution"> <div class="detailed-solution">
<p>Solution or Explanation Heading</p>
<p>Solution or explanation text</p>
</div> </div>
</solution> </solution>
</problem> </problem>
The following template does not include suggested correct answers. The following template does not return answers when the student clicks **Show Answer**. If your problem doesn't include answers for the student to see, make sure to set **Show Answer** to **Never** in the problem component.
.. code-block:: xml .. code-block:: xml
...@@ -242,6 +343,8 @@ The following template does not include suggested correct answers. ...@@ -242,6 +343,8 @@ The following template does not include suggested correct answers.
<solution> <solution>
<div class="detailed-solution"> <div class="detailed-solution">
<p>Solution or Explanation Heading</p>
<p>Solution or explanation text</p>
</div> </div>
</solution> </solution>
</problem> </problem>
...@@ -254,9 +357,21 @@ Formula Response (Math Expression Input Problems) ...@@ -254,9 +357,21 @@ Formula Response (Math Expression Input Problems)
**Sample Problem** **Sample Problem**
.. image:: ../Images/MathExpressionInputExample.gif .. image:: ../Images/MathExpressionInputExample.gif
:width: 600
:alt: Image of a math expression input problem :alt: Image of a math expression input problem
.. list-table::
:widths: 20 80
:header-rows: 1
* - ``<formularesponse>``
-
* - ``<formulaequationinput>``
-
* - ``<script type="loncapa/python">``
-
* - ``<textline size="10" correct_answer="3"/>``
- This tag includes the ``size`` and ``correct_answer`` attributes. The ``correct_answer`` attribute is optional.
**Sample Problem XML** **Sample Problem XML**
.. code-block:: xml .. code-block:: xml
...@@ -293,12 +408,36 @@ Formula Response (Math Expression Input Problems) ...@@ -293,12 +408,36 @@ Formula Response (Math Expression Input Problems)
<solution> <solution>
<div class="detailed-solution"> <div class="detailed-solution">
<p>Explanation</p> <p>Explanation or Solution Header</p>
<p>Explanation or solution text</p>
</div>
</solution>
</problem>
**Template XML**
.. code-block:: xml
<problem>
<p>Problem text</p>
<formularesponse type="ci" samples="VARIABLES@LOWER_BOUNDS:UPPER_BOUNDS#NUMBER_OF_SAMPLES" answer="$VoVi">
<responseparam type="tolerance" default="0.00001"/>
<formulaequationinput size="20" />
</formularesponse>
<script type="loncapa/python">
VoVi = "(R_1*R_2)/R_3"
</script>
<solution>
<div class="detailed-solution">
<p>Explanation or Solution Header</p>
<p>Explanation or solution text</p>
</div> </div>
</solution> </solution>
</problem> </problem>
**XML Attribute Information** **XML Attribute Information**
<script> <script>
...@@ -335,19 +474,23 @@ size (optional) defines the size (i.e. the width) ...@@ -335,19 +474,23 @@ size (optional) defines the size (i.e. the width)
.. _Image Response: .. _Image Response:
Image Response Image Response (Image Mapped Input Problems)
-------------- --------------------------------------------
The Image Response input type presents an image and accepts clicks on the image as an answer. **Sample Problem**
Images have to be uploaded to the courseware Assets directory. Response clicks are marked as correct if they are within a certain specified sub rectangle of the image canvas.
*Note The Mozilla Firefox browser is currently not supported for this problem type.* .. image:: ../Images/image294.png
:alt: Image of an image mapped input problem
Sample Problem: **XML Tags**
.. image:: ../Images/image294.png .. list-table::
:width: 600 :widths: 20 80
* - ``<imageresponse>``
- Indicates that the problem is an image mapped input problem.
* - ``<imageinput>``
- Specifies the image file and the region the student must click. This tag includes the ``src``, ``width``, ``height``, and ``rectangle`` attributes.
**Problem Code**: **Problem Code**:
...@@ -356,25 +499,27 @@ Sample Problem: ...@@ -356,25 +499,27 @@ Sample Problem:
<problem> <problem>
<p><b>Example Problem</b></p> <p><b>Example Problem</b></p>
<startouttext/> <startouttext/>
<p>You are given three shapes. Click on the triangle.</p> <p>In the image below, click the triangle.</p>
<endouttext/> <endouttext/>
<imageresponse> <imageresponse>
<imageinput src="/static/threeshapes.png" width="220" height="150" rectangle="(80,40)-(130,90)" /> <imageinput src="/static/threeshapes.png" width="220" height="150" rectangle="(80,40)-(130,90)" />
</imageresponse> </imageresponse>
</problem> </problem>
Template **Problem Template**
.. code-block:: xml .. code-block:: xml
<problem> <problem>
<startouttext/>
<p>In the image below, click the triangle.</p>
<endouttext/>
<imageresponse> <imageresponse>
<imageinput src="Path_to_Image_File.png" width="220" height="150" rectangle="(80,40)-(130,90)" /> <imageinput src="IMAGE FILE PATH" width="NUMBER" height="NUMBER" rectangle="(X-AXIS,Y-AXIS)-(X-AXIS,Y-AXIS)" />
</imageresponse> </imageresponse>
</problem> </problem>
XML Attribute Information **XML Attribute Information**
<imageresponse> <imageresponse>
...@@ -384,57 +529,49 @@ XML Attribute Information ...@@ -384,57 +529,49 @@ XML Attribute Information
.. image:: ../Images/imageresponse2.png .. image:: ../Images/imageresponse2.png
.. _Multiple Choice: .. _Multiple Choice Response:
Multiple Choice Multiple Choice Response (Multiple Choice Problems)
--------------- -----------------------------------------------------
Although you can create multiple choice problems by using the Simple Editor in Studio, you may want to see or change the problem's underlying XML.
The Multiple Choice input type allows the student to select at most one choice **Sample Problem**
from a collection of answer choices, presented as a list of radio buttons.
A Multiple Choice problem can have more than one correct answer, depending on
how many choices are marked as correct in the underlying XML. If all choices are
marked as incorrect, there is no correct response.
Multiple Choice is structurally similar to Option Response. Some conceptual
differences between the two include the following.
• The Multiple Choice radio button format makes it easier for students to read very long response options.
• The Option Response drop-down input format makes it more likely for students to think of an answer and then search for it, rather than relying purely on recognition to answer the question. .. image:: ../Images/MultipleChoiceExample.gif
:alt: Image of a multiple choice problem
• The Multiple Choice format is more explicit and visual. This makes it a more appropriate choice for presenting tricky or complicated answer options which are intended to get the student to pause and think. **XML Tags**
Sample Problem: .. list-table::
:widths: 20 80
.. image:: ../Images/image289.png * - ``<multiplechoiceresponse>``
:width: 600 - Indicates that the problem is a multiple choice problem.
:alt: Image of a multiple choice problem * - ``<choicegroup type="MultipleChoice">``
- Indicates the beginning of the list of options.
* - ``<choice>``
- Lists an option. This tag includes the ``correct`` and ``name`` attributes.
**Problem Code:** **Problem Code:**
.. code-block:: xml .. code-block:: xml
<problem> <problem>
<p><b>Example Problem</b></p> <p>Lateral inhibition, as was first discovered in the horsehoe crab...</p>
<p>How many correct responses can a Multiple Choice question have?</p>
<multiplechoiceresponse> <multiplechoiceresponse>
<choicegroup type="MultipleChoice"> <choicegroup type="MultipleChoice">
<choice correct="false" name="one">Only one</choice> <choice correct="false">is a property of touch sensation, referring to the ability of crabs to detect nearby predators.</choice>
<choice correct="false" name="zeroone">Only zero or one</choice> <choice correct="false">is a property of hearing, referring to the ability of crabs to detect low frequency noises.</choice>
<choice correct="true" name="zeromore">Zero or more</choice> <choice correct="false">is a property of vision, referring to the ability of crabs eyes to enhance contrasts.</choice>
<choice correct="false" name="onemore">Only one or more</choice> <choice correct="true">has to do with the ability of crabs to use sonar to detect fellow horseshoe crabs nearby.</choice>
<choice correct="false" name="noone">Nobody knows</choice> <choice correct="false">has to do with a weighting system in the crabs skeleton that allows it to balance in turbulent water.</choice>
<choice correct="true" name="someone">Somebody might know :)</choice>
</choicegroup> </choicegroup>
</multiplechoiceresponse> </multiplechoiceresponse>
<solution> <solution>
<div class="detailed-solution"> <div class="detailed-solution">
<p>Explanation</p> <p>Explanation</p>
<p>It depends on how many choices are marked as correct in the underlying XML.</p> <p>Horseshoe crabs were essential to the discovery of lateral inhibition, a property of vision present in horseshoe crabs as well as humans, that enables enhancement of contrast at edges of objects as was demonstrated in class. In 1967, Haldan Hartline received the Nobel prize for his research on vision and in particular his research investigating lateral inhibition using horseshoe crabs.</p>
<p>Note that if all choices are marked as incorrect, there is no
correct response.</p>
</div> </div>
</solution> </solution>
</problem> </problem>
...@@ -445,17 +582,18 @@ Sample Problem: ...@@ -445,17 +582,18 @@ Sample Problem:
.. code-block:: xml .. code-block:: xml
<problem> <problem>
<p>Question text</p>
<multiplechoiceresponse> <multiplechoiceresponse>
<choicegroup type="MultipleChoice"> <choicegroup type="MultipleChoice">
<choice correct="false" name="a">A</choice> <choice correct="false" name="a">Incorrect choice</choice>
<choice correct="true" name="b">B</choice> <choice correct="true" name="b">Correct choice</choice>
</choicegroup> </choicegroup>
</multiplechoiceresponse> </multiplechoiceresponse>
<solution> <solution>
<div class="detailed-solution"> <div class="detailed-solution">
<p>Explanation or solution header</p>
<p>Explanation or solution text</p>
</div> </div>
</solution> </solution>
</problem> </problem>
...@@ -776,59 +914,72 @@ The default included functions are the following: ...@@ -776,59 +914,72 @@ The default included functions are the following:
.. _Option Response: .. _Option Response:
Option Response (Dropdown) Option Response (Dropdown Problems)
-------------------------- -----------------------------------
The Option Response input type allows the student to choose from a collection of Although you can create dropdown problems by using the Simple Editor in Studio, you may want to see or change the problem's underlying XML.
answer options, presented as a drop-down list.
Option Response is structurally similar to Multiple Choice. Some conceptual **Sample Problem**
differences between the two include the following.
* The Multiple Choice radio button format makes it easier for students to read very long response options. .. image:: ../Images/DropdownExample.gif
:alt: Image of an option response problem
* The Option Response drop-down input format makes it more likely for students to think of an answer and then search for it, rather than relying purely on recognition to answer the question. The Multiple Choice format is more explicit and visual. This makes it a more appropriate choice for presenting tricky or complicated answer options which are intended to get the student to pause and think. **XML Tags**
Sample Problem: .. list-table::
:widths: 20 80
* - ``<optionresponse>``
- Indicates that the problem is a dropdown problem.
* - ``<optioninput>``
- Lists the answer options. This tag includes the ``options`` and ``correct`` attributes.
.. image:: ../Images/image287.png
:width: 600
:alt: Image of an option response problem
**Problem Code:** **Problem Code:**
.. code-block:: xml .. code-block:: xml
<problem> <problem>
<p>
<em>This exercise first appeared in HarvardX's PH207x Health in Numbers: Quantitative Methods in Clinical &amp; Public Health Research course, fall 2012.</em>
</p>
<p>What type of data are the following?</p>
<p>Age:</p>
<optionresponse>
<optioninput options="('Nominal','Discrete','Continuous')" correct="Continuous"/>
</optionresponse>
<p>Age, rounded to the nearest year:</p>
<optionresponse>
<optioninput options="('Nominal','Discrete','Continuous')" correct="Discrete"/>
</optionresponse>
<p>Life stage - infant, child, and adult:</p>
<optionresponse>
<optioninput options="('Nominal','Discrete','Continuous')" correct="Nominal"/>
</optionresponse>
</problem>
<p>Option Response is most similar to __________.</p> **Template**
.. code-block:: xml
<problem>
<p>
Problem text</p>
<optionresponse> <optionresponse>
<optioninput <optioninput options="('Option 1','Option 2','Option 3')" correct="Option 2"/>
options="('Multiple Choice','String Response',
'Numerical Response','External Response',
'Image Response')"
correct="Multiple Choice"/>1
</optionresponse> </optionresponse>
<solution> <solution>
<div class="detailed-solution"> <div class="detailed-solution">
<p>Explanation</p> <p>Explanation or Solution Header</p>
<p>Like Option Response, Multiple Choice also allows students to select <p>Explanation or solution text</p>
from a variety of pre-written responses.</p>
</div> </div>
</solution> </solution>
</problem> </problem>
**Template**
.. code-block:: xml .. code-block:: xml
<problem> <problem>
<p>Problem text</p>
<optionresponse> <optionresponse>
options="('A','B')" options="('A','B')"
correct="A"/> correct="A"/>
...@@ -836,6 +987,8 @@ Sample Problem: ...@@ -836,6 +987,8 @@ Sample Problem:
<solution> <solution>
<div class="detailed-solution"> <div class="detailed-solution">
<p>Explanation or Solution Header</p>
<p>Explanation or solution text</p>
</div> </div>
</solution> </solution>
</problem> </problem>
...@@ -857,24 +1010,15 @@ Sample Problem: ...@@ -857,24 +1010,15 @@ Sample Problem:
.. _Schematic Response: .. _Schematic Response:
Schematic Response Schematic Response (Circuit Schematic Problems)
------------------ -----------------------------------------------
The Schematic Response input type provides an interactive grid on which the The Schematic Response input type provides an interactive grid on which the
student can construct a schematic answer, such as a circuit. student can construct a schematic answer, such as a circuit.
Sample Problem: **Sample Problem**
.. image:: ../Images/image297.png
:width: 600
:alt: Image of a schematic response problem
.. image:: ../Images/image298.png
:width: 600
:alt: Image of a schematic response problem
.. image:: ../Images/image299.png .. image:: ../Images/CircuitSchematicExample.gif
:width: 600
:alt: Image of a schematic response explanation :alt: Image of a schematic response explanation
**Problem Code**: **Problem Code**:
...@@ -883,8 +1027,7 @@ Sample Problem: ...@@ -883,8 +1027,7 @@ Sample Problem:
<problem> <problem>
Make a voltage divider that splits the provided voltage evenly. <p>Make a voltage divider that splits the provided voltage evenly.</p>
<schematicresponse> <schematicresponse>
<center> <center>
<schematic height="500" width="600" parts="g,r" analyses="dc" <schematic height="500" width="600" parts="g,r" analyses="dc"
...@@ -897,12 +1040,10 @@ Sample Problem: ...@@ -897,12 +1040,10 @@ Sample Problem:
if response[0] == 'dc': if response[0] == 'dc':
for node in response[1:]: for node in response[1:]:
dc_value = node['output'] dc_value = node['output']
if dc_value == .5: if dc_value == .5:
correct = ['correct'] correct = ['correct']
else: else:
correct = ['incorrect'] correct = ['incorrect']
</answer> </answer>
</schematicresponse> </schematicresponse>
<schematicresponse> <schematicresponse>
...@@ -927,7 +1068,6 @@ Sample Problem: ...@@ -927,7 +1068,6 @@ Sample Problem:
correct = ['incorrect'] correct = ['incorrect']
</answer> </answer>
</schematicresponse> </schematicresponse>
<solution> <solution>
<div class="detailed-solution"> <div class="detailed-solution">
<p>Explanation</p> <p>Explanation</p>
...@@ -941,44 +1081,74 @@ Sample Problem: ...@@ -941,44 +1081,74 @@ Sample Problem:
.. _String Response: .. _String Response:
String Response (Text Input Problems)
-------------------------------------
Although you can create text input problems by using the Simple Editor in Studio, you may want to see or change the problem's underlying XML. For example, you can add hints that appear when students enter common incorrect answers, or modify the problem's XML so that students can submit regular expressions as answers.
String Response The regular expression that the student enters must contain the part of the answer that the instructor specifies. For example, if an instructor has specified ``<answer=".*example answer.*" type="regexp">``, correct answers include ``example answered``, ``two example answers``, or even ``==example answer==``, but not ``examples`` or ``example anser``.
---------------
The String Response input type provides an input box in which the student can
enter a line of text, which is then checked against a specified expected answer.
A String Response input does not provide any answer suggestions, so it can be a You can add ``regexp`` to the value of the ``type`` attribute, for example: ``type="ci regexp"`` or ``type="regexp"`` or ``type="regexp cs"``. In this case, any answer or hint will be treated as regular expressions.
good way to get the students to engage with the material more deeply in a
sequence and look up, figure out, or remember the correct answer themselves.
Note that a student's answer in a String Response is marked as correct if it **Sample Problem**
matches every character of the expected answer. This can be a problem with
international spelling, dates, or anything where the format of the answer is not
clear.
Sample Problem:
.. image:: ../Images/image291.png .. image:: ../Images/TextInputExample.gif
:width: 600
:alt: Image of a string response problem :alt: Image of a string response problem
**Problem Code:** **XML Tags**
.. list-table::
:widths: 20 80
* - ``<stringresponse>``
- Indicates that the problem is a text input problem.
* - ``<textline>``
- Child of ``<stringresponse>``. Lists the answer options.
* - ``<additional_answer>`` (optional)
- Specifies an additional correct answer for the problem. A problem can contain an unlimited number of additional answers.
* - ``<hintgroup>`` (optional)
- Indicates that the instructor has provided hints for certain common incorrect answers.
* - ``<stringhint />`` (optional)
- Child of ``<hintgroup>``. Specifies the text of the incorrect answer to provide the hint for. Contains answer, type, name.
* - ``<hintpart>``
- Contains the name from ``<stringhint>``. Associates the incorrect answer with the hint text for that incorrect answer.
* - ``<startouttext />``
- Indicates the beginning of the text of the hint.
* - ``<endouttext />``
- Indicates the end of the text of the hint.
**Sample Problem Code**
.. code-block:: xml .. code-block:: xml
<problem> <problem>
<p><b>Example Problem</b></p> <p>
<p>What is the name of this unit? (What response type is this?)</p> <em>This problem is adapted from an exercise that first appeared in MITx's 14.73x The Challenges of Global Poverty course, spring 2013.</em>
<stringresponse answer="String Response" type="ci"> </p>
<p>What is the technical term that refers to the fact that, when enough people sleep under a bednet, the disease may altogether disappear?</p>
<stringresponse answer=".*herd immunity.*" type="ci regexp">
<additional_answer>community immunity</additional_answer>
<additional_answer>population immunity</additional_answer>
<textline size="20"/> <textline size="20"/>
<hintgroup>
<stringhint answer="contact immunity" type="ci" name="contact_immunity_hint" />
<hintpart on="contact_immunity_hint">
<startouttext />
In contact immunity, a vaccinated individual passes along his immunity to another person through contact with feces or bodily fluids. The answer to the question above refers to the form of immunity that occurs when so many members of a population are protected, an infectious disease is unlikely to spread to the unprotected population.
<endouttext />
</hintpart >
<stringhint answer="firewall immunity" type="ci" name="firewall_immunity_hint" />
<hintpart on="firewall_immunity_hint">
<startouttext />
Although a firewall provides protection for a population, the term "firewall" is used more in computing and technology than in epidemiology.
<endouttext />
</hintpart >
</hintgroup>
</stringresponse> </stringresponse>
<solution> <solution>
<div class="detailed-solution"> <div class="detailed-solution">
<p>Explanation</p> <p>Explanation</p>
<p>The name of this unit is "String Response," written without the punctuation.</p> <p>The correct answer is <b>herd immunity</b>. As more and more people use bednets, the risk of malaria begins to fall for everyone – users and non-users alike. This can fall to such a low probability that malaria is effectively eradicated from the group (even when the group does not have 100% bednet coverage).</p>
<p>Arbitrary capitalization is accepted.</p>
</div> </div>
</solution> </solution>
</problem> </problem>
...@@ -988,50 +1158,34 @@ Sample Problem: ...@@ -988,50 +1158,34 @@ Sample Problem:
.. code-block:: xml .. code-block:: xml
<problem> <problem>
<stringresponse answer="REPLACE_THIS" type="ci"> <p>Problem text</p>
<textline size="20"/> <stringresponse answer="**.Correct answer 1.**" type="ci regexp">
</stringresponse> <additional_answer>Correct answer 2</additional_answer>
<solution> <additional_answer>Correct answer 3</additional_answer>
<div class="detailed-solution">
</div>
</solution>
</problem>
This response type allows to add more than one answer. Use `additional_answer` tag to add more answers.
You can add `regexp` to value of `type` attribute, for example: `type="ci regexp"` or `type="regexp"` or `type="regexp cs"`.
In this case, any answer and hint will be treated as regular expressions.
Regular expression has to match whole answer, for answer to be correct.
Student answers "foobar", "o foo" or " ==foo==", will be correct if teacher has set answer=".*foo.*" with type="regexp".
**Template**
.. code-block:: xml
<problem>
<stringresponse answer="a1" type="ci regexp">
<additional_answer>\d5</additional_answer>
<additional_answer>a3</additional_answer>
<textline size="20"/> <textline size="20"/>
<hintgroup> <hintgroup>
<stringhint answer="a0" type="ci" name="ha0" /> <stringhint answer="Incorrect answer A" type="ci" name="hintA" />
<stringhint answer="a4" type="ci" name="ha4" /> <hintpart on="hintA">
<stringhint answer="^\d" type="ci" name="re1" /> <startouttext />Text of hint for incorrect answer A<endouttext />
<hintpart on="ha0">
<startouttext />+1<endouttext />
</hintpart > </hintpart >
<hintpart on="ha4"> <stringhint answer="Incorrect answer B" type="ci" name="hintB" />
<startouttext />-1<endouttext /> <hintpart on="hintB">
<startouttext />Text of hint for incorrect answer B<endouttext />
</hintpart > </hintpart >
<hintpart on="re1"> <stringhint answer="Incorrect answer C" type="ci" name="hintC" />
<startouttext />Any number+5<endouttext /> <hintpart on="hintC">
<startouttext />Text of hint for incorrect answer C<endouttext />
</hintpart > </hintpart >
</hintgroup> </hintgroup>
</stringresponse> </stringresponse>
<solution>
<div class="detailed-solution">
<p>Explanation or Solution Header</p>
<p>Explanation or solution text</p>
</div>
</solution>
</problem> </problem>
**XML Attribute Information** **XML Attribute Information**
<stringresponse> <stringresponse>
...@@ -1090,17 +1244,3 @@ Student answers "foobar", "o foo" or " ==foo==", will be correct if teacher has ...@@ -1090,17 +1244,3 @@ Student answers "foobar", "o foo" or " ==foo==", will be correct if teacher has
<textline> <textline>
.. image:: ../Images/stringresponse2.png .. image:: ../Images/stringresponse2.png
\ No newline at end of file
<additional_answer> - Can be unlimited number of this tags. Any tag adds one more additional answer for matching.
...@@ -4,7 +4,6 @@ ...@@ -4,7 +4,6 @@
Change Log Change Log
********** **********
.. list-table:: .. list-table::
:widths: 10 80 :widths: 10 80
:header-rows: 1 :header-rows: 1
...@@ -12,10 +11,12 @@ Change Log ...@@ -12,10 +11,12 @@ Change Log
* - Date * - Date
- Change - Change
* - 02/14/14 * - 02/14/14
- Added :ref:`Additional Transcripts` section to :ref:`Working with Video Components`; updated :ref:`Video Advanced Options` - Added :ref:`Additional Transcripts` section to :ref:`Working with Video Components`;
updated :ref:`Video Advanced Options`
* -
- Added the :ref:`Course Data`, :ref:`Course_Staffing`, and :ref:`Enrollment` chapters. - Added the :ref:`Course Data`, :ref:`Course_Staffing`, and :ref:`Enrollment` chapters.
* - 02/11/14 * - 02/11/14
- Added :ref:`Gene Editor` and updated :ref:`Interactive Periodic Table` and :ref:`Molecule Editor` in :ref:`Additional Tools` - Added :ref:`Gene Explorer` and updated :ref:`Interactive Periodic Table` and :ref:`Molecule Editor` in :ref:`Additional Tools`
* - 02/07/14 * - 02/07/14
- Added section on :ref:`Full Screen Image`. - Added section on :ref:`Full Screen Image`.
* - 02/06/14 * - 02/06/14
......
...@@ -398,7 +398,7 @@ Case Sensitivity and Text Input Problems ...@@ -398,7 +398,7 @@ Case Sensitivity and Text Input Problems
By default, text input problems do not require a case sensitive response. You can change this By default, text input problems do not require a case sensitive response. You can change this
and require a case sensitive answer. and require a case sensitive answer.
To make a text input response case sensitive, you must use the :ref:`Advanced Editor`. To make a text input response case sensitive, you must use :ref:`Advanced Editor`.
In the advanced editor, you see that the **type** attribute of the **stringresponse** In the advanced editor, you see that the **type** attribute of the **stringresponse**
element equals **ci**, for *case insensitive*. For example: element equals **ci**, for *case insensitive*. For example:
...@@ -426,7 +426,7 @@ By default, the response field for text input problems is 20 characters long. ...@@ -426,7 +426,7 @@ By default, the response field for text input problems is 20 characters long.
You should preview the unit to ensure that the length of the response input field You should preview the unit to ensure that the length of the response input field
accommodates the correct answer, and provides extra space for possible incorrect answers. accommodates the correct answer, and provides extra space for possible incorrect answers.
If the default response field length is not sufficient, you can change it using the :ref:`Advanced Editor`. If the default response field length is not sufficient, you can change it using :ref:`Advanced Editor`.
In the advanced editor, in the XML block for the answer, you see that the **size** attribute of the **textline** In the advanced editor, in the XML block for the answer, you see that the **size** attribute of the **textline**
element equals **20**: element equals **20**:
...@@ -444,3 +444,9 @@ To change the response field length, change the value of the **size** attribute: ...@@ -444,3 +444,9 @@ To change the response field length, change the value of the **size** attribute:
<stringresponse answer="Democratic Republic of the Congo" type="ci"> <stringresponse answer="Democratic Republic of the Congo" type="ci">
<textline size="40"/> <textline size="40"/>
</stringresponse> </stringresponse>
====================================================
Hints and Regular Expressions in Text Input Problems
====================================================
You can provide hints for common incorrect answers in text input problems. You can also set a text input problem to allow a regular expression as an answer. To do this, you'll have to modify the problem's XML in the Advanced Editor. For more information, see :ref:`String Response`.
\ No newline at end of file
...@@ -3,24 +3,37 @@ ...@@ -3,24 +3,37 @@
import sys, os import sys, os
# on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org
on_rtd = os.environ.get('READTHEDOCS', None) == 'True' on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
sys.path.append(os.path.abspath('../../../../')) if not on_rtd: # only import and set the theme if we're building docs locally
import sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme'
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
sys.path.append(os.path.abspath('../../../')) sys.path.append(os.path.abspath('../../../'))
sys.path.append(os.path.abspath('../../'))
from docs.shared.conf import * #from docs.shared.conf import *
sys.path.insert(0, os.path.abspath('.')) sys.path.insert(0, os.path.abspath('.'))
master_doc = 'index' master_doc = 'index'
# Add any paths that contain templates here, relative to this directory. # Add any paths that contain templates here, relative to this directory.
templates_path.append('source/_templates') #templates_path.append('source/_templates')
# Add any paths that contain custom static files (such as style sheets) here, # Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files, # relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css". # so a file named "default.css" will overwrite the builtin "default.css".
html_static_path.append('source/_static') #html_static_path.append('source/_static')
# General information about the project. # General information about the project.
......
...@@ -24,4 +24,3 @@ To view course data: ...@@ -24,4 +24,3 @@ To view course data:
.. You also use the Instructor Dashboard to set up the staff for your course, enroll students and access student data, and initiate, review, and adjust grades. .. You also use the Instructor Dashboard to set up the staff for your course, enroll students and access student data, and initiate, review, and adjust grades.
**Question**: I initially thought that there was enough information available about the course as a whole to make this into a longer chapter. Am I missing features or tasks that instructors use to get information about a course? It doesn't have to be something accessible on the instructor dashboard, but just info that might be useful while a course is running...
\ No newline at end of file
...@@ -190,7 +190,7 @@ To encourage longer, threaded discussions rather than many similar, separate pos ...@@ -190,7 +190,7 @@ To encourage longer, threaded discussions rather than many similar, separate pos
You can respond to a redundant post or response by pasting in a link to the thread that you prefer students to contribute to, and then prevent further thread interaction by closing the entire post or a specific response. Click the **Close** button that displays below the post or response to close it. You can respond to a redundant post or response by pasting in a link to the thread that you prefer students to contribute to, and then prevent further thread interaction by closing the entire post or a specific response. Click the **Close** button that displays below the post or response to close it.
* Provide post/response/comment guidelines. * Provide post/response/comment guidelines.
A set of :ref:`Discussion Forum Guidelines` or a post in the General discussion can provide guidance about when to create a new thread, respond to an existing post, or comment on a response. A set of :ref:`Guidance for Discussion Moderators` or a post in the General discussion can provide guidance about when to create a new thread, respond to an existing post, or comment on a response.
.. _Moderating_discussions: .. _Moderating_discussions:
......
...@@ -61,7 +61,7 @@ C ...@@ -61,7 +61,7 @@ C
**Chemical Equation Response Problem** **Chemical Equation Response Problem**
A problem that allows the student to enter chemical equations as answers. For more information, see :ref:`Chemical Equation Response`. A problem that allows the student to enter chemical equations as answers. For more information, see :ref:`Chemical Equation`.
.. _Circuit Schematic Builder Problem: .. _Circuit Schematic Builder Problem:
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment