Feedback Plugin, Guide for Further Development

Project: TIMCAN

Document creator: Kimmo Urtamo

Created: 16.5.2019

Modified: 6.6.2019

For further queries: tim@jyu.fi

1. Purpose and content of the guide

The document describes the functionality and structure of the feedback plugin developed by the TIMCAN project. The feedback plugin is a plugin that works together with the drag&drop and dropdown plugins. The plugins together allow the creation of tests making use of adaptive feedback, which guides learners towards learning the concepts being studied. The feedback plugin can control certain aspects of the other plugins and also handles the flow of a task from the beginning to the end.

The purpose of the document is to provide an understanding of the implementation solutions in the plugin, supporting the understanding of the source code and comments in it.

2. Structure and location of the plugin in TIM

The code of the feedback plugin in TIM is mostly located in the files:

• timApp/modules/feedback/css/feedback.css,
• timApp/modules/feedback/css/hideanswerbrowser.css and
• timApp/modules/feedback/css/viewhide.css hide elements on the page.
• timApp/modules/feedback/js/feedback.ts contains the code for the front-end and
• timApp/modules/feedback/feedback.py contains the code for the back-end.

Other notable files are

• timApp/static/scripts/tim/document/viewctrl.ts which contains the ITimComponent interface and
• timApp/static/scripts/tim/plugin/util.ts which contains the functions usable by all TIM plugins.

Some smaller changes were made to the following files to hide elements from learners with only view rights in a TIM document that has a feedback plugin in it.

• timApp/document/docsettings.py contains general settings for TIM documents,
• timApp/static/scripts/tim/document/editing/editing.ts handles document editing for TIM,
• timApp/static/scripts/tim/document/notes.ts controls the comments in the right side of the document,
• timApp/templates/base.html is the base HTML of a TIM document,
• timApp/item/routes.py contains routes for TIM items and
• timApp/templates/view_html.html is a template for the document view.

The file timApp/plugin/containerLink.py was modified to turn some of the YAML fields of the feedback plugins to automatically use markdown without the need to specify markdown with the md: notation.

3. Description of the functionality

Almost every detail regarding the creation of an adaptive feedback task is defined in the YAML of the feedback plugin including

• all of the question items in the task,
• the names of the plugins for the question items located in the TIM document as well as the content in the plugins,
• what kind of feedback is provided on each selection and
• whether the selection was correct.

Most of the functionality in a task is done through the feedback plugin and depends on the document having a feedback plugin and the document settings being correct.

An answer is saved by calling the answer-route of the plugin. This saves the following information to the database:

• whether the answer was correct or not,
• the answer the learner provided,
• the correct answer to the question item and
• the feedback the learner was provided.

The flow of completing a task is the following:

1. When a learner starts a task the feedback plugin is in the instruction mode, waiting for the learner to read the instructions and click the Begin button.
2. After the learner clicks the Begin button the plugin changes to the question item mode, where it waits for the learner to select an answer to a question item presented to them.
3. After the learner clicks the OK button the plugin compares the learners answer to the correct answer, shows feedback to the learner, saves the selections in the question items to the database and moves to the feedback mode.
4. When the learner clicks the Continue button after reading the feedback, the plugin saves the feedback to the database along with the correct answer and the learners answer to the question item.
5. Next the plugin checks if any of the stopping conditions to end the task are met. If they are, the task has ended and the plugin moves to the end task mode. Otherwise the plugin moves back to the question item mode in step 2 and presents another question item to the learner. This continues until there are no more question items to be presented. At that point the plugin moves automatically from the feedback mode to the end task mode.
6. The plugin is in the end task mode and guides the learner forward.

4. Feedback route file feedback.py

The following routes are used in the feedback plugin:

• answer handles the saving of an answer.
• reqs contains the templates for quick creation of a task.

5. AngularJS component feedback.ts

The file feedback.ts contains

• the code controlling the flow of a task,
• providing feedback to the learner,
• setting or getting the content in the plugins of the question items in the task and
• dynamic hiding of elements in the document.

The file also includes AngularJS framework's HTML template of the plugin and the FeedbackController.

5.1 The most relevant attributes in the feedback controller

The most relevant attributes in the feedback controller are:

