diff --git a/.gitignore b/.gitignore index fbf7a2fca..bea14c073 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,4 @@ build .DS_Store source/.DS_Store .idea/ +sphinx-env/ diff --git a/source/conf.py b/source/conf.py index ae78b2e3d..841c55ed6 100644 --- a/source/conf.py +++ b/source/conf.py @@ -124,6 +124,7 @@ "default_image_width": "60%", } +# 'migration_wip' links.rst added while migration is underway. Should be removed after migration. rst_epilog = """ .. raw:: html @@ -136,6 +137,7 @@ .. include:: /substitutions.txt .. include:: /links.txt +.. include:: /educators/migration_wip/links/links.rst """ diff --git a/source/educators/migration_wip/10_exercises_tools/Section_adding_hints.rst b/source/educators/migration_wip/10_exercises_tools/Section_adding_hints.rst new file mode 100644 index 000000000..1c41d276d --- /dev/null +++ b/source/educators/migration_wip/10_exercises_tools/Section_adding_hints.rst @@ -0,0 +1,139 @@ +.. _Adding Feedback and Hints to a Problem: + +======================================= +Adding Feedback and Hints to a Problem +======================================= + +You can add feedback, hints, or both to the simple problem types. + +By using hints and feedback, you can provide learners with guidance and help as +they work on problems. + +------------------------------------------ +Feedback in Response to Attempted Answers +------------------------------------------ + +You can add feedback that displays to learners after they submit an answer. + +For example, the following single select problem provides feedback in +response to the selected option when the learner selects **Submit**. In this +case, feedback is given for an incorrect answer. + +.. image:: ../images/multiple_choice_feedback.png + :alt: Image of a single select problem with feedback. + :width: 600 + +------------------------------------------ +Best Practices for Providing Feedback +------------------------------------------ + +The immediacy of the feedback available to learners is a key advantage of +online instruction and difficult to do in a traditional classroom environment. + +You can target feedback for common incorrect answers to the misconceptions that +are common for the level of the learner (for example, elementary, middle, high +school, college). + +In addition, you can create feedback that provides some guidance to the learner +about how to arrive at the correct answer. This is especially important in text +input and numeric input problems, because without such guidance, learners might +not be able to proceed. + +You should also include feedback for the correct answer to reinforce why the +answer is correct. Especially in questions where learners are able to guess, +such as single select and dropdown problems, the feedback should provide a +reason why the selection is correct. + +------------------------------------------ +Providing Hints for Problems +------------------------------------------ + +You can add one or more hints that are displayed to learners. When you add +hints, the **Hint** button is automatically displayed to learners. Learners can +access the hints by selecting **Hint** beneath the problem. A learner can view +multiple hints by selecting **Hint** multiple times. + +For example, in the following single select problem, the learner selects +**Hint** after having made one incorrect attempt. + +.. image:: ../images/multiple_choice_hint.png + :alt: Image of a single select problem with the first hint. + :width: 600 + +The hint text indicates that it is the first of two hints. After the learner +selects **Next Hint**, both of the available hints appear. When all hints have +been used, the **Hint** or **Next Hint** option is no longer available. + +.. image:: ../images/multiple_choice_hint2.png + :alt: Image of a single select problem with the second hint. + :width: 600 + +------------------------------------------ +Best Practices for Providing Hints +------------------------------------------ + +To ensure that your hints can assist learners with varying backgrounds and +levels of understanding, you should provide multiple hints with different +levels of detail. + +For example, the first hint can orient the learner to the problem and help +those struggling to better understand what is being asked. + +The second hint can then take the learner further towards the answer. + +In problems that are not graded, the third and final hint can explain the +solution for learners who are still confused. + +------------------------------------------ +Create Problems with Feedback and Hints +------------------------------------------ + +While editing a problem block, you can apply **Answer-specific feedback** +for all problem types. **Group feedback** can only be applied to +**multi-select** problems. + +Any number of **hints** can be added for all simple problem types. + +------------------------------------------ +Adding Answer-specific Feedback +------------------------------------------ + +**Answer-specific feedback** can be added under each answer by pressing +the feedback icon to the right of the answer text. Feedback entered in +these fields are given when the learner selects that answer or when the +learner does not select that answer. + +.. image:: ../images/problem_editor_feedback_box.png + :alt: Image of the answer-specific feedback settings. + :width: 600 + +.. note:: + The “is not selected” feedback field shown above is only available + for the **multi-select** problem type. + +------------------------------------------------ +Adding Group Feedback for Multi-Select Problems +------------------------------------------------ + +This setting can be found on the collapsible settings to the right of +the problem editor. Feedback entered in this field will display if and +only if the learner selects all of the checked answers. Click the +**Add group feedback** button to add additional feedback for different +groups of checked answers. **Group feedback** can only be applied for +the **multi-select** problem type. + +.. image:: ../images/problem_editor_group_feedback_box.png + :alt: Image of the group feedback settings. + :width: 300 + +------------------------------------------ +Adding Hints +------------------------------------------ + +This setting can be found on the collapsible settings to the right of +the problem editor. Click the **Add hint** button to add additional +hints for learners. + +.. image:: ../images/problem_editor_hints_box.png + :alt: Image of the hints settings. + :width: 300 diff --git a/source/educators/migration_wip/10_exercises_tools/Subsection_configure_hints.rst b/source/educators/migration_wip/10_exercises_tools/Subsection_configure_hints.rst new file mode 100644 index 000000000..902b02786 --- /dev/null +++ b/source/educators/migration_wip/10_exercises_tools/Subsection_configure_hints.rst @@ -0,0 +1,12 @@ +In the settings panels on the right of the editor, you'll find a Hints panel. + +.. image:: ../images/problem_editor_hints_box.png + :alt: An example of the hints settings panel. + :width: 200 + +Click the **Add hint** button to add a new hint text field. To delete any hints +you've added, click the trash can icon next to its respective hint field. + +.. note:: + You can configure any number of hints. The learner views one hint at a time + and views the next one by selecting **Hint** again. diff --git a/source/educators/migration_wip/10_exercises_tools/Subsection_configure_hints_advanced.rst b/source/educators/migration_wip/10_exercises_tools/Subsection_configure_hints_advanced.rst new file mode 100644 index 000000000..312e6ec1b --- /dev/null +++ b/source/educators/migration_wip/10_exercises_tools/Subsection_configure_hints_advanced.rst @@ -0,0 +1,33 @@ + +In the advanced editor, you add the ```` element immediately before +the closing ```` tag, and then configure each hint using the +```` element. + +.. code-block:: xml + + + . + . + . + + Hint 1 + Hint 2 + Hint 3 + + + +For example, the following OLX for a single select problem shows two hints. + +.. code-block:: xml + + + + . + . + . + + + A fruit is the fertilized ovary from a flower. + A fruit contains seeds of the plant. + + diff --git a/source/educators/migration_wip/10_exercises_tools/Subsection_customizing_feedback_labels.rst b/source/educators/migration_wip/10_exercises_tools/Subsection_customizing_feedback_labels.rst new file mode 100644 index 000000000..8e4a6bc87 --- /dev/null +++ b/source/educators/migration_wip/10_exercises_tools/Subsection_customizing_feedback_labels.rst @@ -0,0 +1,47 @@ +----------------------------- +Customizing Feedback Labels +----------------------------- + +By default, the feedback labels shown to learners are **Correct** and +**Incorrect**. If you do not define feedback labels, learners see these terms +when they submit an answer, as in the following example. + +:: + + Incorrect: A pumpkin is the fertilized ovary of a squash plant and contains + seeds classifying it as a fruit. + +You can configure the problem to override the default labels. For example, you +can configure a custom label for a specific wrong answer. + +:: + + Not Quite: Many people mistakenly think a tomato is a vegetable. However, + because a tomato is the fertilized ovary of a tomato plant and contains seeds + it is classified as a fruit. + +In the :ref:`advanced editor`, you configure custom feedback +labels with the following syntax. + +.. code-block:: xml + + Answer + Feedback for learners who select this + answer. + + +For example, the feedback for the following answer option is configured to use +a custom label. + +.. code-block:: xml + + tomato + Many people mistakenly think a tomato is a + vegetable. However, because a tomato is the fertilized ovary of a tomato + plant and contains seeds, it is a fruit. + + +.. note:: + The default labels **Correct** and **Incorrect** display in the learner's + requested language. If you provide custom labels, they display as you define + them to all learners. They are not translated into different languages. diff --git a/source/educators/migration_wip/10_exercises_tools/annotation.rst b/source/educators/migration_wip/10_exercises_tools/annotation.rst new file mode 100644 index 000000000..0c8f22acf --- /dev/null +++ b/source/educators/migration_wip/10_exercises_tools/annotation.rst @@ -0,0 +1,94 @@ +.. _Annotation: + +################### +Annotation Problem +################### + +.. note:: EdX does not support this problem type. + +In an annotation problem, you highlight specific text inside a larger text +block and then ask questions about that text. The questions appear when +learners move their cursors over the highlighted text. The questions also +appear in a section below the text block, along with space for learners' +responses. + +.. image:: ../images/AnnotationExample.png + :alt: An example annotation problem. + +.. contents:: + :local: + :depth: 1 + +***************************** +Enable Annotation Problems +***************************** + +Before you can add annotation problems to your course, you must enable +annotation problems in Studio. + +To enable annotation problems in Studio, you add the ``"annotatable"`` key to +the **Advanced Module List** on the **Advanced Settings** page. (Be sure to +include the quotation marks around the key value.) For more information, see +:ref:`Enable Additional Exercises and Tools`. + +**************************** +Create an Annotation Problem +**************************** + +To create an annotation problem, you add the **Instructions** and **Guided +Discussion** segments of the problem, and then the **Annotation problem** +segment of the problem. + +============================================ +Add Instructions and Guided Discussion +============================================ + +To add the **Instructions** and **Guided Discussion** segments of the problem, +follow these steps. + +#. In the unit where you want to create the problem, under **Add New + Component** select **Advanced**. + +#. In the list of problem types, select **Annotation**. + +#. In the component that appears, select **Edit**. + +#. In the component editor, replace the example code with your own code. + +#. Select **Save**. + +================================= +Add Annotation Problem +================================= + +To add the **Annotation problem** segment of the problem, follow these steps. + +#. Under the annotation component, create a new blank advanced problem + component. + +#. Paste the following code in the advanced problem component, replacing + placeholders with your own information. + + .. code-block:: xml + + + + + PLACEHOLDER: Text of annotation + PLACEHOLDER: Text of question + PLACEHOLDER: Type your response below: + PLACEHOLDER: In your response to this question, which tag below do you choose? + + + + + + + + +

PLACEHOLDER: Detailed explanation of solution

+ + + +#. Select **Save**. diff --git a/source/educators/migration_wip/10_exercises_tools/calculator.rst b/source/educators/migration_wip/10_exercises_tools/calculator.rst new file mode 100644 index 000000000..045b6b48b --- /dev/null +++ b/source/educators/migration_wip/10_exercises_tools/calculator.rst @@ -0,0 +1,56 @@ +.. _Calculator: + +################## +Calculator Tool +################## + +.. note:: EdX offers provisional support for this tool. + +.. contents:: + :local: + :depth: 1 + +********** +Overview +********** + +Learners can use the edX calculator tool to perform simple +and complex calculations. Learners can enter input including numbers, +operators, Greek letters, affixes, trigonometric functions, and more. + +The calculator is available for every edX course, but it is not visible by +default. To make the calculator visible, you must enable it in the course +advanced settings. + +When the calculator is visible in a course, the calculator icon appears at the +bottom of every unit page. + +.. image:: ../images/Calc_Closed.png + :width: 600 + :alt: Course page with an arrow pointing to the calculator. + +When learners select the calculator icon, the calculator opens along the lower +edge of the browser window. + +The calculator includes an information page that learners can use if they have +questions about entering input in the calculator. Learners access the +calculator's information page by selecting the ``i`` icon next to the input +field. + +.. image:: ../images/Calc_Open_InfoPage.png + :width: 600 + :alt: Course page with the calculator visible along the edge of the browser. + +Learners close the calculator by selecting the X. + + +************************************ +Enable the Calculator Tool +************************************ + +To enable the calculator tool, follow these steps. + +#. In Studio, from the **Content** menu select **Pages & Resources**. +#. Click the gear icon on the **Calculator** card shown on this page. +#. From the **Configure calculator** modal, select the toggle to enable or disable the notes application. +#. Select **Apply** to save your configuration changes. diff --git a/source/educators/migration_wip/10_exercises_tools/checkbox.rst b/source/educators/migration_wip/10_exercises_tools/checkbox.rst new file mode 100644 index 000000000..dd52aecf8 --- /dev/null +++ b/source/educators/migration_wip/10_exercises_tools/checkbox.rst @@ -0,0 +1,10 @@ +:orphan: + +.. _Checkbox: + +######################################## +Checkbox +######################################## + +.. note:: + See :ref:`Multi-select` for documentation \ No newline at end of file diff --git a/source/educators/migration_wip/10_exercises_tools/chemical_equation.rst b/source/educators/migration_wip/10_exercises_tools/chemical_equation.rst new file mode 100644 index 000000000..527d68a37 --- /dev/null +++ b/source/educators/migration_wip/10_exercises_tools/chemical_equation.rst @@ -0,0 +1,184 @@ +.. _Chemical Equation: + +################################ +Chemical Equation Problem +################################ + +.. note:: EdX does not support this problem type. + +The chemical equation problem type allows the learner to enter text that +represents a chemical equation into a text box. The system converts that text +into a chemical equation below the text box. The grader evaluates the +learner's response 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. + +.. contents:: + :local: + :depth: 1 + +.. note:: + You can make a calculator available to your learners on every + unit page. For more information, see :ref:`Calculator`. + +********************************************** +Create a Chemical Equation Problem +********************************************** + +Chemical equation problems use MathJax to create formulas. For more +information about using MathJax in Studio, see :ref:`MathJax in Studio`. + +To create the above chemical equation problem, follow these steps. + +#. In the unit where you want to create the problem, select **Problem** under + **Add New Component**. +#. Select **Advanced problem types**. Then select **Blank Advanced Problem**. +#. In the component that appears, select **Edit**. +#. In the component editor, paste the code from below. +#. Select **Save**. + +========================================== +Sample Chemical Equation Problem Code +========================================== + +.. code-block:: xml + + + +

