Torx Design-Analyze Webframe Helper

Outline

Web pages and applications can be embedded within Torx Design-Analyze through a configurable webframe plugin. Embedded applications can exchange data with Torx Design-Analyze through a secure messaging channel within the browser. This helper library is designed to make it easy to connect an application embedded within a Torx Design-Analyze webframe to the parent Torx Design-Analyze application, and exchange data between the applications.

Usage

Builds

There are two builds of the library available:

IIFE build

The IIFE build is in the dist folder of this repository, and can be included in a webpage in a script tag, loading txda-webframe-helper.min.js:

<script src="path/to/txda-webframe-helper.min.js"></script>

As an alternative to hosting the script, it can be loaded from a CDN, for example:

<script
 src="https://cdn.jsdelivr.net/gh/torx-software/txda-webframe-helper@0246699/dist/txda-webframe-helper.min.js"
 integrity="sha384-Lm7cXXN8qC7E77e1aYvw9T15+cqTQxsOj5P/VEYVIBRqgaeVt6Ylhv5vij4crTnw"
 crossorigin="anonymous">
</script>

The above example references a specific commit. To update to a new version, replace the @d008f3c with the version (commit, or release tag) that you wish to use. The subresource integrity hash will need to be updated.

When loaded, the script provides a window global object txdaWebframeHelper. See the section below for usage.

An example can be found in the source of the demonstration page.

ES module build

The ES module build is in the esm folder of this repository, and can be used when integrating with a bundled application using ES6+ modules. To use the ESM build, install the package from GitHub, replacing the #commit-hash at the end of the URI with the desired version:

NPM:

npm install --save git+https://github.com/torx-software/txda-webframe-helper.git#d008f3c

Yarn:

yarn add git+https://github.com/torx-software/txda-webframe-helper.git#d008f3c

Or the repository can be added directly to a package.json, followed by npm install or yarn:

  "dependencies": {
    "txda-webframe-helper": "git+https://github.com/torx-software/txda-webframe-helper.git#d008f3c"
  }

The ES module build is shipped with TypeScript declaration files, which provides type safety if your project uses TypeScript, and autocompletion in TypeScript and JavaScript projects in supported text editors such as Visual Studio Code.

See the section below for usage.

Establishing a connection to Torx Design-Analyze

A single function, initialize, is provided to initiate a connection with Torx Design-Analyze:

IIFE build: available as window.txdaWebframeHelper.initialize
ES module build: importable with import { initialize } from 'txda-webframe-helper/esm'

initialize returns a Promise that resolves to a TXDAConnection object. TXDAConnection can be used to set up event listeners for incoming data, and call methods to send requests to Torx Design-Analyze. Full details of supported listeners and methods are available in the documentation. See the example demonstration page for a worked example.

Embedding in Torx Design-Analyze

To configure your application to be embedded in an iframe in Torx Design-Analyze, add a webframe plugin configuration in the Control Panel with the following configuration:

{
  "url": "https://your-service.com",
  "messagingEnabled": true
}

Required security practices when embedding

Services embedded in Torx Design-Analyze must be served over HTTPS, as this is a browser requirement to prevent loading mixed active content. Depending on the browser, localhost may be an exception during development.
Pages embedded in Torx Design-Analyze should have a frame-ancestors Content Security Policy (CSP) header set to only allow embedding in the desired Torx Design-Analyze install. This header ensures that the page cannot be embedded in another page impersonating a Torx Design-Analyze install.

Demo

A publicly available example page is available to show an example of integration. The source code for this example page is available on GitHub. No data are transferred outside of the example page, neverless use of this demonstration integration is not recommended or supported in use with production data and no security assumptions should be made when using it.

To configure in Torx Design-Analyze, add a webframe plugin configuration in the Control Panel with the following configuration:

{
  "url": "https://torx-software.github.io/txda-webframe-helper",
  "messagingEnabled": true
}

Documentation

Full TypeScript documentation for this helper library is available on GitHub pages.