Merge pull request #119 from open-craft/master

Problem Builder - Review for release on edx.org

.gitignore

@@ -5,3 +5,8 @@
 /workbench.*
 /dist
 /templates
+/var
+*.iml
+.idea/*
+dump.rdb
+problem_builder.tests.*

.pep8

@@ -0,0 +1,2 @@
+[pep8]
+exclude=problem_builder/migrations

AUTHORS

@@ -9,3 +9,4 @@ Alan Boudreault <[email protected]>
 Eugeny Kolpakov <[email protected]>
 Braden MacDonald <[email protected]>
 Jonathan Piacenti <[email protected]>
+Tim Krones <[email protected]>

LICENSE.MIT

@@ -0,0 +1,30 @@
+------------------------------------------------------------------------------
+This license applies to the following third-party libraries included
+in this repository:
+
+  - backbone.paginator
+  - Backbone.js
+  - Underscore.js
+------------------------------------------------------------------------------
+
+The MIT License (MIT)
+
+Copyright (c) [year] [fullname]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,21 +1,24 @@
-Problem Builder XBlock
-----------------------
+Problem Builder and Step Builder
+--------------------------------
 
-[![Build Status](https://travis-ci.org/open-craft/problem-builder.svg?branch=master)](https://travis-ci.org/open-craft/problem-builder)
+[![Circle CI](https://circleci.com/gh/open-craft/problem-builder.svg?style=svg)](https://circleci.com/gh/open-craft/problem-builder)
 
-This XBlock allows creation of questions of various types and simulating the
-workflow of real-life mentoring, within an edX course.
+This repository provides two XBlocks: Problem Builder and Step Builder.
 
-It supports:
+Both blocks allow to create questions of various types. They can be
+used to simulate the workflow of real-life mentoring, within an edX
+course.
+
+Supported features include:
 
 * **Free-form answers** (textarea) which can be shared accross
   different XBlock instances (for example, to allow a student to
-  review and edit an answer he gave before).
-* **Self-assessment MCQs** (multiple choice), to display predetermined
-  feedback to a student based on his choices in the
+  review and edit an answer they gave before).
+* **Self-assessment MCQs** (multiple choice questions), to display
+  predetermined feedback to a student based on his choices in the
   self-assessment. Supports rating scales and arbitrary answers.
 * **MRQs (Multiple Response Questions)**, a type of multiple choice
-  question that allows the student to choose more than one choice.
+  question that allows the student to select more than one choice.
 * **Answer recaps** that display a read-only summary of a user's
   answer to a free-form question asked earlier in the course.
 * **Progression tracking**, to require that the student has
@@ -26,34 +29,22 @@ It supports:
 * **Dashboards**, for displaying a summary of the student's answers
   to multiple choice questions. [Details](doc/Dashboard.md)
 
-The screenshot shows an example of a problem builder block containing a
-free-form question, two MCQs and one MRQ.
+The following screenshot shows an example of a Problem Builder block
+containing a free-form question, two MCQs and one MRQ:
 
 ![Problem Builder Example](doc/img/mentoring-example.png)
 
 Installation
 ------------
 
-Install the requirements into the python virtual environment of your
+Install the requirements into the Python virtual environment of your
 `edx-platform` installation by running the following command from the
 root folder:
 
 ```bash
 $ pip install -r requirements.txt
 ```
 
-Enabling in Studio
-------------------
-
-You can enable the Problem Builder XBlock in studio through the advanced
-settings.
-
-1. From the main page of a specific course, navigate to `Settings ->
-   Advanced Settings` from the top menu.
-2. Check for the `advanced_modules` policy key, and add `"problem-builder"`
-   to the policy value list.
-3. Click the "Save changes" button.
-
 Usage
 -----
 

circle.yml

@@ -0,0 +1,27 @@
+machine:
+  python:
+    version: 2.7.10
+dependencies:
+  override:
+    - "pip install -U pip wheel"
+    # Temporarily pin setuptools to a specific version.
+    # See commit message of https://github.com/open-craft/problem-builder/commit/51277a34fb426724616618c1afdb893ab2de4c6b for more info:
+    - "pip install setuptools==24.3.1"
+    - "pip install -e git://github.com/edx/xblock-sdk.git@bddf9f4a2c6e4df28a411c8f632cc2250170ae9d#egg=xblock-sdk"
+    - "pip install -r requirements.txt"
+    - "pip install -r $VIRTUAL_ENV/src/xblock-sdk/requirements/base.txt"
+    - "pip install -r $VIRTUAL_ENV/src/xblock-sdk/requirements/test.txt"
+    - "pip uninstall -y xblock-problem-builder && python setup.py sdist && pip install dist/xblock-problem-builder-2.6.0.tar.gz"
+    - "pip install -r test_requirements.txt"
+    - "mkdir var"
+test:
+  override:
+    - "if [ $CIRCLE_NODE_INDEX = '0' ]; then pep8 problem_builder --max-line-length=120; fi":
+        parallel: true
+    - "if [ $CIRCLE_NODE_INDEX = '1' ]; then pylint problem_builder --disable=all --enable=function-redefined,undefined-variable,unused-import,unused-variable; fi":
+        parallel: true
+    - "python run_tests.py":
+        parallel: true
+        files:
+          - "problem_builder/v1/tests/**/*.py"
+          - "problem_builder/tests/**/*.py"

