User Manual For Drag Plugin

Version 1.0.0

Public

Modified: 10.6.2019

Created by Hanna Alatalo

University of Jyväskylä

Faculty of Information Technology

1. Overview

Drag plugin makes it possible to create draggable words. The plugin can be used to create gaps in sentences that must be filled by dragging words to them. Words can be dragged from one drag plugin to another. Words can also be reordered within a single plugin area. You can also use TIM's Style options on the words and even drag images and links (see Chapter 11).

Please see TIM manual (in Finnish) in case you have problems with the document creation.

The user manual covers

  • drag plugin options,
  • style options,
  • manual saving functionality and
  • examples.

2. Creation of a plugin area

A plugin area is created by writing the appropriate markdown in TIM's paragraph editor. The drag plugin area and its options are defined using YAML markdown language.

The following is an example of creation of an empty drag plugin area where defaultplugin defines the default inline plugin used in the following paragraph. pluginnamehere is the identifying name of the plugin. The name must be unique within the TIM document.

#-{defaultplugin="defaultplugin"}    
{#pluginnamehere:drag}

:drag may be omitted if the default inline plugin is "drag".

Menu options in the paragraph editor can be used to create basic drag plugin areas. You only need to remember to change the names.

Figure 1: The menu options after clicking Drag menu option.
Figure 1: The menu options after clicking Drag menu option.

3. Plugin options

All plugin options are optional and they are defined as follows:

#- {defaultplugin="drag"}
{#pluginnamehere option: value, option2: value2}

If an option is not defined in the markdown its default value is used. The options and their default values are the following:

Option Value Default See Chapter
words A list of strings e.g ["word", "word2"] [] Chapter 3
shuffle false or true false Chapter 4
copy source or target none Chapter 5
type A string e.g. "typenamehere" " " (space) Chapter 6
max A positive integer infinite Chapter 7
savebutton false or true false Chapter 8
trash false or true false Chapter 9

4. Initializing draggable words

words option defines a list of words to be made draggable. Each word should be in quotation marks. The words can contain style options that are discussed in Chapter 10. In the following markdown example, the words I, am and groot are inserted.

words: ["I", "am", "groot"]

If the word is not displayed correctly in the preview, check that the word (or symbol) is not reserved in YAML. For example the dash - needs to be written with \\- to make it display properly in the plugin. When in doubt try adding one or two \ in front of the word that is causing problems.

See the example in Section 12.1.

5. Shuffling

shuffle option enables word shuffling which means that the word order is randomized by the plugin every time the page is reloaded. Figure 2 presents a result. By setting shuffle: true, the contained words are shuffled. shuffle: false is the default value and it disables this option. In the following example the words a, b and c are shuffled and figure 2 presents the result.

#- {defaultplugin="drag"}
{#dragshuffle words: ["a","b","c"], shuffle: true}
Figure 2: Words are shuffled to a random order.
Figure 2: Words are shuffled to a random order.

See the example in Section 12.1.

Note: The words may be shuffled into the same order they were initially in.

6. Copying

copy option enables word copying and pasting. If a word is copied it will not move from one place to another but will generate a new draggable word that contains the word that was initially dragged.

The options' value can be either source or target. The Drag plugin area defined with copy: source keeps its draggable words and the dragged words are copies of them. copy: target option makes the plugin area only contain copies. Copies will disappear when dropped outside of target areas.

Note: Currently copies of words will be copied again if moved to another Drag plugin area with copy: target option enabled. For example in Section 12.3 if you drag an to the first empty drag plugin and then drag the an from there to the other empty drag plugin there will be an in both.

7. Types

type option will assign a type to the drag plugin area and its words. This can be useful if there are multiple drag plugins in a TIM document and the words should only be dropped to some of the areas. An example could be that the words are connected to different questions.

If type is defined in a drag plugin, only words with the same type can be dropped there.

See the example in Section 12.3.

Note: Default type assigned to the area is " " (a single space) if not otherwise specified. Having that type is equal to not having a type at all. In this case the area can only contain words that have been assigned the default type.

8. Maximum count of words

max option defines how many words may be dropped to the plugin. It can have a value of any positive integer. The default value is infinite.

In the following markdown example you may only drop one word in the drag plugin named dragmax1.

#- {defaultplugin="drag"}
{#dragmax1 max: 1}

See the example in Section 12.3.

9. Manual saving

Manual saving may be toggled by adding savebutton: true option. When a user presses the save button the current words are saved in the order that they are in the drag plugin area. If the user refreshes the page or closes the document and opens it again the saved words remain in the plugin area in the same order. Without manual saving, the words defined in the words option will reappear after page reload. Below is an example of enabling manual saving in the plugin.

#- {defaultplugin="drag"}
{#dragmanualsave savebutton: true}

Note: Currently this is the only way to save answers without using a feedback plugin.

Important note: The saving is based on the name of the drag plugin (see Section 2). Therefore it is important not to change the name after the document has been made public to the users.

10. Trashcan

With the trash option you can create a place to discard draggable words. trash: true makes all words that are dragged to the drag plugin disappear. trash: false disables the trashcan functionality and because it is the default value, it is not necessary. Below is an example of creating a trashcan.

#- {defaultplugin="drag"}
{#dragtrash trash: true}
Figure 3: This is what the trashcan looks like.
Figure 3: This is what the trashcan looks like.

Note: Words will not disappear from the plugins with copy: source option even if their copies are dragged to trash.

Note 2: Without manual saving, the words will reappear in their original places after the page is reloaded.

A draggable content can contain any style options found in the Style tab of TIM's paragraph editor, except Style options or any text containing }.

The recommended text style options are bold, italics, underline, overline and code. You may also find some use in links and images with the options found in the Insert tab. Make sure that all the related markdown stays between the quotation marks.

See the example in Section 12.4.

12. Examples

Here are some examples of common assignments that are created with drag plugins.

12.1 Reorderable sentence

By using one drag plugin area with the shuffle option you can create a reorderable sentence.

#- {defaultplugin="drag"}
{#reorder words: ["the", "weather", "is", "lovely", "almost" , "always"], shuffle: true}
Figure 4: The result is a shuffled sentence that can be reordered.
Figure 4: The result is a shuffled sentence that can be reordered.

I think we came to the conclusion that the correct order is allowed in shuffling since the learner doesn’t know it already is in the correct order. As noted in chapter 5. I will need to review the shuffling algorithm to verify the odds of it happening.

— 03 Jun 19 (edited 04 Jun 19)

12.2 Copying one word to multiple places

You can have one source area specified with the optioncopy: source and multiple target areas specified with the option copy: target. The following example specifies a question where the correct answer contains multiples of the same word dragged to the empty spaces. The markdown and corresponding image of the result are presented below.

#- {defaultplugin="drag"}
{#articles copy: source, words: ["a", "an", "the"]}

I ate {#a1 copy: target} apple and I ate {#a1 copy: target} orange.
Figure 5: There is one source area and two target areas.
Figure 5: There is one source area and two target areas.

12.3 Multiple types

In the following example we have a traditional english language assignment where there is a sentence with two gaps with missing words of different word classes. Such a sentence can be created by following the steps:

  1. Divide the words by their type, in this case word class, and assign them to the words options of the different drag plugins (named here articles and pronouns).
  2. Assign a different value (article or pronoun) to type option of each empty area,
  3. Write the sentence and add empty drag plugins to the word gaps, here ex1 and ex2.
  4. Assign types accordingly to the target areas.
  5. Assign a maximum amount of words to drag to gaps (max) as 1
#- {defaultplugin="drag"}
{#articles type: "article", words: ["a", "an", "the"]}
{#pronouns type: "pronoun", words: ["I", "Me", "Us"]}

I have {#ex1 type: "article", max: 1} apple. {#ex2 type: "pronoun", max: 1} like it.
Figure 6: The first gap accepts only articles and the second gap only pronouns.
Figure 6: The first gap accepts only articles and the second gap only pronouns.

12.4 Using style options

In the following example there is a sentence with words that are more important in the assignment in question. You can focus the learners' attention to those words with style options. Easiest way to use the style options is to select the word without the quotation marks and push the related style option button in TIM paragraph editor.

The following markdown creates the drag plugin displayed in Figure 7.

#- {defaultplugin="drag"}
{#dragstyle words: ["there", "*is*", "**no**", "place", "like", "home"]}
Figure 7: The word is is in italics and the word no is bolded.
Figure 7: The word is is in italics and the word no is bolded.

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