Some problems may ask for a particular chemical equation. Practice by writing out the following reaction in the box below.

+ + \( \text{H}_2\text{SO}_4 \longrightarrow \text { H}^+ + \text{ HSO}_4^-\) + + + + + + if chemcalc.chemical_equations_equal(submission[0], 'H2SO4 -> H^+ + HSO4^-'): + correct = ['correct'] + else: + correct = ['incorrect'] + + + +

Some tips:

+
    +
  • Use real element symbols.
    • +
  • Create subscripts by using plain text.
    • +
  • Create superscripts by using a caret (^).
    • +
  • Create the reaction arrow (\(\longrightarrow\)) by using "->".
    • +
+ + + + +
+

Solution

+

To create this equation, enter the following:

+

H2SO4 -> H^+ + HSO4^-

+
+ + + +.. _Chemical Equation Problem XML: + +************************************ +Chemical Equation Problem XML +************************************ + +============ +Template +============ + +.. code-block:: xml + + + +

Problem text

+ + + + + + if chemcalc.chemical_equations_equal(submission[0], 'TEXT REPRESENTING CHEMICAL EQUATION'): + correct = ['correct'] + else: + correct = ['incorrect'] + + + + + + + +
+

Solution or Explanation Header

+

Solution or explanation text

+
+ + + +====== +Tags +====== + +* ````: Indicates that this problem has a custom response. +* ````: Specifies that the answer to this problem is a + chemical equation. +* ````: Contains the Python script that grades the + problem. + +**Tag:** ```` + +Indicates that this problem has a custom response. The ```` +tags must surround the ```` tags. + + **Attributes** + + (none) + + **Children** + + * ```` + * ```` + +**Tag:** ```` + +Indicates that the answer to this problem is a chemical equation and creates a +response field where the learner enters an answer. + + **Attributes** + + .. list-table:: + :widths: 20 80 + + * - Attribute + - Description + * - size + - Specifies the size of the response field, in characters. + * - label (required) + - Contains the text of the principal question in the problem. + + **Children** + + (none) + +**Tag:** ```` + +Contains the Python script that grades the problem. + + **Attributes** + + .. list-table:: + :widths: 20 80 + + * - Attribute + - Description + * - type (required) + - Must be "loncapa/python". + + **Children** + + (none) + diff --git a/source/educators/migration_wip/10_exercises_tools/circuit_schematic_builder.rst b/source/educators/migration_wip/10_exercises_tools/circuit_schematic_builder.rst new file mode 100644 index 000000000..5c7499a1d --- /dev/null +++ b/source/educators/migration_wip/10_exercises_tools/circuit_schematic_builder.rst @@ -0,0 +1,160 @@ +.. _Circuit Schematic Builder: + +################################## +Circuit Schematic Builder Problem +################################## + +.. note:: EdX does not support this problem type. + +In circuit schematic builder problems, students can arrange circuit elements +such as voltage sources, capacitors, resistors, and MOSFETs on an interactive +grid. They then submit a DC, AC, or transient analysis of their circuit to the +system for grading. + +.. image:: ../images/CircuitSchematicExample.png + :alt: A problem that asks learners to use the circuit schematic builder to + build a mixer that combines the signals generated by two voltage sources. + :width: 600 + +********************************************* +Create a Circuit Schematic Builder Problem +********************************************* + +#. In the unit where you want to create the problem, under **Add New + Component** select **Problem**. +#. In the problem editor, select **Advanced problem types**. Then select + **Circuit Schematic Builder**. +#. In the advanced problem editor, replace the example code with your own code. +#. Select **Save**. + +**Problem Code** + +The illustration above shows a condensed version of an actual problem from +MITx's 6.002.1x. To create the entire problem, paste the following code into +the advanced editor. + +.. code-block:: xml + + +

A circuit that combines two or more signals is called a mixer. In + this lab, your goal is to build a mixer that combines the signals generated + by two voltage sources, V1 and V2, where:

+
    +
  • +

    V1 is a 1 kHz square wave that varies between 0V and +1V, and

    +
    • +
  • +

    V2 is a 5 kHz sine wave that varies between -1V and +1V.

    +
    • +
+

Please design a circuit that mixes V1 and V2 to produce Vout such that

+
\[V_\mathrm{out} \approx \frac{1}{2}V_1 + \frac{1}{6}V_2.\]
+

The resulting output should be similar to that shown in Figure 1. The + maximum value of the output is approximately \(667mV\) and the minimum value + is approximately \(-167mV\).

+

Figure 1. Desired output waveform
+

Hint: Figure 2 shows a simple resistive mixer for combining two signals.

+

Figure 2. Simple resistive mixer
+

Enter your circuit below, using the appropriate configuration of + resistors. Please do not modify the wiring or parameters of the voltage + sources -- your goal is to take the signals they generate and combine them, + not to change what is generated. Run a 5ms transient analysis to verify the + correct operation of your circuit. We will be checking for the transient + waveform at the "output" node.

+ +
+ +
+ + # for a schematic response, submission[i] is the json representation + # of the diagram and analysis results for the i-th schematic tag + + def get_tran(json,signal): + for element in json: + if element[0] == 'transient': + return element[1].get(signal,[]) + return [] + + output = get_tran(submission[0],'output') + + answer = [[0.00025, 0.666], + [0.00035, 0.333], + [0.00065, 0.166], + [0.00075, -0.166]] + + okay = True + if not output or output[0][1] == 'undefined': # No transient or output node floating + okay = False + else: + for (at,av) in answer: + for (t,v) in output: + if at==t and abs(av - v) < 0.05*abs(av): + # found a good match for this answer, on to the next one + break + else: + print 'check',at,av + # no submission matched answer, complain + okay = False; + break; + + correct = ['correct' if okay else 'incorrect'] + + + +

When you're done or if you wish to save your work, please click CHECK. + The checker will be verifying the voltage of the output node at several + different times, so you'll earn a point only after you've performed + the transient simulation so that the checker will have a waveform to check!

+ +

Explanation:

+

The goal is to design a mixer circuit with characteristics of + \(V_{out}=\frac{1}{2}\cdot V_1+\frac{1}{6}\cdot V_2\) + You might have started to design your mixer with two resistors only as the example suggests. + But working through the math, soon you'll realize that the equations return no non-zero value for the resistor components. + Thus you have to change the design. The next simplest design will be to add a resistor \(R_3\) that connects the node Vout to ground. + See the schematic below:

+ +

Since we are going to use only linear elements in this circuit + (resistors are linear), superposition will hold + and thus one can look at the effect of each source \(V_1\) and \(V_2\) + one at the time:

+ [mathjax] V_{out1} = V_1 \cdot \frac{\left(R_2 \parallel R_3\right)} + {\left(R_2 \parallel R_3+R_1\right)}\\ V_{out2} = V_2 \cdot + \frac{\left(R_1 \parallel R_3\right)}{\left(R_1 \parallel R_3+R_2\right)} + \\ V_{out} = V_{out 1} + V_{out 2} \\ V_{out} = V_1 \cdot + \frac{\left(R_2 \parallel R_3\right)}{\left(R_2\parallel R_3+R_1\right)} + + V_2 \cdot \frac{\left(R_1 \parallel R_3\right)}{\left(R_1 \parallel R_3 + + R_2\right)} = \frac{1}{2} \cdot V_1+\frac{1}{6} \cdot V_2 [/mathjax] +

Therefore:

+ [mathjax] \frac{ \left(R_2 \parallel R_3 \right) } + { \left( R_2 \parallel R_3 + R_1 \right)} = + \frac{1}{2} \\\frac{\left( R_1 \parallel R_3 \right) } + { \left(R_1 \parallel R_3 + R_2 \right)} = \frac{1}{6} [/mathjax] +

So we have to solve for the resistors given these two equations. You + might notice that we have 2 equations and 3 unknowns, and that there is + therefore not a unique solution. That is okay, though. We only have to + worry if there is no solution, not if there are too many solutions. We will + simply find one of the many possible correct answers by arbitrarily + choosing a value for one of the variables later.

+

The first equation simplifies to \( R_1 = R_2\parallel R_3\) and the + second simplifies to \(R_2 = 5 \cdot R_1\parallel R_3\) + Expanding the notation gives:

+ [mathjax]\frac{1}{R_1}=\frac{1}{R_2}+\frac{1}{R_3} + \tag{*} \\\frac{1}{R_1}+\frac{1}{R_3}=\frac{5}{R_2} [/mathjax] +

Subtracting these two equations will yield \(R_2 = 2 \cdot R_3\) + And putting this back to the starred equation , will result in + \(R_1 = \frac{2}{3} \cdot R_3\) + So now we have \(R_2\) and \(R_1\) in terms of \(R_3\) with the following + ratios:

+ [mathjax]R_2 = 2 \cdot R_3 \\ R_1 = \frac{2}{3} \cdot R_3 \\[/mathjax] +

Since the design hadn't mentioned anything about the resistances, one can + use a simple value of \(R_3= 3Ω\) and find the rest accordingly:

+ [mathjax]R_1= 2Ω \\ + R_2= 6Ω \\ + R_3= 3Ω \\ + [/mathjax] +

With these resistor values, doing a transient analysis shows a result which meets the required specs of \(V_{out}\).

