# Documentation

## Description

A text module enables to insert different parts of text into a presentation, including a type of task called "gap". A text gap consists of three activity types:

• a drop-down gap which enables to choose answers from a drop-down menu,
• a draggable gap which can be filled in with an item selected from a Source list (Source list is a separate module presented further in this documentation),
• an editable gap that enables to type text manually into it,
• a math gap, which is an editable gap working with MathJax.
• a filled gap, which is an editable gap with a placeholder.

All texts should be entered in the property called "Text" in the right-side menu. To define a certain type of a text gap, it is required to use simple scripts presented below:

• draggable and editable gap

\gap{blue} – blue is the correct answer that should be entered into a gap. "1" defines the value of a correct answer.

In case of more than one correct possibility the script is a bit different:

\gap{blue|navy} – both options are correct and they will be counted as such.

• drop-down gap

{{1:blue|yellow|red}} – the first option is always the correct answer, in this case it is "blue". "1" defines the value of a correct answer. if you want to keep the original order of the elements, check the 'Keep original order' property, and use the following formula: {{one|two|1:three}}, which means that "three" is the correct answer and 1 is the value of the correct answer.

• math gap

Use the editable gap pattern inside MathJax brackets $$MathJax commands$$. For example: $$\frac{1}{\gap{2}}$$ will render fraction with 1 as the nominator and an editable gap as the denominator, where the correct answer is 2.

Note: Keep in mind that the index of the gap in the module is defined by the order of the gaps written in the LaTeX formula. To properly navigate between gaps on a page in a situation when you have two gaps – one over another (e.g. integration limits), you should always define the upper limit first.

Example: $$\int^\gap{b}_\gap{a}f(x)dx$$

• filled gap

If you want a gap with the introductory text (e.g. to be corrected by students), use the filled gap's syntax. For example: \filledGap{initial text|answer} will render a gap with "initial text" as a placeholder and "answer" as the right answer.

For more than one answer, you should use the syntax for a draggable and editable gap:

\filledGap{initial text|answer|another answer} where the first value is a placeholder and the next two values are the answers.

## Definitions

It is possible to put definitions inside the Text module. To do it, use \def{my_id|word} syntax and "word" will be displayed as a clickable element with an id – "my_id". Clicking on the definition will trigger a Definition event which can be used by other modules. The most common use involves cooperation with Glossary addon.

## eKeyboard integration

It is possible to enter text into gaps using the eKeyboard module.

See the documentation of eKeyboard module »

## Audio

The text module also allows inserting simple audio controls. They add the possibility of playing and stopping a sound. Though there may be more than one audio in the text module, only one sound can be played simultaneously.
To add an audio control, use "Insert Audio" button on the toolbar of the text editor.
Adding the audio control is also possible using \audio{URL} syntax, where URL is the URL of the audio resource.

## Gap editor

The gap editor allows you to create a gap in an easy way. Depending on a gap type you want to create, you can choose:

• Editable
• Draggable
• Filled

For example, to create the editable gap, you should choose Editable from the 'Add gap' option.

Then, you will see the editor window like the one presented below:

If you fill in the first input: "first" and the second input: "second", that's equivalent to: \gap{first|second}

In each case, if you choose the Editable, Dropdown or Filled gap, simply click OK to save your changes, or Cancel to discard them.

## Properties

