Utility Functions

The module JSAV.utils includes some utility functions for working with HTML pages and visualizations.

JSAV.utils.getQueryParameter()

Returns an object containing all query parameters given for the HTML page. If no parameters exist, returns an empty object.

JSAV.utils.getQueryParameter(name)

Returns the value of the query parameter name. If no such parameter exists, return undefined

JSAV.utils.rand.numKey(min, max)

Returns a random integer number between min (inclusive) and max (exclusive).

JSAV.utils.rand.numKeys(min, max, num[, opts])

Returns an array of num random integer numbers between min (inclusive) and max (exclusive). Optional parameter opts is an object that can specify options:

• sorted If set to true, the array will be sorted.
• sortfunc If sorted is set to true, this option can be used to specify a function for sorting.
• test A function that takes the random array as a parameter and returns true/false indicating whether it fullfills some requirements. If it returns false, a new random array is generated. This is typically used with exercises to randomize and test the initial data.
• tries If test function is provided, this option specifies how many data sets are tested. If none of the first tries data sets pass the tests, the last one is returned.

JSAV.utils.rand.sample(arrayCollection, num[, opts])

Returns an array of num elements randomly picked from the given array arrayCollection. The optional parameter opts can specify options test and tries like for the numKeys function.

JSAV.utils.dialog(html, options)

Shows a pop-up dialog with the given HTML as content. Returns an object with function close() that can be used to close the dialog. Options can include:

• modal: whether the dialog is modal (default true)
• width (and min/maxWidth): control the width of the dialog
• height (and min/maxHeight): control the height of the dialog
• closeText: if specified, a button with this text to close the dialog will be added
• dialogClass: custom CSS classes to be added to the created component. Class jsavdialog is always added.
• title: title of the dialog
• dialogBase: the base element inside which the dialog will be created. Defaults to a newly created element ```<div class="jsavdialog"></div>”.
• dialogRootElement: The element into which the dialog element will be appended. By default, it will be appended at the end of the body element.

JSAV.utils.getInterpreter(languageJSON[, language])

Returns an interpreter function which translates tags into strings or other values specified in the selected language. languageJSON be either a JavaScript object or a URL to a JSON file, and can contain one or more translations. In case there are several translations language should specify the selected language. A simple translation JSON with two translations would look something like:

{
  "en": {
    "message": "Hello"
  },
  "fi": {
    "message": "Hei"
  }
}

The example above contains translations for English and Finnish. To create an interpreter function for English, language should be set to "en". The returned function will return "Hello" when called with the argument "message". Similarly the interpreter function returns "Hei" if language is set to "fi". Alternatively, different langauges can be placed in different files. In this case languageJSON could be a URL with the language tag {lang} that will be substituted with the value of language. For instance if the URL is "path/to/{lang}.json" and language is "en" the translation will be fetched from "path/to/en.json".

JSAV.utils.replaceLabels(string, replacementObject)

Returns a string where the labels (surrounded by curly brackets) in the string have been replaced by values in the replacementObject. The function works the same way as fill works for .umsg().

For instance if the string is "The value of x is {x}" and the object containing the replacements for the tag is {x: 7}, this function will return the string "The value of x is 7"

var str = "The value of x is {x}";
var replacement = {x: 7};
// the result will be "The value of x is 7"
var result = JSAV.utils.replaceLabels(str, replacement);

This function uses regular expressions to replace the tags. Therefore tags should not use numbers or special characters such as $ ^ . + - etc.

JSAV.utils.getUndoableFunction(jsav, func, undoFunc)

Returns an undoable/animatable function which will work with JSAV’s undo and recorded animation. The returned function can for instance be used to show or hide non-JSAV DOM element.

Arguments:

• jsav - The jsav instance with the exercise or animation.
• func - The function which performs the action. If the same function can be used to undo the performed action, it should return the undo arguments in an array.
• undoFunc - (OPTIONAL IF func RETURNS THE UNDO ARGUMENTS) The function which will undo the action performed by func.

// JSAV undoable functions for enabling and disabling jQuery buttons
var enableButton = JSAV.utils.getUndoableFunction(
  av,
  function (button) { button.attr("disabled", false); },
  function (button) { button.attr("disabled", true); }
);
var disableButton = JSAV.utils.getUndoableFunction(
  av,
  function (button) { button.attr("disabled", true); },
  function (button) { button.attr("disabled", false); }
);

// JSAV undoable function for changing html content of a jQuery object
var setHTML = JSAV.utils.getUndoableFunction(av,
  function ($object, html) {
    var oldHtml = $object.html();
    $object.html(html);
    // return arguments (for the same function) that will undo the action
    return [$object, oldHtml];
  }
);