doc/Dashboard.md

@@ -80,3 +80,16 @@ must be in JSON format. The supported entries are:
 * **`"width"`**: (Important) The width of the images, in pixels (all images
   should be the same size).
 * **`"height"`**: (Important) The height of the images, in pixels
+
+
+Enabling in Studio
+------------------
+
+You can enable the Dashboard XBlock in Studio by modifying the advanced settings
+for your course:
+
+1. From the main page of a specific course, navigate to **Settings** ->
+   **Advanced Settings** from the top menu.
+2. Find the **Advanced Module List** setting.
+3. Add `"pb-dashboard"` to the modules listed there.
+4. Click the **Save changes** button.

doc/Problem Builder.md

@@ -0,0 +1,32 @@
+Problem Builder Usage
+=====================
+
+When you add the **Problem Builder** component to a course in the studio, the
+built-in editing tools guide you through the process of configuring the block
+and adding individual questions.
+
+See [Question Types](Questions.md) to learn about the various types of question
+that can be added to a Problem Builder block.
+
+
+Configuration Options
+---------------------
+
+### Maximum Attempts
+
+You can limit the number of times students are allowed to complete a
+Mentoring component by setting the **Max. attempts allowed** option.
+
+Before submitting an answer for the first time:
+
+![Max Attempts Before](img/max-attempts-before.png)
+
+After submitting a wrong answer two times:
+
+![Max Attempts Reached](img/max-attempts-reached.png)
+
+### Custom Window Size for Tip Popups
+
+You can specify **Width** and **Height** attributes of any Tip
+component to customize the popup window size. The value of those
+attributes should be valid CSS (e.g. `50px`).

doc/Questions.md