+
+ + + diff --git a/source/educators/migration_wip/10_exercises_tools/completion.rst b/source/educators/migration_wip/10_exercises_tools/completion.rst new file mode 100644 index 000000000..a46a04437 --- /dev/null +++ b/source/educators/migration_wip/10_exercises_tools/completion.rst @@ -0,0 +1,119 @@ +.. _completion: + +################## +Completion Tool +################## + +.. note:: EdX does not support this tool. + +The completion tool provides learners with a way to mark sections of the +course as completed. It helps learners to track their progress through +sections of the course, including for ungraded activities such as reading +text, watching video, or participating in course discussions. + +.. contents:: + :local: + :depth: 1 + +*********** +Overview +*********** + +The completion tool provides learners with a way to indicate both to themselves +and to the course team that they have completed an activity. + +The completion tool is itself a graded component and is therefore always +included on the learner **Progress** page. However, depending on whether it is +used in a graded or ungraded section of the course, it appears either as a +part of the learner's final grade or as a practice score, respectively. + +If you use the completion tool in an ungraded section of the course, the score +for completing the activity that it is associated with is listed as a practice +score on the **Progress** page. Practice scores are not included in the +learner's final grade for the course. + +You can also use the completion tool in graded sections of the course. If you +do so, a score for completing the activity is included in learners' final +grades. For example, if you include a completion component in a particular unit +of the course content, learners who use the component to mark the unit as +complete receive 1/1 points, while learners who do not mark the unit as +complete receive 0/1 points. These scores are included in learners' final +grades on the **Progress** page. + +.. note:: EdX recommends using the completion tool primarily to track progress + for ungraded activities such as reading assigned texts, watching videos, + or participating in course discussions. + + +========================= +The Completion Control +========================= + +When you add a completion component to a unit, learners see a control that is +labeled **Mark as complete**. In this example, the completion component follows +a Text component. + +.. image:: ../images/completion_markcomplete.png + :alt: The completion component in an incomplete state. + :width: 400 + +After a learner selects this control, the label changes to **Unmark**. Learners +who revisit their work in a unit and want to change the completion status can +select this control as many times as needed. + +.. image:: ../images/completion_unmark.png + :alt: The completion component in a complete state. + + +****************************************** +Enable the Completion Tool +****************************************** + +Before you can add a completion component to your course, you must enable the +completion tool in Studio. + +To enable the completion tool in Studio, add the ``"done"`` key to the +**Advanced Module List** on the **Advanced Settings** page, then select **Save +Changes**. (Be sure to include the quotation marks around the key value.) For +more information, see :ref:`Enable Additional Exercises and Tools`. + +************************************* +Add a Completion Component +************************************* + +After you have enabled the completion tool in Studio, to add a completion +component to a unit in a course, follow these steps. + +#. In the course outline in Studio, locate the unit to which you want to add + the completion component. +#. Under **Add New Component**, select **Advanced**. +#. Select **Completion**. + The completion component is added to the unit. + +.. note:: Select **Edit** in the completion component for information about the + tool. + + +.. only:: OLX + + **************************************** + Add the Completion Tool to an OLX Course + **************************************** + + To add the completion tool to a unit in an OLX (open learning XML) course, it + is sufficient to add the ```` tag to the OLX. + + EdX recommends that you also explicitly specify a ``url_name`` within the + ```` tag, as shown in the following example. If you do not explicitly + specify a ``url_name``, a value is automatically assigned, which can be + problematic if the same course is imported several times. For example, if the + ``url_name`` value is automatically generated each time you import your + course, and if you import your course more than once, the learner state for + the associated problems is lost each time a new ``url_name`` value is + assigned. + + .. code-block:: xml + + + + diff --git a/source/educators/migration_wip/10_exercises_tools/conditional_module.rst b/source/educators/migration_wip/10_exercises_tools/conditional_module.rst new file mode 100644 index 000000000..1a5335e07 --- /dev/null +++ b/source/educators/migration_wip/10_exercises_tools/conditional_module.rst @@ -0,0 +1,99 @@ +.. _Conditional Module: + +#################### +Conditional Module +#################### + +.. note:: EdX offers provisional support for this problem type. + +A conditional module controls the content that learners see after a response +that they make meets a certain condition. For example, learners who answer +"Yes" to a poll question see a different block of text from the learners who +answered "No" to the same question. + +******************** +Format description +******************** + +The main tag of conditional module input is ``conditional``. + +.. code-block:: xml + + ... + +``conditional`` can include any number of any Xmodule tags (``html``, +``video``, ``poll``, etc.) or ``show`` tags. + +==================== +``conditional`` Tag +==================== + +The main container for a single instance of a conditional module. The +following attributes can be specified for this tag. + +.. code-block:: xml + + sources - location id of required modules, separated by ';' + [message | ""] - message for case, where one or more are not passed. Here you can use variable {link}, which generate link to required module. + + [submitted] - map to `is_submitted` module method. + (pressing RESET button makes this function to return False.) + + [correct] - map to `is_correct` module method + [attempted] - map to `is_attempted` module method + [poll_answer] - map to `poll_answer` module attribute + [voted] - map to `voted` module attribute + +============ +``show`` Tag +============ + +Symlink to some set of Xmodules. The following attribute can be specified for +this tag. + +.. code-block:: xml + + sources - location id of modules, separated by ';' + +********* +Examples +********* + +======================================== +Example: conditional depends on poll +======================================== + +.. code-block:: xml + + + +

You see this because your vote value for "First question" was "man"

