DriveWorks Pro 22

How To: Pass Data from a Website to a Specification within an IFrame (KB18111901)

How To: Pass Data from a Website to a Specification within an IFrame

DriveWorks can be placed in an IFrame, in an existing website, and data can be passed to it through the Integration Module.

Data is passed to the IFrame through a URL. However, this does have some limitations:

• Changing the URL arguments will cause the IFrame to fully refresh
• Anyone can pass data to the IFrame with it embedded in their website

These limitations are solved by the implementation of postMessage in the Specification Form Module.

The image below shows an example of a website (area within the red border) that uses an IFrame (area within the blue border) to push data to a running specification.

Here the running specification contains a 3D Preview control only.

The data being pushed to the specification (Strap Color, Case Material, Face Markers, etc.) will update the 3D file in the running specification.

Implementing this does require code to be written on the web page hosting the IFrame. Example code is given later in this topic.

Underlying Technology

DriveWorks utilizes postMessage which allows safe communication between a parent web page and DriveWorks Live.

The page in the IFrame (the DriveWorks Live specification) listens for a message event.

Once received from the expected URL (the site hosting the IFrame) it will send the data it received to the Integration Module, using the session data available to the window within the IFrame.

Implementing Parent to Child Web Page Communication

1. Specification Form Module

The Specification Form module is required to have the following settings applied:

• Integration Module Page

  This is the relative path or full URL of the integration module to pass parameters to.

  If the value of this setting does not begin with http:// or https://, then DriveWorks will treat this as a relative value, and automatically resolve it.

  So, if DriveWorks Live is running at:

  http://driveworkslive.mydomain.com

  and the value /Integration is passed, this will automatically become:

  http://driveworkslive.mydomain.com/Integration

  Using the same example, any of the three following values would also be resolved:

  • /Integration
  • ~/Integration
  • Integration
• Expected Origin URL

  This is the URL of the parent site hosting the specification in the IFrame, as this is what should be sending the postMessage events to the running Specification.

  If this does not match the site that is sending the messages, then nothing will happen to the specification.

  This prevents unauthorized domains from seeing the response data that comes back from communicating with the specification (if a call into the code from outside the trusted domain was made).

2. Code Example in the Parent Web Page

This is the part where a little bit of code is required to be written in the web page where the IFrame will be hosted.

The example code below is a very simple html web page, that contains:

• An IFrame pointing at a DriveWorks project
• Some basic JavaScript containing a single function.

<iframe id="MyFrame" height="1000" width="1500" src="http://driveworkslive.mydomain.com/Apps/MyProject" ></iframe>

<script>

	// The params element below should be replaced with the parameters to be driven - see below for examples

function sendIntegrationParams(params) {

	// MyFrame below must be the same name declared in the iframe id above

var iFrame = document.getElementById("MyFrame").contentWindow;

	// The second parameter below must be the URL where the content of the IFrame is hosted

iFrame.postMessage(params, "http://driveworkslive.mydomain.com");
	}

</script>

Further explanation of the tags and elements used in the code above are given below:

The <iframe> tag (line 1)

This tag includes the following elements:

• id

  This is any name used to identify the IFrame. This is also given in the getElementById value.

  For example: id="MyFrame"

• height

  This is the required height for the IFrame.

  For example: height="1000"

• width

  This is the required width for the IFrame.

  For example: width="1500"

• src

  This is the URL to the project to be run as a specification.

  For example: http://driveworkslive.mydomain.com/Apps/MyProject

The (params) element (line 4)

The word params should be replaced with all the parameters that are required to be driven.

The param string is made up of the following:

• The string should begin with a ?
• each parameter be separated with &
• Use = after a parameter name to declare the value to be passed into it
• the entire string enclosed in quotes " "

For example: "?StrapColor=Green&CaseMaterial=Steel&FaceMarkers=Light"

<iframe id="MyFrame" height="1000" width="1500"></iframe>

<button id="Light">Light</button>
<button id="Dark">Dark</button>
 
// There is some JavaScript on that page that adds event handlers to the buttons: 
<script>

// Set a default color value
var defaultColor = "Light"; 

// Set the src of the IFrame to run our project via the Integration Module so we can pass in an initial value dynamically
document.getElementById("MyFrame").src = "http://driveworkslive.mydomain.com/integration?FaceMarker=" + defaultColor;

// Get hold of all of the color buttons
var LightButton = document.getElementById("Light");
var DarkButton = document.getElementById("Dark");
 
// Put the FaceMarker buttons in an array
var buttons = [LightButton, DarkButton];
 
// Loop over all of the buttons
buttons.forEach(function(button) {
 
  // Add a click event handler to the button
  button.addEventListener("click", function(e) {
 
    // Get hold of the id of the button to get the name of the color
    var color = e.target.id;
     
    // Send the new color to the IFrame to be applied to the running spec
    sendIntegrationParams("?FaceMarker=" + color);
  });
});

</script>

The getElementById value (line 6)

The value "MyFrame" should be replaced with the name decalred in the id element of the iframe tag above.

The postMessage URL (line 8)

This must be the URL of where the content of the IFrame is hosted.

For example: "http://driveworkslive.mydomain.com"

If you have followed the above and your setting for the Expected Origin URL in the Specification form module matches the origin of the message being sent, then everything should work as expected.