<commit_before>Mentoring XBlock
----------------

This XBlock allows to automate the workflow of real-life mentoring, within an edX course.

It supports:

* **Free-form answers** (textarea) which can be shared accross different XBlock instances (for example, to remind a student of an answer he gave before). Editable or read-only.
* **Self-assessment MCQs** (multiple choice), to display predetermined feedback to a student based on his choices in the self-assessment. Supports rating scales and arbitrary answers.
* **Progression tracking**, allowing to check that the student has completed the previous steps before allowing to complete a given XBlock instance. Provides a link to the next step to the student.
* **Tables**, which allow to present answers from the student to free-form answers in a concise way. Supports custom headers.
* **Data export**, to allow course authors to download a CSV file containing the free-form answers entered by the students

Examples
--------

### Free-form answers

First XBlock instance:

```xml
<mentoring url_name="goal_definition" followed_by="getting_feedback">
    <html>
        <p>What is your goal?</p>
    </html>

    <answer name="goal" />
</mentoring>
```

Second XBlock instance:

```xml
<mentoring url_name="getting_feedback">
    <html>
        <p>The goal you entered was:</p>
    </html>
    <answer name="goal" read_only="true" />

    <html>
        <p>Ask feedback from friends about this goal - what did they think?</p>
    </html>
    <answer name="goal_feedback" />
</mentoring>
```

### Self-assessment MCQs

```xml
<mentoring url_name="mcq_1" enforce_dependency="false">
    <mcq name="mcq_1_1" type="choices">
        <question>Do you like this MCQ?</question>
        <choice value="yes">Yes</choice>
        <choice value="maybenot">Maybe not</choice>
        <choice value="understand">I don't understand</choice>

        <tip display="yes">Great!</tip>
        <tip reject="maybenot">Ah, damn.</tip>
        <tip reject="understand"><html><div id="test-custom-html">Really?</div></html></tip>
    </mcq>

    <mcq name="mcq_1_2" type="rating" low="Not good at all" high="Extremely good">
        <question>How much do you rate this MCQ?</question>
        <choice value="notwant">I don't want to rate it</choice>

        <tip display="4,5">I love good grades.</tip>
        <tip reject="1,2,3">Will do better next time...</tip>
        <tip reject="notwant">Your loss!</tip>
    </MCQ>

    <message type="completed">
        All is good now...
        <html><p>Congratulations!</p></html>
    </message>
</mentoring>
```

### Self-assessment MRQs
```xml
<mentoring url_name="mcq_1" enforce_dependency="false">
    <mrq name="mrq_1_1" type="choices" max_attempts="3">
        <question>What do you like in this MRQ?</question>
        <choice value="elegance">Its elegance</choice>
        <choice value="beauty">Its beauty</choice>
        <choice value="gracefulness">Its gracefulness</choice>
        <choice value="bugs">Its bugs</choice>

        <tip require="gracefulness">This MRQ is indeed very graceful</tip>
        <tip require="elegance,beauty">This is something everyone has to like about this MRQ</tip>
        <tip reject="bugs">Nah, there isn't any!</tip>

        <message type="on-submit">Thank you for answering!</message>
    </mrq>
    <message type="completed">
        All is good now...
        <html><p>Congratulations!</p></html>
    </message>
</mentoring>

### Tables

```xml
<mentoring-table type="goal" url_name="goal_table">
    <column>
        <header>Your goal</header>
        <answer name="goal" />
    </column>

    <column>
        <header>Header Test 2</header>
        <answer name="goal_feedback" />
    </column>
</mentoring-table>
```

### Data export

```xml
<vertical>
    <mentoring-dataexport url_name="mentoring_dataexport"></mentoring-dataexport>
</vertical>
```

Installing dependencies
-----------------------

From the xblock-mentoring repository, and within the Python virtual environment you used to setup the XBlock
workbench or the LMS, install the requirements:

```bash
$ pip install -r requirements.txt
```

You also need to install the mentoring XBlock in the same virtual environment. From the `xblock-mentoring`
directory, enter:

```bash
$ pip install -e .
```

Since `XBlock` and `xblock-mentoring` are both in development, it is recommended
to use the `XBlock` revision specified in the workbench/LMS requirements.txt<commit_msg>Added a a section about the feedback child in README.md<commit_after>Mentoring XBlock
----------------

This XBlock allows to automate the workflow of real-life mentoring, within an edX course.

It supports:

* **Free-form answers** (textarea) which can be shared accross different XBlock instances (for example, to remind a student of an answer he gave before). Editable or read-only.
* **Self-assessment MCQs** (multiple choice), to display predetermined feedback to a student based on his choices in the self-assessment. Supports rating scales and arbitrary answers.
* **Progression tracking**, allowing to check that the student has completed the previous steps before allowing to complete a given XBlock instance. Provides a link to the next step to the student.
* **Tables**, which allow to present answers from the student to free-form answers in a concise way. Supports custom headers.
* **Data export**, to allow course authors to download a CSV file containing the free-form answers entered by the students

Examples
--------

### Free-form answers

First XBlock instance:

```xml
<mentoring url_name="goal_definition" followed_by="getting_feedback">
    <html>
        <p>What is your goal?</p>
    </html>

    <answer name="goal" />