+ + + +======================================================== +Example: conditional depends on poll (use tag) +======================================================== + +.. code-block:: xml + + + + + + + +================================================ +Examples of conditional depends on problem +================================================ + +.. code-block:: xml + + + You see this because "lec27_Q1" was attempted. + + + You see this because "lec27_Q1" was not attempted. + diff --git a/source/educators/migration_wip/10_exercises_tools/create_exercises_and_tools.rst b/source/educators/migration_wip/10_exercises_tools/create_exercises_and_tools.rst new file mode 100644 index 000000000..5cb2885f1 --- /dev/null +++ b/source/educators/migration_wip/10_exercises_tools/create_exercises_and_tools.rst @@ -0,0 +1,505 @@ +.. _Create Exercises: + +############################### +Problems, Exercises, and Tools +############################### + +You can add a wide variety of different types of problems, exercises, and +tools to your course outline. By default, a core set of :ref:`problem +types` is available in Studio for you to +include in your course. You have the option to expand the initial set of core +problem types by enabling additional exercises and tools. + +.. contents:: + :local: + :depth: 2 + +.. _Levels of Support: + +****************** +Levels of Support +****************** + +.. only:: Open_edX + + .. note:: The support level definitions described in this section and the + level of support designated for each exercise, problem type, or tool are + applicable only to edx.org. + +The level of support that edX provides for each problem, exercise, or tool +varies. The levels of support are categorized as full, provisional, or no +support. This table provides the definition for each level of support. + +In Studio, the support level for each exercise, problem type, or tool is +represented with an icon when you select **Advanced**, **Text**, or +**Problem** to add a new component to your course. By default, only fully +supported or provisionally supported exercises, problem types, or tools are +available for adding to your course. To add unsupported problem types and +tools, see :ref:`Add_Unsupported_Exercises_Problems`. + +.. Internal note: For the OLX Guide there is a separate levels_of_support.rst file under olx/source/problem-xml that contains the levels of support info + + +.. list-table:: + :widths: 25 60 + :header-rows: 1 + + * - Level of Support + - Description + * - Full support + - Fully supported tools and features are available on edx.org, are fully + tested, have user interfaces where applicable, and are documented in the + official edX guides that are available on docs.edx.org. + * - Provisional support + - Provisionally supported tools and features are available on edx.org, + but might lack the robustness of functionality that your courses + require. Third party tools are classified as provisionally supported + because edX does not have control over the quality of the software, or + of the content that can be provided using such tools. + + You should test provisionally supported tools thoroughly + before using them in your course, especially in graded sections. + Complete documentation might not be available for provisionally + supported tools, or documentation might be available from sources other + than the official edX guides. + * - Not supported + - Exercises and tools with no support are not maintained by edX, and + might be deprecated in the future. They are not recommended for use in + courses due to non-compliance with one or more of the base + requirements, such as testing, accessibility, internationalization, and + documentation. + + +************************************************************** +Enhancing Your Course with Additional Exercises and Tools +************************************************************** + +"Exercises and tools" is a general way to refer to the robust variety of +content that you can integrate into an online course. Software developers use +the XBlock component architecture to contribute new exercises and tools to the +Open edX platform and provide new and varied options for reaching learners. +Exercises enhance the core set of problem types by challenging learners to +complete graded and ungraded assessments. Tools deliver a variety of other +types of course content. + +* To use an exercise or tool in your course beyond the core set of problem + types, you must explicitly enable that exercise or tool. For more + information, see :ref:`Enable Additional Exercises and Tools`. + +* After you enable an exercise or tool for use in your course, you might need + to select **Advanced**, **Text**, or **Problem** on the unit page to + add content of that type to your course. + +The topics in this section introduce the core set of problem types and a +selection of other exercises and tools that you can add to your course. + +******************* +Core Problem Types +******************* + +The problem types that you can include in any course, without taking any +other steps to identify or enable additional exercises or tools, are the core +problem types. When you add a problem component in Studio, the core problem +types are classified as either **Simple Problem Types** or **Advanced**. + +.. contents:: + :local: + :depth: 1 + +===================== +Simple Problem Types +===================== + +When you create a problem in Studio, the editor opens with options for the +following problem types. When you select any of the simple problem types, the +:ref:`simple editor` opens. + +.. list-table:: + :widths: 25 60 20 + :header-rows: 1 + + * - Problem Type + - Description + - Support + * - :ref:`Single Select` + - In single select problems, learners select one answer from a set of + possible answers, which are visible directly below the question. + - Full support; mobile-ready + * - :ref:`Multi-select` + - In multi-select problems, learners select one or more options from a list of + possible answers. To answer the problem correctly, a learner must select + all of the options that are correct answers, and none of the options + that are incorrect. + - Full support; mobile-ready + * - :ref:`Dropdown` + - In dropdown problems, learners choose one answer from a set of possible + answers, which are presented in a dropdown list after the learner + selects the dropdown arrow. + - Full support; mobile-ready + * - :ref:`Numerical Input` + - In numerical input problems, learners enter numbers or specific and + relatively simple mathematical expressions to answer a question. These + problems allow only integers and a few select constants. You can specify + a margin of error, and you can specify a correct answer either + explicitly or by using a Python script. + - Full support; mobile-ready + * - :ref:`Text Input` + - In text input problems, learners enter text into a response field. The + response can include numbers, letters, and special characters such as + punctuation marks. + - Full support; mobile-ready + +By adding hints, feedback, or both, you can give learners guidance and help +when they work on a problem. When you choose one of the simple problem types, +the editor interface provides additional guidance and text fields for entering +these options. All of these problem types also have full support and are +mobile-ready. + +========= +Advanced +========= + +If none of the simple problem types fit what you need, the editor's problem type +select page has an option for **Advanced problem types**. Selecting this option +will bring you to a list of advanced problems. When you select any of the +advanced problem types, the :ref:`advanced editor` opens. + +* If you choose the **Blank Advanced Problem** option, the editor opens without + providing a template or example for you to follow. You can begin to add OLX + markup and the text for required and optional problem elements immediately. + +* If you choose one of the following problem types, a template appears in the + editor with guidance for adding all of that problem type's required elements, + as well as several optional elements. + +.. note:: Some advanced problem types are :ref:`unsupported` and are not available in the list of problem types unless you + enable a setting in Studio. For more information, see :ref:`Unsupported + Advanced Problem Types` and :ref:`Add_Unsupported_Exercises_Problems`. + + +.. list-table:: + :widths: 25 60 20 + :header-rows: 1 + + * - Type + - Description + - Support + + * - :ref:`Custom JavaScript Display and Grading` + - Custom JavaScript display and grading problems (also called custom + JavaScript problems or JS input problems) allow you to create a custom + problem or tool that uses JavaScript and then add the problem or tool + directly into Studio. + - Full support + * - :ref:`Custom Python-evaluated Input (Write Your Own Grader)` + - In custom Python-evaluated input (also called "write-your-own-grader") + problems, the grader uses a Python script that you create and embed in + the problem to evaluate a learner's response or provide hints. These + problems can be any type. + - Provisional support + * - :ref:`Math Expression Input` + - Learners enter mathematical expressions to answer a question. These + problems can include unknown variables and more complex symbolic + expressions. You can specify a correct answer either explicitly or by + using a Python script. + - Full support; mobile-ready + +.. _Unsupported Advanced Problem Types: + +++++++++++++++++++++++++++++++++++ +Unsupported Advanced Problem Types +++++++++++++++++++++++++++++++++++ + +The following advanced problem types are :ref:`not supported` by edX. You can enable an option to make unsupported problem types +available in Studio. For more information, see +:ref:`Add_Unsupported_Exercises_Problems`. + +.. list-table:: + :widths: 25 60 20 + :header-rows: 1 + + * - Type + - Description + - Support + * - :ref:`Circuit Schematic Builder` + - Learners arrange circuit elements such as voltage sources, capacitors, + resistors, and MOSFETs on an interactive grid. They then submit a DC, + AC, or transient analysis of their circuits to the system for grading. + - Not supported + * - :ref:`Image Mapped Input` + - Learners answer prompts by selecting a defined area in an image. You + define the area by including coordinates in the body of the problem. + - Not supported + * - :ref:`Problem with Adaptive Hint` + - A problem with an adaptive hint evaluates a learner's response, then + gives the learner feedback or a hint based on that response so that the + learner is more likely to answer correctly on the next attempt. These + problems can be text input or single select problems. + - Not supported + +****************************** +Additional Exercises and Tools +****************************** + +This table lists the fully or provisionally supported additional exercises and +tools that you can add to your course. + +.. note:: Some additional exercises and tools are :ref:`not supported` by edX. You can enable an option to make unsupported exercises + and tools available in Studio. For more information, see :ref:`Unsupported + Additional Exercises and Tools` and + :ref:`Add_Unsupported_Exercises_Problems`. + +.. to come: revise to eliminate entries with no support. Add pointer (at least for Open edX) to all of the XBlocks that are available. + +.. only:: Open_edX + + .. note:: In addition to the following exercises and tools, Open edX offers + the :ref:`Notes tool`. The Notes tool allows learners to + highlight and make notes about what they read in the course. This tool + is not available for courses on edx.org. + +.. list-table:: + :widths: 25 60 20 + :header-rows: 1 + + * - Type + - Description + - Support + + * - :ref:`Calculator` + - Learners can enter input that includes Greek letters, trigonometric + functions, and scientific or ``e`` notation in addition to common + operators. The calculator tool is available for every course through the + course advanced settings. When the calculator tool is enabled, it + appears on every unit page. + - Provisional support + * - :ref:`Conditional Module` + - You can create a conditional module to control versions of content that + groups of learners see. For example, learners who answer "Yes" to a poll + question then see a different block of text from the learners who answer + "No" to that question. + - Provisional support + * - :ref:`drag_and_drop_problem` + - Learners respond to a question by dragging text or objects to a specific + location on an image. + - Full support; mobile-ready + * - :ref:`Drag and Drop` + - Learners respond to a question by dragging text or objects to a specific + location on an image. This version of the drag and drop problem type is + deprecated and should not be added to a course. For more information + about the fully supported drag and drop problem type, see + :ref:`drag_and_drop_problem`. + - Not supported + * - :ref:`External Grader` + - An external grader is a service that receives learner responses to a + problem, processes those responses, and returns feedback and a problem + grade to the edX platform. You build and deploy an external grader + separately from the edX platform. An external grader is particularly + useful for software programming courses where learners are asked to + submit complex code. + - Provisional support + * - :ref:`Google Calendar Tool` + - Learners see a Google calendar embedded in your course. You can use a + Google calendar to share quiz dates, office hours, or other schedules of + interest to learners. + - Provisional support + * - :ref:`Google Drive Files Tool` + - Learners see a Google Drive file, such as a document, spreadsheet, or + image, embedded in your course. + - Provisional support + * - :ref:`IFrame` + - With the iframe tool, you can integrate ungraded exercises and tools + from any Internet site into a Text component in your course. + - Provisional support + * - :ref:`LTI Component` + - LTI components allow you to add an external learning application or non- + PDF textbook to Studio. + - Full support + * - :ref:`Open Response Assessment` + - Learners receive feedback on responses that they submit and give + feedback to other course participants. Open response assessments include + self assessment, peer assessment, and optionally, staff assessment. + - Full support + * - :ref:`Oppia Exploration Tool` + - You can embed Oppia explorations in your course so that learners can + interact with them directly in the course body. + - Provisional support + * - :ref:`UBC Peer Instruction` + - This type of exercise offers the experience of the Peer Instruction + learning system within your online course. + - Full support + * - :ref:`Poll Tool` + - You can include polls in your course to gather learners' opinions on + various questions. You can use the Poll Tool in Studio. + - Full support + * - :ref:`Qualtrics Survey` + - You can import surveys that you have created in Qualtrics. The survey + appears inside an iframe in your course. + - Provisional support + * - :ref:`Survey Tool` + - You can include surveys in your course to collect learner responses to + multiple questions. + - Full support + * - :ref:`Word Cloud` + - Word clouds arrange text that learners enter in response to a question + into a colorful graphic. + - Provisional support + + + +.. _Unsupported Additional Exercises and Tools: + +=========================================== +Unsupported Additional Exercises and Tools +=========================================== + +The following additional exercises and tools are :ref:`not supported` by edX. You can enable an option to make unsupported exercises and +tools available in Studio. For more information, see +:ref:`Add_Unsupported_Exercises_Problems`. + + +.. list-table:: + :widths: 25 60 20 + :header-rows: 1 + + * - Type + - Description + - Support + * - :ref:`Annotation` + - Learners respond to questions about a specific block of text. The + question appears above the text so that learners can think about the + question as they read. + - Not supported + * - :ref:`Chemical Equation` + - Learners enter a value that represents a chemical equation into a text + box. The grader uses Python script that you create and embed in the + problem to evaluate learner responses. + - Not supported + * - :ref:`completion` + - Learners mark sections of course content as completed. This tool helps + learners track their progress through sections of the course (including + ungraded activities such as reading text, watching videos, or + participating in course discussions), and gives them a way to indicate + to both themselves and course staff that they completed an activity. + - Not supported + * - :ref:`Full Screen Image` + - Learners can enlarge an image in the entire browser window. This tool is + useful for detailed images that are easier to view when enlarged. + - Not supported + * - :ref:`Gene Explorer` + - The gene explorer (GeneX) simulates the transcription, splicing, + processing, and translation of a small hypothetical eukaryotic gene. + Learners make specific mutations in a gene sequence, and this tool + calculates and displays the effects of the mutations on the mRNA and + protein. + - Not supported + * - :ref:`Periodic Table` + - An interactive periodic table of the elements that shows detailed + information about each element when learners move the pointer over each + element. + - Not supported + * - :ref:`Poll` + - You can run polls in your course so that your learners can share + opinions on different questions. You can only add this type of poll to a + course by using OLX (open learning XML). Support for this tool in Studio + is not available. For more information, see the `EdX Open Learning XML Guide`_.. + - Not supported + * - :ref:`Problem Written in LaTeX` + - If you have a problem that is already written in LaTeX, you can use this + problem type to convert your code into XML. + - Not supported + * - :ref:`Protein Builder` + - Learners create specified protein shapes by stringing together amino + acids. + - Not supported + * - :ref:`RecommenderXBlock` + - RecommenderXBlock can hold a list of resources for misconception + remediation, additional reading, and so on. This tool allows the course + team and learners to work together to maintain the list of resources. + For example, team members and learners can suggest new resources, vote + for useful ones, or flag abuse and spam. + - Not supported + * - :ref:`Single Select and Numerical Input` + - Learners not only choose one answer from a set of possible options, they + are also prompted to provide more specific information, if necessary. + - Not supported + * - :ref:`Zooming Image` + - Learners can view sections of an image in detail. You specify the + sections in an image that can be enlarged. + - Not supported + +****************************************** +Analyzing Learner Performance on Problems +****************************************** + +For the following problem types in your course, you can use edX Insights to +review aggregated learner performance data and examine the submitted answers. +For more information, see `Using edX Insights`_ . + +* :ref:`Dropdown` +* :ref:`Math Expression Input` +* :ref:`Multi-select` +* :ref:`Numerical Input` +* :ref:`Single Select` +* :ref:`Text Input` + +.. _Mobile-Ready Problem Types: + +********************************* +Mobile-Ready Problem Types +********************************* + +Learners can read and submit answers for the following types of problems while +they use the edX mobile app. + +* :ref:`drag_and_drop_problem` +* :ref:`Dropdown` +* :ref:`Math Expression Input` +* :ref:`Multi-select` +* :ref:`Numerical Input` +* :ref:`Single Select` +* :ref:`Text Input` + +Questions that have other problem types do not appear in the edX mobile app. +Instead, a message appears with a link to open the applicable problem component +in a web browser. + + +.. _Add_Unsupported_Exercises_Problems: + +*********************************************** +Adding Unsupported Problem Types and Exercises +*********************************************** + +.. only:: Open_edX + + .. note:: These instructions are applicable only to edx.org. + +.. When DOC-3163 is complete, update this Open edX only note to say "These instructions are applicable only to edx.org or if your Open edX site has configured {the name of the config setting}" + +In general, you should use only problem types and exercises that are either +fully or provisionally supported by edX. By default, only supported problem +types and exercises are available in Studio for adding to courses. + +However, in some situations, you might choose to use exercises and problem types +that edX does not support. + +To add unsupported problem types, exercises, and tools to your course, follow +these steps. + +#. In Studio, select **Settings**, then **Advanced Settings**. + +#. Locate the **Add Unsupported Problems and Tools** field, and enter a value + of ``true``. + +#. Select **Save Changes**. + +After you enable this setting, unsupported problem types, exercises, and tools +are available in the lists of new components that you can add to your course +in Studio. + +.. include:: ../links/links.rst diff --git a/source/educators/migration_wip/10_exercises_tools/custom_javascript.rst b/source/educators/migration_wip/10_exercises_tools/custom_javascript.rst new file mode 100644 index 000000000..6601b898a --- /dev/null +++ b/source/educators/migration_wip/10_exercises_tools/custom_javascript.rst @@ -0,0 +1,320 @@ +.. _Custom JavaScript: + +############################################## +Custom JavaScript Display and Grading Problem +############################################## + +.. note:: EdX offers full support for this problem type. + +Custom JavaScript display and grading problems (also called custom JavaScript +problems or JS input problems) allow you to create a custom problem or tool +that uses JavaScript and then add the problem or tool directly into Studio. +When you create a JS input problem, Studio embeds the problem in an inline +frame (an HTML iframe element) so that your learners can interact with it in +the LMS. You can grade your learners’ work using JavaScript and some basic +Python, and the grading is integrated into the edX grading system. + +The JS input problem that you create must use HTML, JavaScript, and cascading +style sheets (CSS). You can use any application creation tool, such as the +Google Web Toolkit (GWT), to create your JS input problem. + +.. image:: ../images/JavaScriptInputExample.png + :alt: An example JavaScript Input problem that contains a dropdown selector + inside an inline frame. + +.. caution:: + + * You cannot use a custom JavaScript problem in a component that contains + more than one problem. Each custom JavaScript problem must be in its own + component. See :ref:`Multiple Problems in One Component` for more + information. + + * The **Show Answer** button does not work for JS input problems. By + default, the **Show Answer** option is set to **Never**. If you change + this option in the problem component, a **Show Answer** button appears in + the learner's view of the problem in the LMS, but the button does not work. + + +************************************************************ +Create a Custom JavaScript Display and Grading Problem +************************************************************ + +#. Create your JavaScript application, and then upload all files associated + with that application to the **Files & Uploads** page. +#. In the unit where you want to create the problem, under **Add New + Component** select **Problem**. +#. In the problem editor, select **Advanced problem types**. Then select + **Custom JavaScript Display and Grading**. +#. In the advanced problem editor, modify the example code according to your problem. + Be sure to specify a ``title`` attribute on the ``jsinput`` tag. This title + is used for the title attribute on the generated inline frame. +#. (Optional) To add a **Save** button to your problem, in the settings panels on + the right side of the editor, set **Attempts** to a number larger than zero. +#. Select **Save**. + + +.. note:: All problems include more than one resource. If all the resources in + a problem have the same protocol, host, and port, then the problem conforms + to the same-origin policy (SOP). For example, the resources + ``http://store.company.com:81/subdirectory_1/JSInputElement.html`` and + ``http://store.company.com:81/subdirectory_2/JSInputElement.js`` have the + same protocol (``http``), host (``store.company.com``), and port (``81``). + + If any resources in your problem use a different protocol, host, or port, + you need to bypass the SOP. For example, + ``https://info.company.com/JSInputElement2.html`` uses a different + protocol, host, and port from + ``http://store.company.com:81/subdirectory_1/JSInputElement.html``. + + To bypass the SOP, change ``sop="true"`` to ``sop="false"``. In the example + problem code, this attribute is just before the closing ``customresponse`` + tag. + + If you bypass the same-origin policy, you require an additional file. + The example problem uses the file ``jschannel.js`` to bypass the SOP. + + For more information, see the same-origin policy page on the `Mozilla + Developer Network site `_ + or on `Wikipedia `_. + + +======================================== +JavaScript Input Example Problem Code +======================================== + +The following code recreates the JavaScript Input problem example shown in the +overview. The example problem uses these files. + +* https://files.edx.org/custom-js-example/jsinput_example.html +* https://files.edx.org/custom-js-example/jsinput_example.js +* https://files.edx.org/custom-js-example/jsinput_example.css +* https://files.edx.org/custom-js-example/jschannel.js (This file is used only + because this example bypasses the SOP, as indicated by the line + ``sop="false"``) + + +.. code-block:: xml + + + + +

This is paragraph text displayed before the iframe.