@@ -0,0 +1,138 @@
+Questions and Other Components
+==============================
+
+These are the types of questions that can be added to Problem Builder and Step
+Builder:
+
+
+### Free-form Questions
+
+Free-form questions are represented by a **Long Answer** component.
+
+Example screenshot before answering the question:
+
+![Answer Initial](img/answer-1.png)
+
+Screenshot after answering the question:
+
+![Answer Complete](img/answer-2.png)
+
+You can add **Long Answer Recap** components to problem builder blocks later on
+in the course to provide a read-only view of any answer that the student entered
+earlier.
+
+The read-only answer is rendered as a quote in the LMS:
+
+![Answer Read-Only](img/answer-3.png)
+
+### Multiple Choice Questions (MCQs)
+
+Multiple Choice Questions can be added to a problem builder component and have
+the following configurable options:
+
+* **Question** - The question to ask the student
+* **Message** - A feedback message to display to the student after they have
+  made their choice.
+* **Weight** - The weight is used when computing total grade/score of the
+  problem builder block. The larger the weight, the more influence this question
+  will have on the grade. Value of zero means this question has no influence on
+  the grade (float, defaults to `1`).
+* **Correct Choice[s]** - Specify which choice[s] are considered correct. If a
+  student selects a choice that is not indicated as correct here, the student
+  will get the question wrong.
+
+Using the Studio editor, you can add **Custom Choice** blocks to an MCQ. Each
+Custom Choice represents one of the options from which students will choose
+their answer.
+
+You can also add **Tip** entries. Each Tip must be configured to link it to one
+or more of the choices. If the student selects a choice, the tip will be
+displayed.
+
+**Screenshots**
+
+Before attempting to answer the questions:
+
+![MCQ Initial](img/mcq-1.png)
+
+While attempting to complete the questions:
+
+![MCQ Attempting](img/mcq-2.png)
+
+After successfully completing the questions:
+
+![MCQ Success](img/mcq-3.png)
+
+#### Rating Questions
+
+When constructing questions where the student rates some topic on the scale from
+`1` to `5` (e.g. a Likert Scale), you can use the Rating question type, which
+includes built-in numbered choices from 1 to 5. The `Low` and `High` settings
+specify the text shown next to the lowest and highest valued choice.
+
+Rating questions are a specialized type of MCQ, and the same instructions apply.
+You can also still add **Custom Choice** components if you want additional
+choices to be available such as "I don't know".
+
+### Multiple Response Questions (MRQs)
+
+Multiple Response Questions are set up similarly to MCQs. The answers are
+rendered as checkboxes. Unlike MCQs where only a single answer can be selected,
+MRQs allow multiple answers to be selected at the same time.
+
+MRQ questions have these configurable settings:
+
+* **Question** - The question to ask the student
+* **Required Choices** - For any choices selected here, if the student does
+  *not* select that choice, they will lose marks.
+* **Ignored Choices** - For any choices selected here, the student will always
+  be considered correct whether they choose this choice or not.
+* Message - A feedback message to display to the student after they have made
+  their choice.
+* **Weight** - The weight is used when computing total grade/score of the
+  problem builder block. The larger the weight, the more influence this question
+  will have on the grade. Value of zero means this question has no influence on
+  the grade (float, defaults to `1`).
+* **Hide Result** - If set to `True`, the feedback icons next to each choice
+  will not be displayed (This is `False` by default).
+
+The **Custom Choice** and **Tip** components work the same way as they do when
+used with MCQs (see above).
+
+**Screenshots**
+
+Before attempting to answer the questions:
+
+![MRQ Initial](img/mrq-1.png)
+
+While attempting to answer the questions:
+
+![MRQ Attempt](img/mrq-2.png)
+
+After clicking on the feedback icon next to the "Its bugs" answer:
+
+![MRQ Attempt](img/mrq-3.png)
+
+After successfully completing the questions:
+
+![MRQ Success](img/mrq-4.png)
+
+Other Components
+================
+
+### Tables
+
+Tables allow you to present answers to multiple free-form questions in a concise
+way. Once you create an **Answer Recap Table** inside a Mentoring component in
+Studio, you will be able to add columns to the table. Each column has an
+optional **Header** setting that you can use to add a header to that column.
+Each column can contain one or more **Answer Recap** elements, as well as HTML
+components.
+
+Screenshot:
+
+![Table Screenshot](img/mentoring-table.png)
+
+### "Dashboard" Self-Assessment Summary Block
+
+[Instructions for using the "Dashboard" Self-Assessment Summary Block](Dashboard.md)