Dropdown Plugin, Guide for Further Development

Project: TIMCAN

Document creator: Kimmo Urtamo

Created: 27.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 dropdown plugin developed by the TIMCAN project. The dropdown plugin is a word selection similar to a HTML select element. By default the plugin is designed to work with a feedback plugin but it can be used independently.

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 as well as providing ideas for further development.

2. Structure and location of the plugin in TIM

The plugin consists of three parts. The css file defines the look of the plugin on the page, the ts file defines the front-end functionality of the plugin and the py file the back-end functionality of the plugin. The locations for these files are

  • timApp/modules/dropdown/css/dropdown.css,
  • timApp/modules/dropdown/js/dropdown.ts and
  • timApp/modules/dropdown/dropdown.py.

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.

3. Description of the functionality

The dropdown inline plugin is a word selection control similar to a HTML select element. The items inside it are presented as a dropdown list where the user can select one of the items.

You can either specify the content to be shown when creating the plugin or it can receive the content from other plugins implementing the ITimComponent interface. By default the plugin is designed to work with a feedback plugin and does not save the selection without a function call from it. If you enable an autosave option the plugin immediately saves the selection when the user selects another option from the list. You can also shuffle the order of the items in the list or change the plugin presentation from a dropdown list to radio buttons.

The following routes are used in the dropdown plugin:

  • answer handles the saving of a selection to the dropdown plugin.
  • reqs contains the templates for quick creation of a dropdown plugin.

5. AngularJS component dropdown.ts

The file dropdown.ts contains the code setting or getting the content in the plugin and initiating a save call to the back end. It also contains the function to register the dropdown plugin to the view control so it can communicate with other plugins that have registered to the view control as well. The file also includes AngularJS framework's HTML template of the plugin and the DropdownController.

5.1 The most relevant attributes in the dropdown controller

The relevant attributes and their explanations are the following:

  • answers tells whether the answer browser should be shown for the plugin. It is false by default, but the aforementioned functionality is not implemented yet.
  • autosave calls the answer route when the selection in the plugin changes. It is false by default. The plugin calls the answer route only if the save function in the plugin is called by another plugin. Setting the attribute to true enables autosaving.
  • c is the current state of the content in the plugin. This should be kept the same across all new plugins for cohesion.
  • instruction tells whether the plugin is a practice item (true) or not (false). In the case it is the selection is not saved to the database. It is relevant only if it is mandatory to answer the practice item in the task.
  • radio can be used to turn the dropdown plugin to be presented as a list of radio buttons instead of a select list. It if false by default.
  • shuffle enables the shuffling of the positions of the items in the plugin. It is false by default.
  • words is a string array of the items the plugin should have if the plugin is used independently from a feedback plugin.

5.2 The most relevant methods in the dropdown controller

The relevant methods and their descriptions are the following:

  • $onInit initiates the plugin. It contains setting of attributes and calling of methods as that should be done in the beginning.
  • addToCtrl adds the plugin to the view controller so other plugins registered with the view controller can interact with it.
  • getContent returns the currently selected item in the selection list.
  • save saves the selection in the plugin.
  • selfSave saves the selection in the plugin if the selection is changed when autosave is set to true.
  • setForceAnswerSave forces the plugin to always save its selection when the answer route is called if set to true.
  • setPluginWords sets the list of content in the plugin and shuffles it if shuffle is true.

6. Ideas for further development

The dropdown plugin was developed on the basis that it would only hold text strings. Adding support to other kinds of content as well might be useful. This would make the plugin more generally usable.

A way to use tuples or some other data format in the content of the dropdown plugin would allow easier comparison of images or similar content. Defining a string id to content and comparing the ids to each other is easier than comparing content in a strange format.

Adding a shared answer browser to multiple dropdown plugins should be done so that multiple dropdown plugins can be more easily combined as a single question with a single answer. This also removes extra elements from the page and makes it easier for the teacher to check a student's answer. It should probably be implemented on the inline plugin level though.

7. Relevant material

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

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