+ + + + + +.. note:: Keep the following points in mind about this example problem. + + - The jsinput_example.js file defines three JavaScript functions + (**JSInputDemo.getGrade**, **JSInputDemo.getState**, and + **JSInputDemo.setState**). + + - The JavaScript input problem code uses **JSInputDemo.getGrade**, + **JSInputDemo.getState**, and **JSInputDemo.setState** to grade, save, or + restore a problem. These functions must be global in scope. + + - **JSInputDemo.getState** and **JSInputDemo.setState** are optional. You + need to define these functions only if you want to conserve the state of + the problem. + + - **Width** and **height** represent the dimensions of the inline frame that + holds the application. + + - The response is graded as correct if the ``correct`` option is selected in + the dropdown control when the user selects **Submit**. + + - Selecting **Submit** registers the problem's current state. + + +.. _JS Input Problem XML: + +****************************** +JavaScript Input Problem XML +****************************** + +JSInput allows problem authors to turn stand-alone HTML files into problems +that can be integrated into the edX platform. Since its aim is flexibility, it +can be seen as the input and client-side equivalent of **CustomResponse**. + +A JSInput exercise creates an inline frame (iframe) in a static HTML page, and +passes the return value of author-specified functions to the enclosing +response type (generally **CustomResponse**). JSInput can also store and +retrieve state. + +======== +Template +======== + +The following is the basic format of a JSInput problem. + +.. code-block:: xml + + + + + + + + +The accepted attributes are: + +============== ============== ========= ========== +Attribute Name Value Type Required Default +============== ============== ========= ========== +html_file URL string Yes None +title string Yes ``Problem Remote Content`` +gradefn Function name Yes ``gradefn`` +set_statefn Function name No None +get_statefn Function name No None +height Integer No ``300`` +width Integer No ``400`` +title String No None +============== ============== ========= ========== + +======================== +Required Attributes +======================== + +* **html_file** + + The **html_file** attribute specifies the HTML file that the iframe will + point to. The HTML file must be located in the content directory. + + The iframe is created using the sandbox attribute. Although pop-ups, + scripts, and pointer locks are allowed, the iframe cannot access its + parent's attributes. + + The HTML file must contain a **gradefn** function that the JSInput file can + access. To determine whether the **gradefn** function is accessible, in the + console, make sure that **gradefn** returns the right thing. When JSInput + uses the **gradefn** function, `gradefn` is called with + `gradefn`.call(`obj`), where **obj** is the object-part of **gradefn**. For + example, if **gradefn** is **myprog.myfn**, JSInput calls + **myprog.myfun.call(myprog)**. + + The HTML file has no specific requirements other than the **gradefn** + function. Note that inheriting CSS or JavaScript from the parent (except for + the Chrome-only **seamless** attribute, which is set to ``True`` by default) + is not currently supported. + +* **title** + + The **title** attribute specifies the title for the generated iframe. + Generally, the title attribute on the iframe should match the title tag of + the HTML file that is hosted within the iframe. + +* **gradefn** + + The **gradefn** attribute specifies the name of the function that will be + called when a user selects **Submit**, and that returns the learner's answer. + Unless both the **get_statefn** and **set_statefn** attributes are also + used, this answer is passed as a string to the enclosing response type. In + the **customresponse** example above, this means **cfn** will be passed this + answer as ``ans``. + + If the **gradefn** function throws an exception when a learner attempts to + submit a problem, the submission is aborted, and the learner receives a + generic alert. The alert can be customized by making the exception name + ``Waitfor Exception``; in that case, the alert message will be the exception + message. + + .. important:: To make sure the learner's latest answer is passed correctly, + make sure that the **gradefn** function is not asynchronous. Additionally, + make sure that the function returns promptly. Currently the learner has no + indication that her answer is being calculated or produced. + +======================== +Optional Attributes +======================== + +* **set_statefn** + + Sometimes a problem author will want information about a learner's previous + answers ("state") to be saved and reloaded. If the attribute **set_statefn** + is used, the function given as its value will be passed the state as a + string argument whenever there is a state, and the learner returns to a + problem. The function has the responsibility to then use this state + appropriately. + + The state that is passed is: + + * The previous output of **gradefn** (i.e., the previous answer) if + **get_statefn** is not defined. + * The previous output of **get_statefn** (see below) otherwise. + + It is the responsibility of the iframe to do proper verification of the + argument that it receives via **set_statefn**. + +* **get_statefn** + + Sometimes the state and the answer are quite different. For instance, a + problem that involves using a JavaScript program that allows the learner to + alter a molecule may grade based on the molecule's hydrophobicity, but from + the hydrophobicity it might be incapable of restoring the state. In that + case, a *separate* state may be stored and loaded by **set_statefn**. Note + that if **get_statefn** is defined, the answer (i.e., what is passed to the + enclosing response type) will be a json string with the following format: + + .. code-block:: xml + + { + answer: `[answer string]` + state: `[state string]` + } + + + The enclosing response type must then parse this as json. + +* **height** and **width** + + The **height** and **width** attributes are straightforward: they specify + the height and width of the iframe. Both are limited by the enclosing DOM + elements, so for instance there is an implicit max-width of around 900. + + In the future, JSInput may attempt to make these dimensions match the HTML + file's dimensions (up to the aforementioned limits), but currently it + defaults to ``300`` and ``400`` for **height** and **width**, respectively. + + diff --git a/source/educators/migration_wip/10_exercises_tools/custom_python.rst b/source/educators/migration_wip/10_exercises_tools/custom_python.rst new file mode 100644 index 000000000..4abc422ae --- /dev/null +++ b/source/educators/migration_wip/10_exercises_tools/custom_python.rst @@ -0,0 +1,503 @@ +.. _Write Your Own Grader: + +############################################################## +Custom Python-evaluated Input Problem (Write-Your-Own-Grader) +############################################################## + +.. note:: EdX offers provisional support for this problem type. + +This section provides information about writing your own grader directly in a +problem component. + +.. contents:: + :local: + :depth: 1 + +********** +Overview +********** + +In custom Python-evaluated input (also called "write-your-own-grader" +problems), the grader uses a Python script that you create and embed in the +problem to evaluate a learner's response or provide hints. These problems can +be any type. :ref:`Numerical input` and :ref:`text input` problems are the most common write-your-own-grader problems. + +Custom Python-evaluated input problems can include the following advanced +problem types. + +* :ref:`Chemical Equation` +* :ref:`Custom JavaScript` +* :ref:`Gene Explorer` +* :ref:`Protein Builder` + +******************************************************** +Create a Custom Python-Evaluated Input Problem in Studio +******************************************************** + +#. In the unit where you want to create the problem, select **Problem** under + **Add New Component**. + +#. In the problem editor, select **Advanced problem types**. Then select **Custom Python-Evaluated Input**. + +#. In the component editor, edit the problem in :ref:`Script Tag Format`. + +#. Select **Save**. + + +.. _Script Tag Format: + +************************** +Script Tag Format +************************** + +The script tag format encloses a Python script that contains a "check function" +in a `` + +

Enter two integers that sum to 10.

+ +
+ + + +

Enter two integers that sum to 20:

+ +
+ + + + +
+

Explanation

+

Any set of integers on the line \(y = 10 - x\) and \(y = 20 - x\) + satisfies these constraints.

+

You can also add images within the solution clause, like so:

+ +
+ + + + + +======================================================== +Example of the ``check`` Function Returning a Dictionary +======================================================== + + The following example shows a ``check`` function that returns a dictionary. + +.. code-block:: python + + def check(expect, answer_given): + check1 = (int(answer_given[0]) == 1) + check2 = (int(answer_given[1]) == 2) + check3 = (int(answer_given[2]) == 3) + return {'overall_message': 'Overall message', + 'input_list': [ + { 'ok': check1, 'msg': 'Feedback 1'}, + { 'ok': check2, 'msg': 'Feedback 2'}, + { 'ok': check3, 'msg': 'Feedback 3'} ] } + +The function checks that the user entered ``1`` for the first input, ``2`` for +the second input, and ``3`` for the third input. It provides feedback messages +for each individual input, as well as a message displayed below the entire +problem. + +====================== +Script Tag Attributes +====================== + +The following table explains the important attributes and values in the +preceding example. + +.. list-table:: + :widths: 20 80 + + * - `` + +

Part 1: Enter two integers that sum to 10.

+ +
+ + + +

Part 2: Enter two integers that sum to 20.

+ +
+ + + + +
+

Explanation

+

For part 1, any two numbers of the form n and 10-n, + where n is any integer, will work. One possible answer would + be the pair 0 and 10.

+

For part 2, any two numbers of the form n and 20-n, where n is any integer, will work. One possible answer would be the pair 1 and 19

+
+ + + +**Templates** + +The following template includes answers that appear when the learner selects +**Show Answer**. + +.. code-block:: xml + + + + + +

Problem text

+ +
+ + + + +
+

Solution or Explanation Heading

+

Solution or explanation text

+
+ + + +The following template does not return answers when the learner selects **Show +Answer**. If your problem does not include answers for the learner to see, make +sure to set **Show Answer** to **Never** in the problem component. + +.. code-block:: xml + + + + + +

Enter two real numbers that sum to 20:

+ +
+ + + + +
+

Solution or Explanation Heading

+

Solution or explanation text

+
+ + + +.. _Award Partial Credit: + +==================== +Award Partial Credit +==================== + +You can configure a custom Python-evaluated input problem so that learners +who give a partially correct answer receive partial credit for the problem. +You can award 50% of the points for the problem, or you can award a different +percentage of points. For more information, see the following sections. + +* :ref:`Award Half Credit` +* :ref:`Award a Percentage of Credit` + +.. only:: Partners + + .. note:: + Support for partial credit problems in courses on edx.org and edX + Edge is provisional. Ensure that you test such problems thoroughly before + releasing them to learners. For more information, contact your edX partner + manager. + +.. _Award Half Credit: + +Award Half Credit +********************* + +You can configure a problem to award 50% of the possible points. To provide a +learner with a more granular score, see `Award a Percentage of Credit`_. + +The ``check`` function must return the value ``"Partial"`` in one of the +following ways. + +* Return the value ``"Partial"`` directly. + +* Return the value ``"Partial"`` in the dictionary that is returned, in the + following form. + + ``{ 'ok': 'Partial', 'msg': 'Message' }`` + +* Return the value ``"Partial"`` as part of the input list for multi-part + problems. + + .. code-block:: xml + + { 'overall_message': 'Overall message', + 'input_list': [ + { 'ok': True, 'msg': 'Feedback for input 1'}, + { 'ok': False, 'msg': 'Feedback for input 2'}, + { 'ok': 'Partial', 'msg': 'Feedback for input 3'} + ... ] } + +With all of these options, ``True`` awards learners with 100% of the available +points for the problem, ``'Partial'`` with 50%, and ``False`` with 0%. + +For more information about ``check`` function return values, see `The check +Function`_. + +.. _Award a Percentage of Credit: + +Award a Percentage of Credit +****************************** + +You can configure a problem to return a percent value as a grade. This method +provides greater flexibility in assigning the learner a score than +:ref:`awarding half credit`. + +In the following example, the learner's score equals the answer divided by 100. + +.. image:: ../images/partial-credit-python-problem.png + :alt: An image of a write-your-own-grader problem that provides partial + credit. + +The following code shows the configuration of this problem. + +.. code-block:: xml + + +

In the following problem, the learner receives a score that equals the + answer / 100. If the learner's answer is greater than 100 or less than 0, + the score equals 0.

+ + + +

Enter a number beween 0 and 100.

+ +
+ + + +This example illustrates the following points. + +* The ``points`` attribute of the ```` element specifies that + the question is worth 100 points. + +* The ``give_partial_credit`` function checks that the answer is between 0 and + 100, and if so divides the learner's answer by 100 to determine the grade. + +* The ``input_list`` that is returned specifies that: + + * The answer is acceptable and can receive partial or full credit, with the + item ``'ok': True``. + + * The learner receives the message ``Your grade is`` followed by the percent + grade, with the item ``'msg': 'Your grade is ' + str(ans) + '%'``. + + * The grade assigned is the learner's answer divided by 100, with the item + ``'grade_decimal':grade``. + +You can enhance and apply this example for your own partial credit problems. + +.. _Create a Randomized Custom Python-Evaluated Input Problem: + +=========================================================== +Create a Randomized Custom Python-Evaluated Input Problem +=========================================================== + +You can create a custom Python-evaluated input problem that randomizes +variables in the Python code. + +.. note:: + In the problem settings, you must set the **Randomization** value to + something other than **Never** to have Python variables randomized. See + :ref:`Randomization` for more information. + +The following example demonstrates using randomization with a Python-evaluated +input problem. + +.. note:: + This example uses the method ``random.randint`` to generate random numbers. + You can use any standard Python library for this purpose. + +.. code-block:: xml + + +

Some problems in the course will utilize randomized parameters. + For such problems, after you check your answer you will have the option + of resetting the question, which reconstructs the problem with a new + set of parameters.

+ +

Let (x_1 = $x1) and (x_2 = $x2). What is the value of (x_1+x_2)?

+ + + + + +

Explanation:

