simcapi
v3.1.0
Published
Allows the communication between the HTMLViewer and the Sims.
Downloads
8
Readme
SimCapi
SimCapi is an interface used by simulations to communicate between AELP (Smart Sparrow's Adaptive eLearning Platform) and the Simulation (Sim).
Why?
Educators and Learning Designers are generally looking to do two things with a sim;
- Set it up in a specific way for a specific question (eg. disable certain controls or pre-fill certain fields), and
- Determine what the student has done in the sim so they can provide appropriate feedback.
SimCapi allows you to make both these things happen. In other words, by including SimCapi in your simulation, you can allow AELP (and therefore the teacher) to control the sim.
How?
The first half of SimCapi is the CapiModel
. You can create variables on this data object which notify other objects whenever they've been changed.
The second half of SimCapi is the CapiAdapter
, which is responsible for exposing variables on a CapiModel
to AELP.
Together, a connection is created between AELP and the model where the variables are keep in sync.
In this way, a teacher can set an initial condition via AELP which will be sent through to the simulation. On the flip side, when a student uses the sim, the sim can report changes back to the AELP.
Backbone
For those who use Backbone.js. It's possible to use Backbone Models instead of CapiModels. SimCapi also supplies a BackboneAdapter
.
Installation
AMD compatible or use the following script tag:
<script src='https://lib.smartsparrow.com/simcapi-js-3.1.0.min.js'></script>
How to setup
There are three phases to setup SimCapi, setup data, expose data and finalise setup.
Setup Data
In the setup data phase, you just have to create a CapiModel
.
For example:
var simModel = new simcapi.CapiAdapter.CapiModel({
demoMode: true,
studentResponse: '5',
simEnabled: true
});
This CapiModel
has two variables inside it that can be exposed to AELP.
Expose Data
In this phase, you must tell the CapiAdapter
what you want to expose from the CapiModel
.
simcapi.CapiAdapter.expose(variableName, model, options);
Here is the list of what you must pass to expose.
- variableName - String - name of the variable on the model
- model - CapiModel - the model that the variable belongs to.
- options - Object
- type - SimCapiValue.TYPES - the type of the variable. By default, simcapi will detect the type of the variable.
- alias - String - nickname of the variable that is only shown via AELP. Having '.' in the nickname will group variables that have the same prefix.
- readonly - Boolean - if the variable is read-only
- writeonly - Boolean - if the variable is write-only
Inversely, if you want to unexpose your data, you can tell the CapiAdapter
.
simcapi.CapiAdapter.unexpose(variableName, model);
Here is the list of what you must pass to unexpose.
- variableName - String - name of the variable on the model
- model - CapiModel - the model that the variable belongs to.
Finalise Setup
This phase require you to tell SimCapi you have finished setting up the Capimodel
. This is with the command below:
simcapi.Transporter.notifyOnReady();
This must be called when the model has finished being setup. It is to tell SimCapi that the CapiModel
is ready to sync with the AELP. If this is not called, AELP will not sync to the CapiModel
because it thinks the CapiModel
is not ready.
Usage
Transporter
Apart from syncing, there may be other functionality that can be used via the Transporter
.
To be notified when the initial Capi snapshot has been applied, use addInitialSetupCompleteListener
with a callback function. This must be set before notifyOnReady
is called.
simcapi.Transporter.addInitialSetupCompleteListener(function() {
//Do something after initial snapshot is available
});
Check events
Sims can have the ability to trigger check
events the same way when a student clicks on the check
button on AELP.
simcapi.Transporter.triggerCheck();
The above code will click check
on behave of the user when they interact with a sim in a certain way.
It is also possible to pass a callback function to the triggerCheck
that will be executed when the feedback panel is closed.
simcapi.Transporter.triggerCheck({
complete: function(){
//Do something when feedback panel is closed.
}
});
Check events can also be trigger external to your sim, and you can respond to these by using addCheckStartListener
and addCheckCompleteListener
simcapi.Transporter.addCheckStartListener(function() {
//Do something when Check event starts
});
simcapi.Transporter.addCheckCompleteListener(function() {
//Do something when Check event ends
});
Persisting data
There is also the ability to persist student's data between lessons, by using setDataRequest
function onSuccess(response) {
var key = response.key
var value = response.value
//Do something when data is successfully stored
}
function onError(error) {
//Do something when request fails
}
var simId = 'yourSim';
var key = 'some data key';
var value = 'data you want to store';
simcapi.Transporter.setDataRequest(simId, key, value, onSuccess, onError);
To retrieve the stored data, use getDataRequest
. If you are polling for data changes, please be aware of how many users will be using your sim when setting your polling duration.
function onSuccess(response) {
var keyExists = response.exists;
var key = response.key
var value = response.value
//Do something
}
function onError(error) {
//Do something when request fails
}
var simId = 'yourSim';
var key = 'some data key';
simcapi.Transporter.getDataRequest(simId, key, onSuccess, onError);
Sim Context
Sims may run in different contexts, such as a when when an instructor is configuring the sim, as to when a student is viewing the sim. A sim can discern its context by the property simcapi.Transporter.getConfig().context
, where the value will be one of:
- VIEWER, sim is either being used by the student or previewed by an instructor
- REVIEW, sim is being viewed by a student on a historical screen
- AUTHOR, sim is being used by the instructor in an authoring environment
- REPORT, sim is being used to report previous input from a student
A simple example
var simModel = new simcapi.CapiAdapter.CapiModel({
demoMode: true,
studentResponse: '5',
simEnabled: true
});
...
simcapi.CapiAdapter.expose('demoMode', simModel,
{readonly: false});
simcapi.CapiAdapter.expose('studentResponse', simModel,
{alias: 'studentAnswer',
readonly: true});
simcapi.CapiAdapter.expose('simEnabled', simModel,
{writeonly: true});
...
simcapi.Transporter.notifyOnReady();
For SimCapi to work, you must use the following functions on the CapiModel
:
Get
To retrieve a variable from a CapiModel
.
For example:
var value = simModel.get('demoMode');
Set
To set a variable to the CapiModel
.
For example:
simModel.set('demoMode', false);
On
To listen to changes to a variable that were sent from the AELP or changed in the simulation.
For example:
simModel.on('change:demoMode', function(){
var changedValue = simModel.get('demoMode');
});
That function will be called everytime demoMode changes.
Has
Checks to see if a variable with the given name exists in the CapiModel
var returnsTrue = simModel.has('demoMode')
A backbone example
var SimModel = Backbone.Model.extend({
defaults:{
demoMode: true,
studentResponse: '5',
simEnabled: true
}
});
var simModel = new SimModel();
...
simcapi.BackboneAdapter.expose('demoMode', simModel,
{readonly: false});
simcapi.BackboneAdapter.expose('studentResponse', simModel,
{alias: 'studentAnswer',
readonly: true});
simcapi.CapiAdapter.expose('simEnabled', simModel,
{writeonly: true});
...
simcapi.Transporter.notifyOnReady();
AllowedValues
It's possible for SimCapi to supply the teacher with a choice of options for a particular property on a sim if it is possible.
For example, you have a capi property named color and depending whether the teacher inputs the strings 'red', 'blue', or 'green', the background will change to that color.
Getting the teacher to type up the color may cause issues like spelling mistakes or the teacher not knowing what the valid values are.
Simple Example
var simModel = new simcapi.CapiAdapter.CapiModel({
color: 'red'
});
simcapi.CapiAdapter.expose('color', simModel, {allowedValues: ['red', 'blue', 'green']});
...
simcapi.Transporter.notifyOnReady();
Note that using this will always return a string, even if you say the allowed values to be numbers.
Dynamic Capi
It is possible to expose more capi properties depending on a change of another capi property.
For example, you have a capi property named numberOfColors. For each color, you want more capi properties to appear for name and red, green and blue properties. So 4 capi properties will be exposed for the numberOfColors that the teacher sets.
Simple Example
var simModel = new simcapi.CapiAdapter.CapiModel({
numberOfColors: 0
});
simcapi.CapiAdapter.expose('numberOfColors', simModel);
simModel.on('change:numberOfColors', function(m, attributes){
for(var i = 0; i< attributes.numberOfColors; ++i){
createProperty('color'+i+'Name', '');
createProperty('color'+i+'Red', 0);
createProperty('color'+i+'Green', 0);
createProperty('color'+i+'Blue', 0);
}
});
function createProperty(name, defaultValue){
simModel.set(name, defaultValue);
simcapi.CapiAdapter.expose(name, simModel);
}
...
simcapi.Transporter.notifyOnReady();
Take note that when numberOfColors change, we create the variables on the model and expose those values via Simcapi.