From c3da73ed1eea6be8afb24d5505190b2d4fa65ce9 Mon Sep 17 00:00:00 2001
From: Will Daly <will@edx.org>
Date: Fri, 1 Mar 2013 10:57:57 -0500
Subject: [PATCH] Changed title of custom response doc. Added custom response
 doc to index

---
 .../course_data_formats/custom_response.rst   | 142 ++++++++++++++++++
 doc/public/index.rst                          |   1 +
 2 files changed, 143 insertions(+)
 create mode 100644 doc/public/course_data_formats/custom_response.rst

diff --git a/doc/public/course_data_formats/custom_response.rst b/doc/public/course_data_formats/custom_response.rst
new file mode 100644
index 0000000000..1ca8214915
--- /dev/null
+++ b/doc/public/course_data_formats/custom_response.rst
@@ -0,0 +1,142 @@
+####################################
+CustomResponse XML and Python Script
+####################################
+
+This document explains how to write a CustomResponse problem.  CustomResponse
+problems execute Python script to check student answers and provide hints.
+
+There are two general ways to create a CustomResponse problem:
+
+
+*****************
+Answer tag format
+*****************
+One format puts the Python code in an ``<answer>`` tag:
+
+.. code-block:: xml
+
+    <problem>
+        <p>What is the sum of 2 and 3?</p>
+
+        <customresponse expect="5">
+        <textline math="1" />
+        </customresponse>
+
+        <answer>
+    # Python script goes here
+        </answer>
+    </problem>
+
+
+The Python script interacts with these variables in the global context:
+    * ``answers``: An ordered list of answers the student provided.
+      For example, if the student answered ``6``, then ``answers[0]`` would
+      equal ``6``.
+    * ``expect``: The value of the ``expect`` attribute of ``<customresponse>``
+      (if provided).
+    * ``correct``: An ordered list of strings indicating whether the
+      student answered the question correctly.  Valid values are
+      ``"correct"``, ``"incorrect"``, and ``"unknown"``.  You can set these
+      values in the script.
+    * ``messages``: An ordered list of message strings that will be displayed
+      beneath each input.  You can use this to provide hints to users.
+      For example ``messages[0] = "The capital of California is Sacramento"``
+      would display that message beneath the first input of the response.
+    * ``overall_message``: A string that will be displayed beneath the
+      entire problem.  You can use this to provide a hint that applies
+      to the entire problem rather than a particular input.
+
+Example of a checking script:
+
+.. code-block:: python
+
+    if answers[0] == expect:
+        correct[0] = 'correct'
+        overall_message = 'Good job!'
+    else:
+        correct[0] = 'incorrect'
+        messages[0] = 'This answer is incorrect'
+        overall_message = 'Please try again'
+
+**Important**: Python is picky about indentation.  Within the ``<answer>`` tag,
+you must begin your script with no indentation.
+
+*****************
+Script tag format
+*****************
+The other way to create a CustomResponse is to put a "checking function"
+in a ``<script>`` tag, then use the ``cfn`` attribute of the
+``<customresponse>`` tag:
+
+.. code-block:: xml
+
+    <problem>
+        <p>What is the sum of 2 and 3?</p>
+
+        <customresponse cfn="check_func" expect="5">
+        <textline math="1" />
+        </customresponse>
+
+        <script type="loncapa/python">
+    def check_func(expect, ans):
+        # Python script goes here
+        </script>
+    </problem>
+
+
+**Important**: Python is picky about indentation.  Within the ``<script>`` tag,
+the ``def check_func(expect, ans):`` line must have no indentation.
+
+The check function accepts two arguments:
+    * ``expect`` is the value of the ``expect`` attribute of ``<customresponse>``
+      (if provided)
+    * ``answer`` is either:
+
+        * The value of the answer the student provided, if there is only one input.
+        * An ordered list of answers the student provided, if there
+          are multiple inputs.
+
+There are several ways that the check function can indicate whether the student
+succeeded.  The check function can return any of the following:
+
+    * ``True``: Indicates that the student answered correctly for all inputs.
+    * ``False``: Indicates that the student answered incorrectly.
+      All inputs will be marked incorrect.
+    * A dictionary of the form: ``{ 'ok': True, 'msg': 'Message' }``
+      If the dictionary's value for ``ok`` is set to ``True``, all inputs are
+      marked correct; if it is set to ``False``, all inputs are marked incorrect.
+      The ``msg`` is displayed beneath the first input, and it may contain
+      XHTML markup.
+    * A dictionary of the form 
+
+.. code-block:: xml
+      
+    
+    { 'overall_message': 'Overall message',
+        'input_list': [
+            { 'ok': True, 'msg': 'Feedback for input 1'},
+            { 'ok': False, 'msg': 'Feedback for input 2'},
+            ... ] }
+
+The last form is useful for responses that contain multiple inputs.
+It allows you to provide feedback for each input individually,
+as well as a message that applies to the entire response.
+
+Example of a checking function:
+
+.. code-block:: python
+
+    def check_func(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 beneath the entire problem.
diff --git a/doc/public/index.rst b/doc/public/index.rst
index cd0136d192..084340e855 100644
--- a/doc/public/index.rst
+++ b/doc/public/index.rst
@@ -24,6 +24,7 @@ Specific Problem Types
 
    course_data_formats/drag_and_drop/drag_and_drop_input.rst
    course_data_formats/graphical_slider_tool/graphical_slider_tool.rst
+   course_data_formats/custom_response.rst
 
 
 Internal Data Formats