+ + diff --git a/source/educators/migration_wip/10_exercises_tools/drag_and_drop.rst b/source/educators/migration_wip/10_exercises_tools/drag_and_drop.rst new file mode 100644 index 000000000..d5dec84a5 --- /dev/null +++ b/source/educators/migration_wip/10_exercises_tools/drag_and_drop.rst @@ -0,0 +1,498 @@ +.. _drag_and_drop_problem: + +########################## +Drag and Drop Problem +########################## + +.. note:: EdX offers full support for this problem type. + +In drag and drop problems, learners respond to a question by dragging text or +images to a specific location on a background image. This section explains how +to use drag and drop problems in your course. + +.. contents:: + :local: + :depth: 1 + +.. note:: + This drag and drop problem type is intended as a replacement for an older + drag and drop problem type. This drag and drop problem type includes + significant improvements and you should use it for any new course + development. For more information about the previous, deprecated drag and + drop problem type, see :ref:`Drag and Drop`. + +.. _overview_of_drag_and_drop_problems: + +********************************** +Overview of Drag and Drop Problems +********************************** + +A drag and drop problem includes a background image and one or more items that +learners can drag into target zones on the background image. You can include as +many draggable items and as many target zones as you need. You can include +decoy items that do not have a target, and you can include decoy targets that +do not correspond to draggable items. + +When learners view a drag and drop problem in the LMS, the problem includes a +top section and a bottom section. Learners drag items from the top section on +to the background image in the section below it. + +The way that a learner selects, or grabs, an item depends on the type of +browser that the learner uses. For example, a learner might click and hold on +a draggable item with a mouse pointer to select it, drag the item to a target, +and release the mouse pointer to drop the item on the target. A learner who +accesses the problem on a mobile device with a touch screen might swipe an item +from the top section into a target zone. A learner who uses a keyboard +interface might use the navigation keys to select an item and then match it to +a target zone. + +You can configure a drag and drop problem to give learners unlimited attempts +to match items to target zones or you can configure it to behave restrictively, +like a test. + +* In standard mode, the problem gives learners unlimited attempts to match + items and it provides immediate feedback to indicate whether an item is + matched correctly. + +* In assessment mode, learners must match all of the draggable items to target + zones and then submit the problem. The problem does not reveal + whether items are matched correctly until the learner submits the problem. + +For more information about assessment mode and standard mode, see +:ref:`choosing_a_dnd_mode`. + +The following image shows an example drag and drop problem. + +.. image:: ../images/dnd-initial.png + :width: 600 + :alt: An example of a simple drag and drop problem. The components of the + problem, such as its title, text, and introductory feedback are labeled. + +The following image shows the success feedback message that learners see when +they match a draggable item with its target zone. Each draggable item has its +own success feedback message. + +.. image:: ../images/dnd-correct-feedback.png + :width: 400 + :alt: An example of a simple drag and drop problem. The success feedback + message appears above the background image. + +The following image shows the error feedback message that learners see when +they match a draggable item with an incorrect target zone. Each draggable item +has its own error feedback message. + +.. image:: ../images/dnd-incorrect-feedback.png + :width: 400 + :alt: An example of a simple drag and drop problem. The error feedback + message appears over the background image. + +The following image shows a completed drag and drop problem. The final feedback +message informs the learner that the problem is complete. + +.. image:: ../images/dnd-complete.png + :width: 400 + :alt: An example of a simple drag and drop problem. The problem is complete + and the final feedback message appears below the background image. + +.. _drag_and_drop_background_images: + +=============================== +Understanding Background Images +=============================== + +The background image for a drag and drop problem is the surface that learners +drag items onto. + +A target zone is a rectangular area on the background image. You can show or +hide the borders of a zone for learners. You can add titles for zones or leave +the **Title** field empty. However, you must fill in the **Description** field +for each zone. The description is only exposed to screen readers. The +description must describe the content of the zone for visually impaired +learners. For example, a zone that includes an apple might have a description +that says "A round, red fruit with a stem." + +A background image must fit within the course screen. The LMS automatically +scales images that are too wide. If you choose a background image that is +extremely large, you should consider how it appears to learners after scaling. +The width of the course screen depends on the device and browsing software that +a learner uses. + +You define a target zone by specifying its width, height, horizontal offset +(``x``), and vertical offset (``y``). Each specification is in pixels. The +horizontal offset is the distance between the left side of the background image +and the left side of the target zone. The vertical offset is the distance +between the top of the background image and the top of the target zone. + +The following image shows a background image and target zones in the drag and +drop problem editing dialog box. For more information about editing drag and +drop problems, see :ref:`creating_a_drag_and_drop_problem`. + +.. image:: ../images/dnd-zone-borders.png + :width: 600 + :alt: A background image and target zones shown in the drag and drop problem + editing dialog box. + +.. note:: + The pixel coordinates that you use to specify the size and location of target + zones are also used by common image editing software. You can open a + background image in an image editing program to find the pixel coordinates of + a target zone. + +.. _drag_and_drop_draggable_items: + +============================== +Understanding Draggable Items +============================== + +A draggable item is a rectangle that contains either a label or an image. +Learners grab draggable items from the top of a drag and drop problem and drag +them to targets on the background image. + +You can set the size of the rectangle for a draggable item as a percentage of +the width of the problem. If you do not specify the size, the LMS sets it based +on the length of the text in the label or the size of the image in it. You can +set the background color and the label text color for the items in a problem. + +Each draggable item can match one target zone on the background image, multiple +target zones, or no target zones. + +Each item must have a text label to identify it in the drag and drop problem. +If you include only a text label, that label appears in the draggable item. If +you include both a text label and an image for an item, the image appears as +its label. + +================================= +Using Draggable Items with Images +================================= + +The following image shows draggable items with images. For examples of items +with text, see :ref:`overview_of_drag_and_drop_problems`. + +.. image:: ../images/dnd-draggable-item-images.png + :width: 400 + :alt: Draggable items with image labels in the item area of a drag and drop + problem. + +Images for draggable items have alternative image descriptions. The alternative +description explains the image content in text. If a learner cannot access the +visual image content, the text description helps that learner to complete the +problem. + +Images for draggable items must fit within the top section of the problem. The +LMS automatically scales large images to fit. If you use a large image in a +draggable item, you should consider how that image appears after scaling. + +.. note:: + If an image file is unavailable, or cannot be displayed, the LMS displays + the text description as the button label. + +.. _choosing_a_dnd_mode: + +========================================= +Choosing a Drag and Drop Problem Mode +========================================= + +You can configure drag and drop problems to allow learners to experiment with +matching draggable items to target zones until all items are matched correctly, +or to require that learners match all items to target zones without any input +and then submit their attempts for grading. You can choose either **Standard +Mode** or **Assessment Mode** to control the behavior of the problem. + +* In standard mode, learners have unlimited attempts to match + items and the problem provides immediate feedback to indicate whether + an item is matched correctly. + +* In assessment mode, learners must match all of the draggable items to target + zones and then choose to submit the problem. The problem does not reveal + whether items are matched correctly until the learner submits the problem. + You can limit the number of attempts a learner is allowed, or allow unlimited + attempts. + +.. _using_standard_mode: + +Using Standard Mode +******************************************** + +Standard mode configures a drag and drop problem to give learners unlimited +attempts to match draggable items with target zones until all of the items are +matched to the correct targets. Each time a learner drops an item on a target +zone, the problem reports whether the match is correct. If the match is not +correct, the draggable item is returned to the item bank for a new attempt. + +A learner completes a drag and drop problem in standard mode when all of the +items are matched to target zones correctly. Learners receive the maximum score +for the problem when the problem is complete. + +.. _using_assessment_mode: + +Using Assessment Mode +******************************************** + +Assessment mode configures a drag and drop problem to behave like a test. In +assessment mode, learners must match all of the draggable items to target zones +before the problem reveals whether the items are matched correctly. + +Learners select **Submit** when they believe that they have completed the +problem. If all items are matched correctly, the problem is complete. If any +items are not matched correctly, and the maximum number of attempts has not +been reached, the learner can correct items and select **Submit** again. When +the learner reaches the maximum number of attempts, the problem is complete. + +The score for the problem is calculated by dividing the maximum score based on +the percent of draggable items that are matched correctly. If a learner +attempts the problem multiple times, the score for the best attempt is the +final score for the problem. + +In assessment mode, you can specify the number of times that learners can +submit a drag and drop problem. If you allow more than one attempt, the problem +reveals which items are correctly matched and gives learners an opportunity to +move items that are not correct. If you do not specify a limit, learners have +unlimited attempts. + +.. _creating_a_drag_and_drop_problem: + +********************************* +Creating a Drag and Drop Problem +********************************* + +To create a drag and drop problem, follow these steps. + +#. In the unit where you want to create the problem, under **Add New + Component** select **Drag and Drop**. + + Studio adds the drag and drop problem to the unit. + +#. Select **Edit**. The **Editing** dialog box opens. + + Configure your drag and drop problem. For detailed information about + individual controls in the **Editing** dialog box, see + :ref:`drag_and_drop_editor_fields`. + + The **Editing** dialog box includes multiple screens. + Configure each screen and select **Continue**. On the final screen, select + **Save** to exit the configuration dialog box and save your changes. + + In particular, configure the aspects of the drag and drop problem described + below. + + * Edit the problem title, problem text, introductory feedback, and final + feedback for the problem. For more information about how the text in these + fields appears in a drag and drop problem, see + :ref:`overview_of_drag_and_drop_problems`. + + * Specify a background image in the **Background URL** field. Enter the URL + of a file you have added to your course or the URL of an image on the web. + For more information about working with course files, see :ref:`Add Files + to a Course`. For more information about background images, see + :ref:`drag_and_drop_background_images`. + + Select **Change background** after you enter the URL for your background + image. + + If you specify the URL of an image on the web, make sure that you are + legally authorized to use the image and that the image is available to + learners around the world. + + * Remove the target zones for the example drag and drop problem. Select + **Add a zone** to add each target zone for your problem. For more + information about target zones, see + :ref:`drag_and_drop_background_images`. + + * Remove the draggable items for the example drag and drop problem. Select + **Add an item** to add draggable items for your problem. Select a matching + target zone for each item in the **Zone** field. Add a label, success + feedback text, and error feedback text. For more information about how the + text in these fields appears, see + :ref:`overview_of_drag_and_drop_problems`. For more information about + draggable items, see :ref:`drag_and_drop_draggable_items`. + +.. _drag_and_drop_editor_fields: + +******************************************************* +Understanding the Drag and Drop Editing Controls +******************************************************* + +The following table explains the controls in the **Editing** dialog box. + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Control + - Explanation + + * - **Problem title** + - The heading that appears above the drag and drop problem. For an + example, see :ref:`overview_of_drag_and_drop_problems`. + + * - **Show title** + - Controls whether the problem title appears above the problem in the LMS. + + * - **Problem mode** + - Controls whether the problem allows learners to experiment with matching + draggable items to target zones (standard mode) or requires learners to + match all items before providing feedback and optionally restricts the + number of attempts (assessment mode). For more information, see + :ref:`choosing_a_dnd_mode`. + + * - **Maximum attempts (assessment mode only)** + - Controls the number of times that learners can match items to target + zones and submit the problem for grading. If you do not enter a maximum + number, learners have unlimited attempts. For more information, see + :ref:`choosing_a_dnd_mode`. + + * - **Maximum score** + - The total number of points that learners receive for completing the + problem. For more information about scores and + grading, see :ref:`Grading Index`. + + * - **Problem text** + - Text that appears above the problem in the LMS. You can use this text to + provide instructions or explain the problem. For an example, see + :ref:`overview_of_drag_and_drop_problems`. + + * - **Show "Problem" heading** + - Controls whether the word **Problem** appears above the problem text. + + * - **Introductory Feedback** + - The text that appears in the feedback section of the problem before a + learner begins. + + * - **Final Feedback** + - The text that appears in the feedback section of the problem after a + learner matches all items to their target zones. + + * - **Background URL** + - The URL of the image that contains target zones for the problem. The URL + can be relative to a file you add to your course or to a file on the + web. For more information, see :ref:`drag_and_drop_background_images`. + + You must select **Change background** when you enter a new URL in this + field. If you do not select **Change background**, the new value will + not be saved when you save other changes in the **Editing** dialog box. + + * - **Background description** + - A description of the background image. This description is used by + learners who cannot access the visual image. + + * - **Display label names on the image** + - Controls whether the text for target zones appears on the background + image in the LMS. + + * - **Display zone borders on the image** + - Controls whether the outlines of target zones appear on the background + image in the LMS. + + * - **Zone Text** + - A name for a target zone. You select the name of a target zone in the + configuration for draggable items. + + * - **Zone Description** + - Text that describes a target zone. This description is available to + learners who cannot access the target zone visually. + + * - **Zone width** + - The horizontal size of a target zone in pixels. + + * - **Zone height** + - The vertical size of a target zone in pixels. + + * - **Zone X** + - The horizontal distance (in pixels) between the left edge of the + background image and the left edge of a target zone. + + * - **Zone Y** + - The vertical distance (in pixels) between the top edge of the background + image and the top edge of a target zone. + + * - **Zone Alignment** + - Controls the way that the problem aligns draggable items after learners + drop them on a target zone. Available options are "left", "center", and + "right". + + * - **Add a zone** + - Adds a set of controls for a new zone to the **Editing** dialog box. + + * - **Background color** + - The color that appears behind the text or image label of a draggable + item. You can specify the color using a hexadecimal color code + (including the ``#`` character) or any other valid CSS color + specification. For more information, see the `W3C CSS color + specification`_. This is an optional configuration. If you do not set + the background color, the LMS will apply the default color to your + draggable items. + + * - **Text color** + - The color of the text label for a draggable item. You can specify the + color using a hexadecimal color code (including the ``#`` character) or + any other valid CSS color specification. For more information, see the + `W3C CSS color specification`_. This is an optional configuration. If + you do not set the background color, the LMS will apply the default + color to your text. + + * - **Item Text** + - Controls the text that appears on the draggable item in the problem. + + * - **Item Zones** + - Controls the target zones that match the draggable item. Learners must + drag the item to any one of the target zones that you select. + + * - **Item Image URL** + - (Optional) the URL of an image that appears on a draggable item. The + image appears on the draggable item in the problem. + + The URL can be relative to a file you add to your + course or to a file on the web. + + * - **Item Image description** + - Text that describes the image label for a draggable item. The + description is used by learners who cannot access the visual image + label. + + * - **Item Success Feedback** + - The text message that appears above the background image when a learner + places a draggable item on its matching target zone. For an example, see + :ref:`overview_of_drag_and_drop_problems`. This is an optional + configuration. If you do not enter a success feedback message, the + LMS will not display one. + + * - **Item Error Feedback** + - The text message that appears above the background image when a learner + places a draggable item on an incorrect matching target zone. For an + example, see + :ref:`overview_of_drag_and_drop_problems`. This is an optional + configuration. If you do not enter an error feedback message, the + LMS will not display one. + + * - **Item Show advanced settings** + - Opens additional controls for configuring a draggable item. + + * - **Item Preferred width** + - The horizontal size of a draggable item as a percent of the problem + width. The percent value must be a whole number between 0 and 100. + + * - **Add an item** + - Adds a set of controls for a new draggable item to the **Editing** + dialog box. + +.. _changing_visual_style_of_drag_and_drop_problem: + +**************************************************** +Changing the Visual Style of a Drag and Drop Problem +**************************************************** + +You can change the visual appearance of drag and drop problems in your courses. + +The **Background color** and **Text color** controls for the draggable items in +a drag and drop problem set the appearance of items for an individual problem. +You can choose colors for the background and text of items when you create or +edit a drag and drop problem. + +.. only:: Open_edX + + You can develop a Python programming language module and include a custom + Cascading Style Sheet (CSS) file for drag and drop problems in your Open edX + site. For more information, see + :ref:`styling_drag_and_drop_problems`. + + diff --git a/source/educators/migration_wip/10_exercises_tools/drag_and_drop_deprecated.rst b/source/educators/migration_wip/10_exercises_tools/drag_and_drop_deprecated.rst new file mode 100644 index 000000000..98f9e8915 --- /dev/null +++ b/source/educators/migration_wip/10_exercises_tools/drag_and_drop_deprecated.rst @@ -0,0 +1,686 @@ +.. _Drag and Drop: + +################################## +Drag and Drop Problem (Deprecated) +################################## + +.. note:: + EdX does not support this problem type. + +This drag and drop problem type has been replaced by a newer drag and drop +problem type. The newer drag and drop problem type includes significant +improvements and you should use it for any new course development. For more +information about the replacement drag and drop problem type, see +:ref:`drag_and_drop_problem`. + +.. warning:: + + * **This deprecated drag and drop problem type is not accessible for learners + with some disabilities, and it does not work correctly on mobile phones and + other devices that use touch screen interfaces.** If you use this kind of + problem, make sure that you include an alternative for learners who cannot + access drag and drop problems, or leave these problems ungraded. + + For more information about creating accessible content, see + :ref:`Accessibility Best Practices for Course Content Development`. + + * The **Show Answer** button does not work for drag and drop problems. By + default, the **Show Answer** option is set to **Never**. If you change this + option in the problem component, a **Show Answer** button appears in the + LMS, but the button does not work. + +In drag and drop problems, learners respond to a question by dragging text or +objects to a specific location on an image. + +.. image:: ../images/DragAndDropProblem.png + :alt: Image of a drag and drop problem. + +********************************* +Adding a Drag and Drop Problem +********************************* + +Before you can include problems that use this deprecated problem type in your +course, you must configure your course to :ref:`add unsupported problems +`. + +To create a drag and drop problem, you upload the image that you want learners +to drag labels onto, and then create a problem component. + +#. On the **Files & Uploads** page, upload your image file. For more + information about uploading files, see :ref:`Add Files to a Course`. +#. In the unit where you want to create the problem, click **Problem** under + **Add New Component**, and then click the **Advanced** tab. +#. Click **Drag and Drop**. +#. In the component that appears, click **Edit**. +#. In the component editor, replace the example text with the text of your + problem. +#. In the ```` tag, replace + **https://studio.edx.org/c4x/edX/DemoX/asset/L9_buckets.png** with the URL + of your image file on the **Files & Uploads** page (for example, + **/static/Image.png**). +#. For at least one ```` tag, replace the text of the **label** + attribute with the text of the label you want learners to drag. For example, + if you want learners to drag the word "Iceland" onto your image, the new tag + would resemble the following: + + ```` + +8. Repeat the previous step for all the labels that you want to use. Make sure + that the **id** attribute is different for each ```` tag. +#. Determine the coordinates and radius of the correct area on the image. +#. Under ``correct_answer = {``, add an entry for each label, using the + following format. These values are in pixels: + + ``'id': [[x coordinate, y coordinate], radius]`` + + For example, if your image is 600 pixels wide and 400 pixels high, and you + want your learners to drag the Iceland label to an area in the upper-left + part of the image and drag a Sweden label near the lower-right part of your + image, the code would resemble the following (where 2 is the ID for the + Sweden label). + + .. code-block:: xml + + correct-answer = { + '1': [[50, 50], 75] + '2': [[550, 350], 75]} + + .. note:: Make sure the code contains the closing curly brace (``}``). + +#. Click **Save**. + +========================================== +Sample Drag and Drop Problem Code +========================================== + +To create the drag and drop problem that appears in the image above, you +download two files from edX, upload these files to the **Files & Uploads** +page, and then add the code for the problem to a problem component. + +#. Download the following files from edX: + + * Allopurinol.gif + * AllopurinolAnswer.gif + + To download both these files in a .zip archive, click + http://files.edx.org/DragAndDropProblemFiles.zip. + +#. Upload the Allopurinol.gif and AllopurinolAnswer.gif files to the **Files & + Uploads** page. +#. In the unit where you want to create the problem, click **Problem** under + **Add New Component**, and then click the **Advanced** tab. +#. Click **Drag and Drop**. +#. In the component that appears, click **Edit**. +#. In the component editor, replace the example code with the following code. +#. Click **Save**. + +**Problem Code**: + +.. code-block:: xml + + +

