Skip to content

Embedded Component API

Jump to bottom Edit New page
Geoffrey Kwan edited this page Jul 25, 2018 · 8 revisions

Table of Contents

How does an embedded model send a message to WISE?

An embedded Javascript model uses the iframe window.postMessage() function to send data to WISE. Here's an example of how the model would send a message to WISE. 

  let message = {
    "messageType": "studentWork",
    "studentData": {
      "yourModelData1": "abc",
      "yourModelData2": 123
    }
  }
  window.postMessage(message, "*");

What types of messages can an embedded model send to WISE?

Message Type Description
studentDataChanged The student data in the model has changed and the model is sending the student data to WISE so that it can be saved. This student data will be saved when WISE auto saves. Use this way of saving student data if you don't need complete control of how often student data is saved.
studentWork The model is sending student work to WISE so that it can be saved. This student data will be saved immediately. This has the option to overwrite existing saved data. Use this way of saving student data if you want complete control of how often student data is saved.
event An event has occurred in the model and the model is sending the event to WISE so that it can be saved. This event will be saved immediately.
applicationInitialized The model is telling WISE that the model is done initializing.
getParameters The model is requesting the parameters that have been authored into this WISE embedded component.
componentDirty The model is notifying WISE that it has unsaved student work.
componentSubmitDirty The model is notifying WISE that it has unsubmitted student work.
getStudentWork The model is requesting student work from WISE. The model can request student work from any step and any component.
getLatestStudentWork The model is requesting the latest student work saved for this model.

How does an embedded model receive a message from WISE?

An embedded model must listen for the message event on the window. Here's an example of how an embedded model would listen for messages from WISE. 

  window.addEventListener('message', function(message) {
      let messageData = message.data;
      let messageType = messageData.messageType;
      if (messageType == 'studentWork') {
        let studentWorkFromThisNode = messageData.studentWorkFromThisNode;
        let studentWorkFromOtherComponents = messageData.studentWorkFromOtherComponents;
      } else if (messageType == 'latestStudentWork') {
        let componentState = messageData.componentState;
      } else if (messageType == 'parameters') {
        let parameters = messageData.parameters;
      } else if (messageType == 'componentStateSaved') {
        let componentState = messageData.componentState;
      } else if (messageType == 'siblingComponentStudentDataChanged') {
        let componentState = messageData.componentState;
      } else if (messageType == 'handleConnectedComponentStudentDataChanged') {
        let componentState = messageData.componentState;
      } else if (messageType == 'componentState') {
        let componentState = messageData.componentState;
      }
  });

What types of messages can an embedded model receive from WISE?

Message Type Description
studentWork WISE is sending student work to the model. This is the response to the "getStudentWork" message that the model has sent to WISE. The student work can be from any step and any component.
latestStudentWork WISE is sending the latest student work to the model. This is the response to the "getLatestStudentWork" message that the model has sent to WISE.
parameters WISE is sending the parameters to the model. This is a response to the "getParameters" message that the model has sent to WISE.
componentStateSaved WISE is sending a confirmation that the model student work has been saved.
componentState WISE is sending the latest student work to the model. This is automatically sent when the component is loaded.
handleConnectedComponentStudentDataChanged The embedded component has a connected component. The student work in a connected component has changed in WISE so WISE is sending the connected component student work to the model.
siblingComponentStudentDataChanged The student work in the same step but a different component has changed in WISE so WISE is sending that student work to the model.

How can an embedded model receive data from other components in real time?

An embedded model can listen for student work in real time from other components in the same step by using the connected component functionality. When the work from the other component changes, the work is sent to the embedded model component using a handleConnectedComponentStudentDataChanged message.

Here's an example of an embedded component that listens for work from another component. 

  {
    "id": "4w57lrheto",
    "type": "Embedded",
    "url": "yourmodel.html",
    "connectedComponents": [
        {
            "nodeId": "node81",
            "componentId": "pxefj7534v",
            "type": "importWork"
        }
    ]
  }

How can an embedded model send data to other components in real time?

Other component types can listen for student work in real time from the embedded model component in the same step by using the connected component functionality. When the work from the embedded model component changes, the work is sent to the other component.

Here's an example of a graph component that listens for work from the embedded model component. 

  {
    "id": "pxefj7534v",
    "type": "Graph",
    "connectedComponents": [
        {
            "nodeId": "node81",
            "componentId": "4w57lrheto",
            "type": "importWork"
        }
    ]
  }

How do parameters work?

The author of the embedded component can specify parameters that will be passed to the model. This allows the author to use a single model file in multiple places in the WISE project, each with a different configuration.

For example, if your embedded component in WISE was authored like this 

  {
    "id": "4w57lrheto",
    "type": "Embedded",
    "url": "yourmodel.html",
    "parameters": {
      "yourModelParameter1": "abc",
      "yourModelParameter2": 123
    }
  }

Then when your model requests the parameters, it would receive an object like this 

  {
    "nodeId": "node8",
    "componentId": "4w57lrheto",
    "yourModelParameter1": "abc",
    "yourModelParameter2": 123
  }

Then imagine you wanted to reuse the model but with a different configuration, then you would author another embedded component like this using the same model but different parameters 

  {
    "id": "d2klzb57ep",
    "type": "Embedded",
    "url": "yourmodel.html",
    "parameters": {
      "yourModelParameter1": "def",
      "yourModelParameter2": 456
    }
  }

Can I use GET URL parameters with the embedded component?

Yes, you can use GET URL parameters with embedded models since we use an iframe to render the model. This is an alternative to using the parameters mentioned above. The GET URL method of sending parameters may actually be easier for authors.

This is an example of what the embedded component would look like with GET URL parameters. 

  {
    "id": "d2klzb57ep",
    "type": "Embedded",
    "url": "yourmodel.html?yourModelParameter1=def&yourModelParameter2=456"
  }
Add a custom footer
Add a custom sidebar
Clone this wiki locally