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

The list starts with the common properties, learn more about them by visiting the Modules description section. The other available properties are described below.

Property name	Description
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	Allows disabling the module so that the user is not able to interact with it.
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.
Group answers	Group answers allows defining the groups to which the given gaps will belong. Groups change the calculation of scores and maximum scores for gaps belonging to the group. Gaps that are in a group do not have their own scores (when the score and maximum score are calculated). If a correct answer is given to each gap in the group then the addon will get 1 point. Otherwise, the number of points will not increase. This property change data in ValueChanged event due to change in value of gap in group. To create a group, provide indexes (1-based indexes of gaps in text) in the following formats: Separated by comma: "1,2". In range: "1-3". Single number: "2". Mixed format: "1-3,5".

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
setGapText	index, text	Changes the text inside the gap
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.
ValueChanged event when gap not defined in Group answers property:

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

ValueChanged event when gap defined in Group answers property:

Field name	Description
Item	index - 1-based index of gap in module
Value	gap value
Score	"correct" for correct answer, "wrong" for wrong

The Text module sends additional ValueChanged event to Event Bus when a user changes the value of a gap in group and all gaps of this group are filled in.

Field name	Description
Item	Group index ("Group" + 1-based index of group answers)
Value	N/A
Score	1 for correct answers, 0 for wrong

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

Field name	Description
word	id of the definition

Audio added to addon has its own events.

The audio in Text addon sends ValueChanged type events to Event Bus when playing begins.

Field name	Description
Item	Current item
Value	playing
Score	N/A

When playback time changes, audio in Text addon sends a relevant event to Event Bus.

Field name	Description
Item	Current item
Value	Current time (in MM:SS format)
Score	N/A

The pause event occurs when the audio in Text addon is paused.

Field name	Description
Item	Current item
Value	pause
Score	N/A

When audio playback is finished, audio in Text addon sends OnEnd event to Event Bus.

Field name	Description
Item	Current item
Value	end
Score	N/A

Show Answers

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;
border-radius: 7px;
padding: 10px;
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;
padding-left: 19px;
border: 2px solid #009900;
}

2.3. Gap — wrong:
.ic_gap-wrong{
background-image: url('/file/serve/77022');
background-repeat: no-repeat;
padding-left: 19px;
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;
border-radius: 4px;
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;
border-radius: 4px;
background-color: #fff7b2;
border-radius: 4px;
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{
padding-left: 12px;
background-image: url('/file/serve/79016');
background-repeat: no-repeat;
}

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

Keyboard navigation

• 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.