</mentoring>
```

Second XBlock instance:

```xml
<mentoring url_name="getting_feedback">
    <html>
        <p>The goal you entered was:</p>
    </html>
    <answer name="goal" read_only="true" />

    <html>
        <p>Ask feedback from friends about this goal - what did they think?</p>
    </html>
    <answer name="goal_feedback" />
</mentoring>
```

### Self-assessment MCQs

```xml
<mentoring url_name="mcq_1" enforce_dependency="false">
    <mcq name="mcq_1_1" type="choices">
        <question>Do you like this MCQ?</question>
        <choice value="yes">Yes</choice>
        <choice value="maybenot">Maybe not</choice>
        <choice value="understand">I don't understand</choice>

        <tip display="yes">Great!</tip>
        <tip reject="maybenot">Ah, damn.</tip>
        <tip reject="understand"><html><div id="test-custom-html">Really?</div></html></tip>
    </mcq>

    <mcq name="mcq_1_2" type="rating" low="Not good at all" high="Extremely good">
        <question>How much do you rate this MCQ?</question>
        <choice value="notwant">I don't want to rate it</choice>

        <tip display="4,5">I love good grades.</tip>
        <tip reject="1,2,3">Will do better next time...</tip>
        <tip reject="notwant">Your loss!</tip>
    </MCQ>

    <message type="completed">
        All is good now...
        <html><p>Congratulations!</p></html>
    </message>
</mentoring>
```

### Self-assessment MRQs
```xml
<mentoring url_name="mcq_1" enforce_dependency="false">
    <mrq name="mrq_1_1" type="choices" max_attempts="3">
        <question>What do you like in this MRQ?</question>
        <choice value="elegance">Its elegance</choice>
        <choice value="beauty">Its beauty</choice>
        <choice value="gracefulness">Its gracefulness</choice>
        <choice value="bugs">Its bugs</choice>

        <tip require="gracefulness">This MRQ is indeed very graceful</tip>
        <tip require="elegance,beauty">This is something everyone has to like about this MRQ</tip>
        <tip reject="bugs">Nah, there isn't any!</tip>

        <message type="on-submit">Thank you for answering!</message>
    </mrq>
    <message type="completed">
        All is good now...
        <html><p>Congratulations!</p></html>
    </message>
</mentoring>
```

### Tables

```xml
<mentoring-table type="goal" url_name="goal_table">
    <column>
        <header>Your goal</header>
        <answer name="goal" />
    </column>

    <column>
        <header>Header Test 2</header>
        <answer name="goal_feedback" />
    </column>
</mentoring-table>
```

### Data export

```xml
<vertical>
    <mentoring-dataexport url_name="mentoring_dataexport"></mentoring-dataexport>
</vertical>
```

### Custom feedback popup window

You can use the `feedback` child to have a custom popup window. Currently, only the *width* and
*height* can be modified. The value of those attribute should be valid CSS.

```xml
<mentoring url_name="mcq_1" enforce_dependency="false">
    <mrq name="mrq_1_1" type="choices" max_attempts="3">
        <question>What do you like in this MRQ?</question>
        <choice value="elegance">Its elegance</choice>
        ...
        <feedback width="100px" height="50px"/>
    </mrq>
</mentoring>
```

Installing dependencies
-----------------------

From the xblock-mentoring repository, and within the Python virtual environment you used to setup the XBlock
workbench or the LMS, install the requirements:

```bash
$ pip install -r requirements.txt
```

You also need to install the mentoring XBlock in the same virtual environment. From the `xblock-mentoring`
directory, enter:

```bash
$ pip install -e .
```

Since `XBlock` and `xblock-mentoring` are both in development, it is recommended
to use the `XBlock` revision specified in the workbench/LMS requirements.txt
{'fraction_non_alphanumeric': 0.14105528694555391, 'fraction_numerical': 0.0040992221988648304, 'mean_word_length': 3.5052083333333335, 'pattern_counts': {'":': 0, '<': 218, '<?xml version=': 0, '>': 218, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 13}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4273267', 'n_tokens_mistral': 2946, 'n_tokens_neox': 2786, 'n_words': 931}