• correctsInRow is the number of correct answers the learner needs to get in a row to move on from a task. It is 1 by default.
• nextTask is the information the learner is presented when they reach the end of a task. For example, a link to the next task may be added. It has markdown enabled by default.
• practiseID is the id of the practice question item in a task. It is not mandatory, but if it is defined the practice item needs to be answered to be able to move to the actual task.
• questionItems is an array of QuestionItem objects. It has markdown enabled by default. A QuestionItem contains the following attributes:
  • area is the HTML class of the TIM area the question item is in, if it is inside a TIM area. It is not a mandatory attribute. At the writing of this document it is not recommended to use it, because the task already is inside a TIM area and TIM currently does not support areas inside areas.
  • dragSource is the name of the drag&drop plugin the words are dragged from to the plugin in the question item. It is only required, if the words in the drag source need to be reset during a task.
  • choices is an array of Choice objects. It has markdown enabled by default. A Choice contains the following attributes:
    • correct implies that the match is the correct answer to the question item. It is false by default.
    • levels is a string array containing the different levels of feedback for the question item. It has markdown enabled by default.
    • match is either a string array or a MatchElementArray object. Support for the use of MatchElementArrays in tasks does not currently exist.
  • pluginNames is a string array of the names of the plugins in the question items.
  • words is an array of string arrays that defines what is the content in the plugins defined in the pluginNames array.
• showAnswers makes it possible to cycle through previous answers in the View page of the document. By default it is disabled and the answers are only visible in the Answer page.
• shuffle defines whether the question items of the task should be presented in a random order or not. It is true by default.
• state is the state of the plugin and is used in presenting and browsing previous answers.

5.2 The most relevant methods in the feedback controller

The most relevant methods in the feedback controller are:

• $onInit initiates the plugin. It contains setting of attributes and calling of methods that should be done in the beginning.
• $doCheck periodically checks if the task creator has the TIM edit mode on, in which case all of the elements in the page relevant to the task are turned visible. When the test creator turns the edit mode off, the elements that were hidden before the mode was turned on are hidden again.
• addToCtrl adds the plugin to the view controller so other plugins in the view controller can interact with it.
• changeVisibility does most of the work for turning elements in the document hidden or visible. There are also a few support functions that can be called to turn different kinds of elements in the document hidden or visible.
• check* functions are used to check that the YAML of the feedback plugin is written so that the task works.
• compareChoices compares the answer the learner chose to the answer choices in the question item.
• getAnswerFromPlugins gets the answer to the current question item from the plugins in the question item and saves information about it to various variables for later use.
• getCorrectValues returns the correct answers to the plugins in the current question item.
• getSentence forms a sentence from the text and plugin names the method is provided. Currently the method is used to form the learners answer by replacing the plugin names by the learners selections or to form the correct answer to the question item by replacing the plugin names with the correct selections to the plugins in the question item.
• handleAnswer controls the state the task is in and calls all the relevant functions to hide elements, control plugins and present feedback to the learner.
• printFeedback handles the presentation of feedback to the learner.
• replacePlaceHolder handles the replacement of placeholders set in the YAML code by the test creator with the actual words in the question item.
• savePlugins function calls all of the plugins in the current question item and tells them to save their current state.
• setPluginWords calls all the plugins from all the question items and sets the words in them to the ones defined in the words attribute.

6. Ideas for further development

The feedback plugin was developed primarily for the Centre for Applied Language Studies and generality was a secondary concern. For that reason refactoring of the code may be necessary to support plugin types other than the two developed in the project. The suggested improvements to the feedback plugin are the following:

• Support for new plugin types and plugins setting their own content should be added to make the feedback plugin more generally usable.
• The way answers are checked needs to be made more secure to make the feedback plugin more appealing in less supervised exams or similar situations.
• More information to be shown to the learner might be useful. For example, one might want to dynamically show the feedback level they currently are in.
• By adding cumulative points to the feedback plugin a task could be used in school assignments or similar excercises.
• By allowing the definition of points to individual question items one could award answering harder questions correctly with more points.
• The setPluginWords function is called too many times unnecessarily. This should be optimized.
• The correct answer to the current question item should be transferred to the plugins in the question item when setting their words. This way the drag&drop plugin can check that the words aren't shuffled to the correct order.

To be able to use a task as a general question type modifying how a task works could be begun by:

• Skipping of the Begin button should be allowed.
• It should be possible to remove the question item hiding.
• the possibility to inform the learner in which task they are currently in should be added.

Separating the instructions and the practice item should be considered, but that might require adding another mode to the handleAnswer method and other changes will probably be needed as well.

If a drag&drop task has drag&drop plugins with droppable pieces that have different amount of words in them, using placeholders to get the pieces is currently possible by using the |part[i]| placeholder. This makes it difficult to reference parts of the answer if there is a lot of text and plugins in the question item. The reason is that every droppable piece counts as one part. The solution works fine if the question items are similar to the ones in ICAnDoiT with only one drag&drop plugin. However, one should consider implementing a placeholder just for the drag&drop pieces if it doesn't decrease the usability too much.

7. Relevant material

Apart from the document, maintainers might find useful information from the following material:

• User Manual for Creating Adaptive Feedback Test in the TIM https://tim.jyu.fi/view/ kurssit/tie/proj/2019/timcan/kayttoohjeet/instructions and
• source code in GitLab https://gitlab.com/jatakuiv/tim.