Drag&drop plugin, Guide for Further Development

Project: TIMCAN

Document creator: Hanna Alatalo

Created: 28.5.2019

Modified: 10.6.2019

For further queries: tim@jyu.fi

Modified pvm puuttuu.

— 29 May 19

Näissä pitänee olla sekä created että modified, ainakin muissa ohjeissa on.

— 07 Jun 19

1. Purpose and content of the guide

The document describes the functionalities and structure of the drag&drop plugin developed by TIMCAN project in spring 2019.

The purpose of the document is to give insight to the implementation details of the plugin and links to related documentation and manuals.

2. Location of the plugin in TIM

The following Python file contains the used routes and templates

  • timApp/modules/dropdown/drag.py.

The following TypeScript files contain the AngularJS components and their related CSS style options are in the drag.css file.

  • timApp/modules/dropdown/js/drag.ts
  • timApp/modules/dropdown/css/drag.css

The following TypeScript files contain functions and interfaces common to all plugins:

  • timApp/static/scripts/tim/document/viewctrl.ts and
  • timApp/static/scripts/tim/plugin/util.ts.

The used libraries are defined in the file

  • timApp/static/scripts/tsconfig_plugin.json.

3. Description of the functionality

The drag&drop inline plugin makes it possible to drag, drop and reorder the content inside drag plugin areas in a TIM document. Draggable words or figures can be copied or moved from one drag&drop area to another. The drag&drop plugin areas can have a defined type of draggable words they can contain. For example, article can be a type for a draggable word.

Manual saving option can be enabled for example if the drag&drop plugin is used without a feedback plugin. The manual saving will save the content of c. The saved database entry will be different from the ones saved by the feedback plugin and therefore will not affect its functionality.

Mitä tapahtuu jos manuaalitallennuksen laittaa päälle kun on feedback myös käytössä?

— 29 May 19

4. Drag&drop route file drag.py

The following routes are used in the Drag&drop plugin:

  • answer handles the saving of the words contained in a drag&drop plugin area.
  • reqs contains the templates for quick creation of a drag&drop plugin area.

There is only one state variable:

  • c is the only state variable and it contains the words contained in the plugin area. It has the value of a string array.

5. AngularJS-component drag.ts

Draggable words are initialized and generated as objects that have all necessary fields to enable desired drag and drop behaviour. Objects are generated in createWordObjs method. Fields and attributes are utilized in AngularJS directives provided by Angular drag and drop lists library.

5.1 The most relevant attributes in the drag&drop controller

The most relevant attributes are the following:

  • c is the current state of the content in the plugin. It should be kept the same across all new plugins for cohesion.

  • type is used by dnd-allowed-types and dnd-type directives to control the types of words allowed in the area. It has a string value. The default value is " ".

  • max is used in the dnd-disable-if directive to disable dragging if the count of contained words in the area is larger than it. It is a positive integer value. The default is the maximum possible integer value in JavaScript.

  • copy is for enabling copying of words from one drag plugin to another by dragging. It can have the value of source which makes the words in the plugin area copyable or target which makes the plugin area accept only copies. The default value in code is "" by default which makes the functionality disabled.

  • trash is used to toggle between trashcan and normal drag plugin area with ng-if directive. See Chapter 7 in Angular drag and drop lists documentation. It is false by default.

  • saveButton enables manual saving with a save button. The feature is disabled by default and it can be enabled with the value true.

  • shuffle is a boolean value to enable word shuffling. It is false by default.

  • wordObjs is an array of word objects containing the words and their related attributes. They are initialized with createWordObjs method

5.2 The most relevant methods in the drag&drop controller

These are the most relevant methods in the controller:

  • $onInit initializes the plugin and sets the values to the attributes.

  • createWordObjs creates word objects from the attributes.

  • save saves the contained words.

  • getContent returns plugins words in a string separated by comma.

  • getContentArray returns plugins words in a string array.

  • setPluginWords sets plugins words from a string array.

  • resetField sets words of the plugin from the markdown of the plugin attributes.

6. Ideas for further development

The plugin needs to check that the words are not shuffled to the same order that they are in the correct answer of an adaptive feedback task. One implementation could be moving the information about the correct answer to the drag&drop plugin in the setPluginWords method of the feedback plugin. Then the shuffling could be repeated until the orders stop matching.

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 enable further control in dragging and dropping behaviours, utilization of the callbacks provided by Angular drag and drop lists library is recommended.

Copies of words are generated by dragging words from a drag&drop with copy: source attribute to drag&drop with copy: target. If they are dragged from the latter to another drag&drop with copy: target they will generate another copy of themselves instead of moving. This is caused by not changing the word's effectAllowed from copy to move. Changing the value should be possible by utilizing the related callbacks in dnd-moved. dnd-copied is an unused directive that could prove useful if the value can be changed after dropping the word for the first time.

The current solution to disable scrolling on Safari while dragging on touch device is labeled as temporary fix in the mobile drag drop library. Therefore it is recommended that its functionality is monitored closely and a better fix to be implemented if possible and necessary.

Some kind of automatic saving should be implemented since now only way to save the plugin's content is to add a save button or by using feedback plugin.

7. Relevant material

The following links will lead to the documents containing relevant information regarding the used libraries and current functionalities:

These are the current permissions for this document; please modify if needed. You can always modify these permissions from the manage page.