Property name Description
Is visible This property allows hiding or showing the module depending on the activity requirements.
Gap type This property serves for selecting a gap module type - editable (drop-down and fillable gap) or draggable. A common text paragraph should be marked as an "editable" gap type.
Gap width This property allows defining a gap width by default.
Gap max length This property allows defining a maximum amount of chars available to be put in each gap. If this property is set to zero, no restriction will be applied. If a gap's right answer is longer than the Gap max length property, the restriction for this gap will automatically increase to this length. For filled gaps, the length of placeholder is also taken into account in determining the maximum number of characters.
Is activity This property allows defining whether a text module is an activity or not. When it is not defined as an activity, the answers given are not taken into account in the overall result. It is helpful for e.g. simulations.
Is disabled This property allows disabling a text module so that it is not possible to enter any answers before certain actions are performed, e.g. a particular part of an activity is completed correctly.
Case sensitive When this property is checked it means that letter case is important while giving answers.
Use numeric keyboard When enabled, gaps will activate the virtual numeric keyboard on mobile devices when selected. This will also cause the gaps to only accept numeric values.
Text This property serves for inserting text into a module. Here it is also possible to define different types of gaps together with the required answers.
Ignore punctuation This property allows ignoring punctuation marks while checking the answers' correctness.
Open external link in This property allows selecting the location for new pages being opened via external links: new tab (default) or the same tab.
Keep original order This property let you keep the original order of elements in dropdown gaps.
Clear placeholder on focus This property allows clearing the placeholder on click in a filled gap.
Value type This property allows defining characters to be put into a gap. There are four vaues to choose from: Numbers only, Letters only, Alphanumeric and All. The default value of this property is set to "All".
Block wrong answers With this option checked, wrong answers are removed and the "on wrong" event is sent.
User action events With this option checked, text module will send the ValueChanged event on every change made in a gap.
Use escape character in gap This property allows using backslash ('\') to escape special characters in dropdown gaps. Backslash can escape: ':', '\'.
Lang attribute This property allows to define the language for this addon (different than the language of the lesson).
Speech texts List of speech texts: Number, Gap, Dropdown, Correct, Wrong, Empty, Inserted, Removed.
This texts will be read by Text to Speech addon after a user performs an action.

## Supported commands

Command name Params Description
setText text Changes the text inside the module
getGapText index - 1-based index of gap in text Returns gap text entered by user
markGapAsCorrect index - 1-based index of gap in text Mark gap as correct
markGapAsWrong index - 1-based index of gap in text Mark gap as wrong
markGapAsEmpty index - 1-based index of gap in text Mark gap as empty
show Shows the module
hide Hides the module
enableGap index - 1-based index of gap in module Enables gap
enableAllGaps --- Enables all gaps
disableGap index - 1-based index of gap in module Disables gap
disableAllGaps --- Disables all gaps
isAllOK --- Returns true if all gaps are filled in correctly and there are no mistakes, otherwise false.
isAttempted --- Returns true if all gaps are filled in. This command is not available if module has 'Is Activity' property deselected.
getView --- Returns HTML element, which is the container of the addon.

## Calculating gaps index

It's important to know that for each kind of gap (editable, draggable, math) the calculating order is:

1. First, all editable gaps are counted (both \gap and \filledgap),
2. Next, drop-down gaps are counted.

Example:

In this case, the getGapText(8) method returns text of a draggable gap, not the last gap.

## Decimal separator

Different countries use different decimal separators. In the Text module, the default one is a dot ('.') character but it doesn't mean that a user is forced to use this one. Thanks to Advanced Connector module, it's possible to change the decimal separator 'on the fly'. It can be done by using a simple JavaScript replace() function. Let's assume that there is a Slider module and its current step value (from 1 to 36) should be inserted in some equations and displayed using the Text module's setText command.

EVENTSTART
Source:Slider1
SCRIPTSTART
var text = presenter.playerController.getModule('Text1');
var slider = presenter.playerController.getModule('Slider1');
var currentValue = sliderModule.getCurrentStep();
var calculatedValue = (parseInt(currentValue, 10) - 18) / 5;

calculatedValue = '' + calculatedValue;

if (calculatedValue !== '0') {
calculatedValue = calculatedValue.replace("\.", ",");
};

text.setText('Calculated value: ' + calculatedValue);
SCRIPTEND
EVENTEND


## Events

The Text module sends ValueChanged events to Event Bus when a user changes the value of a gap.

Field name Description
Item index - 1-based index of gap in module
Value gap value
Score n for correct answer (where n is a maximum score for given gap), 0 for wrong

When a user clicks on a definition, it will trigger a definition event.

Field name Description
word id of the definition

All types of gaps in Text moule are fully compatible with Show Answers module and correct answers are displayed when an adequate event is sent.

## CSS classes

Class name Description
.text_gap Indicates the look of a gap that can be completed by typing the answer into it.
.text_gap-correct A way of indicating a right answer.
.text_gap-wrong a way of indicating a wrong answer.
.text_gap-empty A way of indicating an empty gap.
.ic_inlineChoice-correct A way of indicating a right answer in a drop-down menu.
.ic_inlineChoice-wrong A way of indicating a wrong answer in a drop-down menu.
.ic_inlineChoice-correct-answer A way of indicating a correct answer in a drop-down menu in the show answers mode.
.ic_draggableGapEmpty A way of displaying an empty gap.
.ic_draggableGapFilled A way of displaying a filled gap.
.ic_draggableGapFilled-correct a way of indicating a right answer in a filled gap
.ic_draggableGapFilled-wrong A way of indicating a wrong answer in a filled gap.
.ic_draggableGapFilled-correct-answer A way of indicating a correct answer in a draggable gap in the show answers mode.
.ic_filled_gap Indicates the look of a filled gap .
.ic_filled_gap-correct A way of indicating a corect answer in a filled gap.
.ic_filled_gap-wrong A way of indicating a wrong answer in a filled gap.
.ic_filled_gap-correct-answer A way of indicating a correct answer in a filled gap in the show answers mode.
.ic_gap-correct-answer A way of indicating a correct answer in an editable gap in the show answers mode.

### Examples

1. Text:
.text{
font-family: Arial;
font-size: 20px;
line-height: 23px;
color: #993399;
border: 2px solid #009999;
text-shadow: 1px 2px 2px #616161;
box-shadow: 1px 2px 3px #406d93;
background: #ffffff;
}

2.1. Gap:
.ic_gap{
height: 15px;
width: 108px;
}

2.2. Gap — correct:
.ic_gap-correct{
background-image: url('/file/serve/79016');
background-repeat: no-repeat;
border: 2px solid #009900;
}

2.3. Gap — wrong:
.ic_gap-wrong{
background-image: url('/file/serve/77022');
background-repeat: no-repeat;
border: 2px solid #f74224;
}

3.1. Inline Choice — correct:
.ic_inlineChoice-correct{
border: 2px solid #009900;
}

3.2. InlineChoice — wrong:
.ic_inlineChoice-wrong{
border: 2px solid #f74224;
}

4.1. Draggable Gap Empty:
.ic_draggableGapEmpty{
width:100px;
height: 25px;
line-height: 23px;
border: 1px solid #9e9e9e;
display:inline-block;
text-align: center;
}

4.2. Draggable Gap Filled:
.ic_draggableGapFilled{
width:100px;
height: 25px;
margin-right: 0px;
line-height: 23px;
display:inline-block;
border: 1px solid #9e9e9e;
background-color: #fff7b2;
cursor: pointer;
text-align: center;
font-size: 17px;
color: #656565;
font-family: Verdana;
font-weight: bold;
}

4.3. Draggable Gap Filled — correct:
.ic_draggableGapFilled-correct{
background-image: url('/file/serve/79016');
background-repeat: no-repeat;
}

4.4. Draggable Gap Filled — wrong:
.ic_draggableGapFilled-wrong{
background-image: url('/file/serve/77022');
background-repeat: no-repeat;
}

• Tab – navigate to the next gap.
• Shift + Tab – navigate to the previous gap.

Dropdown gaps:

• Space – expand the choice options.
• up/down arrows – choose a gap.
• Enter – accept.

Draggable gaps:

• Space – insert a currently selected item into a gap or remove an item from a gap.

## Demo presentation

Demo presentation contains examples of the addon's usage.