DriveWorks Pro 16: How To: Pass Data from a Website to a Specification within an IFrame (KB18111901) [send feedback...]

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.

This is a feature that was made available in the main.cshtml file of the Specification Form Module in DriveWorks 16 SP1.

If you had customized this file prior to this service pack, please migrate your changes to the latest version installed with this (or a newer) service pack.

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.

Running DriveWorks Live through IIS

When the specification running in the IFrame is ran through IIS it is important to have Web Sockets enabled, see section 7. Enable Web Sockets for more information.

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).

Editing the Specification Form Module

For information on how to navigate to and apply the above settings please see Specification Form.

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.
Example Code in the Parent Web Page (Index.html for example)
<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"

Example showing the FaceMarkers parameter being dynamically driven
<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>
If a Default Project Name has been set in the Integration Module the project name is not required as a parameter.

If a different Project than that set in the Integration Module is required, or the Default Project Name does not have a value applied, the Project Name will be required as a parameter (line 9 in the example above).

For example, if the Default Project Name had not been set, or was not set to "MyProject" but that is what you are displaying in the IFrame, then the parameter string above would become:

"?Run=MyProject&FaceMarker=" + color

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.


Knowledge Base Article Ref:KB18111901

Table of Contents