Allopurinol is a drug used to treat and prevent gout, a very painful form of arthritis. Once only a “rich man’s disease”, gout has become more and more common in recent decades – affecting about 3 million people in the United States alone. Deposits of needle-like crystals of uric acid in connective tissue or joint spaces cause the symptoms of swelling, stiffness and intense pain. Individuals with gout overproduce uric acid because they cannot eliminate it efficiently. Allopurinol treats and prevents gout by stopping the overproduction of uric acid through inhibition of an enzyme required for the synthesis of uric acid.

+

You are shown one of many possible molecules. On the structure of allopurinol below, identify the functional groups that are present by dragging the functional group name listed onto the appropriate target boxes on the structure. If you want to change an answer, you have to drag off the name as well. You may need to scroll through the names of functional groups to see all options.

+ + + + + + + + + + + + + + + + correct_answer = [ + {'draggables': ['2'], 'targets': ['0' ], 'rule':'unordered_equal' }, + {'draggables': ['none'], 'targets': ['1' ], 'rule':'unordered_equal' }] + if draganddrop.grade(submission[0], correct_answer): + correct = ['correct'] + else: + correct = ['incorrect'] + + + + + + + + +.. _Drag and Drop Problem XML: + +********************************* +Drag and Drop Problem XML +********************************* + +.. code-block:: xml + + + +

Drag each word in the scrollbar to the bucket that matches the number of + letters in the word.

+ + + + + + + + + + + + + + + correct_answer = { + '1': [[70, 150], 121], + '6': [[190, 150], 121], + '8': [[190, 150], 121], + '2': [[310, 150], 121], + '9': [[310, 150], 121], + '11': [[310, 150], 121], + '4': [[420, 150], 121], + '7': [[420, 150], 121], + '3': [[550, 150], 121], + '5': [[550, 150], 121], + '10': [[550, 150], 121]} + if draganddrop.grade(submission[0], correct_answer): + correct = ['correct'] + else: + correct = ['incorrect'] + + + + +.. code-block:: xml + + + +

Label the hydrogen atoms connected with the left carbon atom.

