# Macro Library virtmanip

Virtual Manipulatives
Functions for displaying and scoring virtual manipulatives.
Some of these can be used an exploration/calculation aid in a question without
being scored. Most have the ability to score the interaction with the manipulative.
When being scored, use the String question type. For most of these, you must
manually implement the scoring, usually by defining a wrong $answer, then changing
it to match the value from $stuanswers if the values are correct.
A typical pattern would look like:
loadlibrary("virtmanip")
$listener = vmgetlistener($thisq)
$stua = $stuanswers[$thisq]
$vm = vmsetupnumberline($stua,$thisq)
$showanswer = "Answers will vary"
$answer = "wrong".$stua
if ($stua != null) {
$scale,$val = vmnumberlinegetvals($stua)
$answer = $stua if ($val==$correctval)
}
Then $vm and $listener would get placed in the question text.
To hide the answerbox, wrap it in something like this:
<div style="position:absolute;left:0;right:0;visibility:hidden">$answerbox</div>
Ver 1.1 by David Lippman and Bill Meacham, May 2018

For VM writers, a variable called `$a11yqs` is defined and can be added to the query string passed to the VM. It defines three parameters: a11y_graph, a11y_graph, and a11y_mouse. For each, zero means use an alternative, non-zero means use the default.

- vmgetparam
- vmparamtoarray
- vmsetup
- vmgetlistener
- vmsetupchipmodel
- vmchipmodelgetcount
- vmsetupnumbertiles
- vmnumbertilesgetcount
- vmsetupitemsort
- vmitemsortgetcontainers
- vmsetupnumberlineaddition
- vmnumberlineadditiongetvals
- vmsetupnumberline
- vmnumberlinegetvals
- vmsetupnumberlineinterval
- vmnumberlineintervalgetvals
- vmsetupfractionline
- vmgetfractionlinevals
- vmsetupfractioncompare
- vmgetfractioncompareval
- vmsetupfractionmult
- vmgetfractionmultvals
- vmdrawinchruler
- vmdrawcmruler
- vmdrawclock

### vmsetup

vmsetup(vm name, parameters, width, height, question number, [part number])

Sets up a virtual manipulative iframe

- vm name is the name of a VM on the OERVM AWS site, or a URL to another VM
- parameters is an associative arrays of parameters to be passed to the VM in the query string
- width, height are the width and height of the iframe
- qn: use $thisq
- part: if a multipart or conditional question, put the part index.

### vmgetparam

vmgetparam(parameter string, parameter name)

Extracts one parameter value from a parameter string, where the parameter string is of the form `"name1:value1,name2:value2,name3:value3"`.

Returns the value if found, or FALSE if not found

### vmparamtoarray

vmparamtoarray(parameter string)

Converts a parameter string of the form of the form `"name1:value1,name2:value2,name3:value3"` into an associative array. For example, the above would be converted into an array where `$a["name1"]` would be `value1`.

### vmgetlistener

vmgetlistener(qn,[part])

Generates a listener to receive values from virtual manipulatives. This needs to be generated and included in the question text if the manipulative is to be scored

NOTE: You can avoid needing to use this function by having the manipulative send its postMessage in thise format:

    message = {
      subject: "imathas.update",
      "qn": qn,
      "value": datatostore
    };
    window.parent.postMessage(JSON.stringify(message), "*");

When using this format, be sure to pass the question number to the manipulative in the query string. `qn` should be `$thisq-1` for single-part questions, or `1000*$thisq + (part index)` for multi-part.

### vmsetupchipmodel

vmsetupchipmodel(stuans,qn,[part])
Set up a chip model manipulative

### vmchipmodelgetcount

vmchipmodelgetcount(stuans)
return an array array(poscount,negcount) of the count of positive and
negative chips in the drop region.

### vmsetupnumbertiles

vmsetupnumbertiles(stuans,qn,[part])
Set up a number tiles manipulative

### vmnumbertilesgetcount

vmnumbertilesgetcount(stuans)
return an array array(hundredcount,tencount,onecount) of the count of
hundred blocks, ten blocks, and ones blocks in the drop area

### vmsetupitemsort

vmsetupitemsort(tosort,cats,stuans,qn,[part,width])
Set up an item sort manipulative, where students sort items into 2 categories
tosort = array of items to sort
cats = array of titles for the two drop areas
stuans = use $stuanswers[$thisq] or $stuanswers[$thisq][partn]
qn: use $thisq
part: if a multipart or conditional question, put the part index. Can put null if not multipart
width: width of each container. Default 150px.

### vmitemsortgetcontainers

vmitemsortgetcontainers(stuans, tosort)
tosort = array of items to sort
returns an array of container values
out[i] gives the container that item tosort[i] was sorted into
out[i] = -1 means unsorted; = 0 is first container, = 1 is second container

### vmsetupnumberlineaddition

vmsetupnumberlineaddition(stuans,qn,[part])
Set up a number line addition manipulative

### vmnumberlineadditiongetvals

vmnumberlineadditiongetvals(stuans)
return array(value of first dot, value of sum)

### vmsetupnumberline

vmsetupnumberline(stuans,qn,[part,snap])
Set up a number line manipulative, with a changeable scale
set snap="false" to allow values in between grid markers
to set snap without setting part, use null for part

### vmnumberlinegetvals

vmnumberlinegetvals(stuans)
return array(scale, value of dot)

### vmsetupnumberlineinterval

vmsetupnumberlineinterval(stuans,qn,[part])
Set up a number line interval manipulative, with a changeable scale

### vmnumberlineintervalgetvals

vmnumberlineintervalgetvals(stuans)
return array(scale, left endpoint value, right endpoint value, left type, right type)
types are 1 = arrow, 2 = paren, 3 = square bracket, 4 = none

### vmsetupfractionline

vmsetupfractionline([stuans,qn,part])
Set up a fraction number line manipulative, with a single line

### vmgetfractionlinevals

vmgetfractionlineval(stuans)
return array(numerator, denominator)

### vmsetupfractioncompare

vmsetupfractioncompare([stuans,qn,part])
Set up a fraction number line comparison manipulative, with two lines

### vmgetfractioncompareval

vmgetfractioncompareval(stuans)
return array(numerator, denominator)

### vmsetupfractionmult

vmsetupfractionmult([stuans,qn,part])
Set up a fraction multiplication manipulative, with a single line

### vmgetfractionmultvals

vmgetfractionmultvals(stuans)
return array(horiz numerator, horiz denominator, vert num, vert denom)

### vmdrawinchruler

vmdrawinchruler([max,val,width,height])
Draws an inch ruler, divided into sixteenths, up to the max value (default 4). If specified, will draw an arrow at val (give as numeric/decimal value).

### vmdrawcmruler

vmdrawcmruler([max,val,width,height])
Draws an centimeter ruler, divided into mm, up to the max value (default 4). If specified, will draw an arrow at val (give as numeric/decimal value).

### vmdrawclock

vmdrawclock(hr,min,[size])
Draws an analog clock with hands pointing to the specific hr and min.