+ + + + + + + + + + + + + + + + correct_answer = [{ + 'draggables': ['1', '2'], + 'targets': ['t2', 't3', 't4' ], + 'rule':'anyof' + }] + if draganddrop.grade(submission[0], correct_answer): + correct = ['correct'] + else: + correct = ['incorrect'] + + + + + +======== +Tags +======== + +* ````: Indicates that the problem is a custom response + problem. +* ````: Indicates the custom response problem is a drag + and drop problem. +* ````: Specifies a single object that a learner will drag onto the + base image. +* ````: Specifies the location on the base image where a draggable must + be dropped. + +**Tag:** ```` + + Attributes + + .. list-table:: + :widths: 20 80 + :header-rows: 1 + + * - Attribute + - Description + * - img (required) + - Relative path to an image that will be the base image. All draggables + can be dragged onto it. + * - target_outline + - Specifies whether an outline (gray dashed line) should be drawn around + targets (if they are specified). It can be either 'true' or 'false'. + If not specified, the targets do not have outlines. + * - one_per_target + - Specify whether to allow more than one draggable to be placed onto a + single target. It can be either 'true' or 'false'. If not specified, + the default value is 'true'. + * - no_labels (required) + - The default is false. In default behavior, if label is not set, label + is obtained from id. If no_labels is true, labels are not + automatically populated from id, and one cannot set labels and obtain + only icons. + + Children + + * ```` + * ```` + +**Tag:** ```` + +Specifies a single draggable object in a drag and drop problem. + +A draggable is what the user must drag out of the slider and drop onto the base +image. After a drag operation, if the center of the draggable is located +outside the rectangular dimensions of the image, it will be returned to the +slider. + +For the grader to work, each draggable must have a unique ID. + + Attributes + + .. list-table:: + :widths: 20 80 + :header-rows: 1 + + * - Attribute + - Description + * - id (required) + - Unique identifier of the draggable object. + * - label (optional) + - Text label that the user sees. + * - icon (optional) + - For draggables that are images, the relative path to the image file. + * - can_reuse + - The default is false. If true, the same draggable can be used + multiple times. + + Children + + (none) + +**Tag:** ```` + +Specifies the location on the base image where a learner must drop a draggable +item. By design, if the center of a draggable lies within the target (i.e. in +the rectangle defined by [[x, y], [x + w, y + h]], it is within the target. +Otherwise, it is outside. + +If you specify at least one target, and a learner drops a draggable item on a +location that is outside a target, the draggable item returns to the slider. + +If you don't specify a target, a learner can drop a draggable item anywhere on +the base image. + + Attributes + + .. list-table:: + :widths: 20 80 + :header-rows: 1 + + * - Attribute + - Description + * - id (required) + - Unique identifier of the target object. + * - x + - X-coordinate on the base image where the top left corner of the target + will be positioned. + * - y + - Y-coordinate on the base image where the top left corner of the target + will be positioned. + * - w + - Width of the target, in pixels. + * - h + - Height of the target, in pixels. + + Children + + (none) + +********************** +Targets on Draggables +********************** + +Sometimes it is not enough to have targets only on the base image, and all of +the draggables on these targets. If a complex problem exists where a draggable +must become itself a target (or many targets), then the following extended +syntax can be used. + +:: + + ... + + + + + ... + + ... + +The attribute list in the tags above (``draggable`` and ``target``) is the same +as for normal ``draggable`` and ``target`` tags. The only difference is when +you will be specifying inner target position coordinates. Use the ``x`` and +``y`` attributes to set the offset of the inner target from the upper-left +corner of the parent draggable (that contains the inner target). + +===================================== +Limitations of targets on draggables +===================================== + +* Currently there is a limitation to the level of nesting of targets. + + Even though you can pile up a large number of draggables on targets that + themselves are on draggables, the drag and drop problem will be graded only + if there is a maximum of two levels of targets. The first level are the + `base` targets. They are attached to the base image. The second level are the + targets defined on draggables. + +* Another limitation is that the target bounds are not checked against other + targets. + + You must make sure that there is no overlapping of targets. You should also + ensure that targets on draggables are smaller than the actual parent + draggable. Technically this is not necessary, but from the usability + perspective it is desirable. + +* You can have targets on draggables only in the case when there are base + targets defined (base targets are attached to the base image). + + If you do not have base targets, then you can only have a single level of + nesting (draggables on the base image). In this case the client side will be + reporting (x,y) positions of each draggable on the base image. + +********************** +Correct answer format +********************** + +For specifying answers for targets on draggables, see `Answer format for +targets on draggables`_. + +There are two correct answer formats: short and long. + +In short form, the correct answer is mapping of ``draggable_id`` to +``target_id``:: + + correct_answer = {'grass': [[300, 200], 200], 'ant': [[500, 0], 200]} + correct_answer = {'name4': 't1', '7': 't2'} + +In long form, the correct answer is list of dicts. Every dict has 3 keys: +``draggables``, ``targets`` and ``rule``. For example:: + + correct_answer = [ + { + 'draggables': ['7', '8'], + 'targets': ['t5_c', 't6_c'], + 'rule': 'anyof' + }, + { + 'draggables': ['1', '2'], + 'targets': ['t2_h', 't3_h', 't4_h', 't7_h', 't8_h', 't10_h'], + 'rule': 'anyof' + }] + +"Draggables" is the list of draggable IDs. "Target" is the list of target IDs +that draggables must be dragged to. + +.. Caution:: + Draggables in dicts inside the ``correct_answer`` list must not intersect. + +Wrong (for draggable id 7):: + + correct_answer = [ + { + 'draggables': ['7', '8'], + 'targets': ['t5_c', 't6_c'], + 'rule': 'anyof' + }, + { + 'draggables': ['7', '2'], + 'targets': ['t2_h', 't3_h', 't4_h', 't7_h', 't8_h', 't10_h'], + 'rule': 'anyof' + }] + +The values for ``rule`` follow. + +* ``exact``: Targets for draggable IDs in ``user_answer`` are the same as + targets from the correct answer. For example, for draggables 7 and 8, the + user must drag 7 to target1 and 8 to target2 if the ``correct_answer`` is:: + + correct_answer = [ + { + 'draggables': ['7', '8'], + 'targets': ['tartget1', 'target2'], + 'rule': 'exact' + }] + + +* ``unordered_equal``: Allows draggables be dragged to targets unordered. For + learners to drag 7 to target1 or target2 and 8 to target2 or target1 and 7 + and 8 must be in different targets, then correct answer must be:: + + correct_answer = [ + { + 'draggables': ['7', '8'], + 'targets': ['tartget1', 'target2'], + 'rule': 'unordered_equal' + }] + + +* ``anyof``: Allows draggables to be dragged to any target. For learners to + drag 7 and 8 to target1 or target2, any of these are correct with the `anyof` + rule:: + + correct_answer = [ + { + 'draggables': ['7', '8'], + 'targets': ['tartget1', 'target2'], + 'rule': 'anyof' + }] + +If ``can_reuse`` is true, then you have draggables a,b,c and 10 targets. These +will allow you to drag 4 ``a`` draggables to [``target1``, ``target4``, +``target7``, ``target10``]; you do not need to write ``a`` four times. Also +this will allow you to drag the ``b`` draggable to target2 or target5 for +target5 and target2.:: + + correct_answer = [ + { + 'draggables': ['a'], + 'targets': ['target1', 'target4', 'target7', 'target10'], + 'rule': 'unordered_equal' + }, + { + 'draggables': ['b'], + 'targets': ['target2', 'target5', 'target8'], + 'rule': 'anyof' + }, + { + 'draggables': ['c'], + 'targets': ['target3', 'target6', 'target9'], + 'rule': 'unordered_equal' + }] + +Sometimes you want to allow learners to drag only two ``b`` draggables. In this +case you should use the ``anyof+number`` or ``unordered_equal+number`` rule:: + + correct_answer = [ + { + 'draggables': ['a', 'a', 'a'], + 'targets': ['target1', 'target4', 'target7'], + 'rule': 'unordered_equal+number' + }, + { + 'draggables': ['b', 'b'], + 'targets': ['target2', 'target5', 'target8'], + 'rule': 'anyof+number' + }, + { + 'draggables': ['c'], + 'targets': ['target3', 'target6', 'target9'], + 'rule': 'unordered_equal' + }] + +When there are no multiple draggables per targets (one_per_target=``true``), +for the same number of draggables, ``anyof`` is equal to ``unordered_equal``. + +If ``can_reuse=true``, then you must use only the long form of the correct +answer. + +======================================= +Answer format for targets on draggables +======================================= + +As with the cases described above, an answer must provide precise positioning +for each draggable (on which targets it must reside). In the case when a +draggable must be placed on a target that itself is on a draggable, then the +answer must contain the chain of target-draggable-target. + +For example, suppose we have three draggables - ``up``, ``s``, and ``p``. +Draggables ``s`` and ``p`` have targets on themselves. More specifically, +``p`` has three targets - ``1``, ``2``, and ``3``. The first requirement is +that ``s`` and ``p`` are positioned on specific targets on the base image. The +second requirement is that draggable ``up`` is positioned on specific targets +of draggable ``p``. Below is an excerpt from a problem:: + + + + + + + + + + + + + + ... + + correct_answer = [ + { + 'draggables': ['p'], + 'targets': ['p-left-target', 'p-right-target'], + 'rule': 'unordered_equal' + }, + { + 'draggables': ['s'], + 'targets': ['s-left-target', 's-right-target'], + 'rule': 'unordered_equal' + }, + { + 'draggables': ['up'], + 'targets': ['p-left-target[p][1]', 'p-left-target[p][2]', 'p-right- + target[p][2]', 'p-right-target[p][3]',], + 'rule': 'unordered_equal' + } + ] + +Note that you must specify rules for all draggables, even if a draggable gets +included in more than one chain. + +************* +Grading logic +************* + +#. The learner's answer and the correct answer are parsed to the same format. + :: + + group_id: group_draggables, group_targets, group_rule + + ``group_id`` is ordinal number, for every dict in correct answer incremental + ``group_id`` is assigned: 0, 1, 2, ... + + Draggables from the user answer are added to the same group_id where + identical draggables from the correct answer are, for example:: + + If correct_draggables[group_0] = [t1, t2] then + user_draggables[group_0] are all draggables t1 and t2 from the user answer: + [t1] or [t1, t2] or [t1, t2, t2] etc.. + +#. For every group from the user answer, for that group's draggables, if + ``number`` is in the group rule, set() is applied. If ``number`` is not in + rule, set is not applied:: + + set() : [t1, t2, t3, t3] -> [t1, t2, ,t3] + + For every group, at this step, draggables lists are equal. + +#. For every group, lists of targets are compared using the rule for that + group. + +========================== +Set and ``+number`` cases +========================== + +``set()`` and ``+number`` are needed only for the case of reusable draggables. +For other cases there are no equal draggables in list, so set() does nothing. + +* The ``set()`` operation allows you to create a rule for the case of "any + number of the same draggable can be dragged to targets":: + + { + 'draggables': ['draggable_1'], + 'targets': ['target3', 'target6', 'target9'], + 'rule': 'anyof' + } + +* The ``number`` rule is used for the case of reusable draggables, when you + want to fix number of draggable to drag. In this example only two instances + of draggables_1 are allowed to be dragged:: + + { + 'draggables': ['draggable_1', 'draggable_1'], + 'targets': ['target3', 'target6', 'target9'], + 'rule': 'anyof+number' + } + + +* Note, that in using rule ``exact``, one does not need ``number``, because you + cannot recognize from the user interface which reusable draggable is on which + target. For example:: + + { + 'draggables': ['draggable_1', 'draggable_1', 'draggable_2'], + 'targets': ['target3', 'target6', 'target9'], + 'rule': 'exact' + } + + + Correct handling of this example is to create different rules for + draggable_1 and draggable_2. + +* For ``unordered_equal`` (or ``exact``) you don't need ``number`` if you have + only the same draggable in the group, as the target length will provide + the constraint for the number of draggables:: + + { + 'draggables': ['draggable_1'], + 'targets': ['target3', 'target6', 'target9'], + 'rule': 'unordered_equal' + } + + This means that only ``draggable_1`` can be dragged. + +* But if you have more than one different reusable draggable in the list, you + may use the ``number`` rule:: + + { + 'draggables': ['draggable_1', 'draggable_1', 'draggable_2'], + 'targets': ['target3', 'target6', 'target9'], + 'rule': 'unordered_equal+number' + } + +If you do not use ``number``, the draggables list will be set to +[``draggable_1``, ``draggable_2``]. diff --git a/source/educators/migration_wip/10_exercises_tools/dropdown.rst b/source/educators/migration_wip/10_exercises_tools/dropdown.rst new file mode 100644 index 000000000..cc029057c --- /dev/null +++ b/source/educators/migration_wip/10_exercises_tools/dropdown.rst @@ -0,0 +1,429 @@ +.. _Dropdown: + +##################### +Dropdown Problem +##################### + +.. note:: EdX offers full support for this problem type. + +The dropdown problem type is a simple problem type that can be added to any +course. Dropdown problems include a question or prompt and +several answer options with a single correct answer. By adding hints, feedback, or both, you can give +learners guidance and help when they work on a problem. + +.. contents:: + :local: + :depth: 2 + +For more information about the simple problem types, see +:ref:`Working with Problem Components`. + +********** +Overview +********** + +In dropdown problems, learners select one answer from a list of answer options. +Unlike :ref:`single select` problems, where the answer +choices are always visible directly below the question, the answer options for +dropdown problems do not appear until the learner selects the dropdown arrow. + +Dropdown problems can only have one correct answer per question, we recommend +adding a "Both B & C" answer where multiple selections could be correct. + +================================ +Example Dropdown Problem +================================ + +In the LMS, learners select a single answer option to complete a dropdown +problem. An example of a dropdown problem from the learner's perspective follows. + +.. image:: ../images/DropdownExample2.png + :alt: A problem component that contains three answer choices. + :width: 400 + +******************************** +Adding a Dropdown Problem +******************************** + +You add dropdown problems in Studio by selecting the **Problem** +component. In the problem editor, select the **Dropdown** option. Fill in +the fields on this screen to create your problem. + +.. image:: ../images/problem_editor_dropdown.png + :alt: An example dropdown problem in the problem editor with number + indicators labeling the various features. + :width: 800 + +Creating a dropdown problem is as simple as: + +#. Editing the **Display Name**. Click the pen symbol to edit. +#. Filling in the **Question** field. +#. Filling in the **Explanation** field. When this is shown to learners is + based on the selection in the **Show answer** panel on the right. +#. Filling in the Answer fields. Select the correct answer by ticking off + the radio button. Additional answers can be added by clicking the + **Add answer** button. Answers can be deleted by clicking the trash can + icon. Feedback can be provided for each answer. More information on + feedback can be found in the following section. +#. Selecting and filling in any desired settings on the right. + +If you have any questions on the specifics of using the simple editor, please check +out :ref:`Simple Editor` and :ref:`Problem Settings`. + +.. _Use Feedback in a Dropdown Problem: + +=========================================== +Adding Feedback +=========================================== + +For an overview of feedback in problems, see :ref:`Adding Feedback and Hints to +a Problem`. You can add feedback for each of the answer options you provide in +the problem. Use the following guidelines when providing feedback. + +* Use feedback for the incorrect answers to target common misconceptions and + mistakes. + +* Ensure feedback provides some guidance to the learner about how to arrive at + the correct answer. + +* Use feedback for the correct answer to reinforce why the answer is correct. + Because learners are able to guess, ensure that feedback provides a reason + why the answer is correct for learners who might have selected that answer by + chance. + +.. image:: ../images/problem_editor_feedback_box_2.png + :alt: An example of an expanded feedback section for dropdown problems showing + the 'is selected' feedback field. + :width: 600 + +.. _Use Hints in a Dropdown Problem: + +=========================================== +Adding Hints +=========================================== + +You can add hints to a dropdown problem. For an overview of hints in problems, see +:ref:`Adding Feedback and Hints to a Problem`. + +.. include:: Subsection_configure_hints.rst + +.. _Editing Dropdown Problems using the Advanced Editor: + +**************************************************** +Editing Dropdown Problems using the Advanced Editor +**************************************************** + +If the simple editor is not enough to meet your needs, you can switch over to the +advanced editor. In the setting panels on the right of the editor, click +**Show advanced settings**, then scroll down and click +**Switch to advanced editor**. + +You can use the advanced editor to identify the elements of a dropdown problem +with OLX. For more information, see :ref:`Dropdown Problem XML`. To format equations, +you can use MathJax. For more information, see :ref:`MathJax in Studio`. + +You can see the OLX for the example problem from the Overview section below. + +.. code-block:: xml + + + + + + + + +.. note:: You can begin work on the problem in the simple editor, and then + switch to the advanced editor. However, after you save any advanced OLX + changes you make in the advanced editor, you may not be able to cannot + switch back to the simple editor. + +============================= +Adding Feedback +============================= + +In the advanced editor, you configure feedback with the following syntax. + +.. code-block:: xml + + + +For example, the following problem has feedback for each answer. + +.. code-block:: xml + + + + + + + + + + + + + +.. include:: Subsection_customizing_feedback_labels.rst + +======================================== +Adding Hints +======================================== + +.. include:: Subsection_configure_hints_advanced.rst + +.. _Dropdown Problem XML: + +********************************** +Dropdown Problem OLX Reference +********************************** + +======== +Template +======== + +.. code-block:: xml + + + + + Optional information about how to answer the question + + + +
+

Explanation or Solution Header

+

Explanation or solution text

+
+ + + + Hint 1 + Hint 2 + Hint 3 + + + +========= +Elements +========= + +For dropdown problems, the ```` element can include this +hierarchy of child elements. + +.. code-block:: xml + + +