Getting Started

Paragram enables you to embed high-fidelity, fully configurable 3D models into your website. Here you'll learn the basics of integrating Paragram into your website once you've received the URL for your Paragram Viewer.

What is the Paragram Viewer?

The Paragram Viewer is simply an HTML iframe that acts as a window into your 3D scene. The Viewer handles all of the cross-platform user interaction such as rotating and zooming, and can also be interacted with via our client-side APIs.

How Does Configuration Work?

We use custom internal tools to build the logic that defines how your 3D model can be configured - whether that's showing/hiding parts of the model, changing materials or even enabling/disabling options based on advanced rules. Once the configuration has been set up, our client-side APIs can be used to configure the 3D model in a simple and intuitive way.

Client-Side APIs

Our client-side APIs allow you to interact with and configure your 3D model using simple Javascript.

• Viewer API - The Paragram Viewer API allows you to configure your 3D model programmatically with methods such as selectOption and unselectOption.
• Viewer UI - The Paragram Viewer UI allows you to configure your 3D model visually by automatically building a user interface and placing it within your webpage. This user interface can also be placed inside the iframe upon request.

Embedding the Paragram Viewer

You can embed the Paragram Viewer anywhere that supports an HTML iframe. The Viewer will automatically fill the iframe responsively, so be sure to define its width and height.

<iframe src="path/to/your/iframe.html" style="width:100%; height:100vh;"></iframe>

Using the Paragram Viewer API

The Paragram Viewer API allows you to configure your 3D model programmatically using simple Javascript.

Instantiate the Viewer API

Import the ParagramViewerAPI module and instanstiate it, passing in a query selector for your iframe element.

<script type="module">
  import { ParagramViewerAPI } from 'path/to/ParagramViewerAPI.js';
  const api = new ParagramViewerAPI('#viewerFrame');
</script>
          
<iframe id="viewerFrame" src="path/to/your/iframe.html"></iframe>

Configure the 3D Model

Use the selectOption and unselectOption methods to configure the 3D model.

api.selectOption('someOptionGroupID', 'someOptionID');
api.unselectOption('someOptionGroupID', 'someOptionID'); // only necessary for "select multiple" fields

Listen to Viewer Events

The Paragram Viewer API triggers custom events such as paragramViewerLoaded and paragramViewerStateChanged that can be useful for performing actions when the Viewer is finished loading or the configuration state has changed.

window.addEventListener('paragramViewerLoaded', function() {
  document.querySelector('#customLoadingSpinner').remove();
});

Using the Paragram Viewer UI

The Paragram Viewer UI allows you to configure your 3D model visually by automatically building a user interface and placing it within your webpage. This user interface can also be placed inside the iframe upon request.

Instantiate the Viewer UI

Import the ParagramViewerUI module and instanstiate it, passing in a query selector for a container element as well as the ParagramViewerAPI instance.

<script type="module">
  import { ParagramViewerAPI } from 'path/to/ParagramViewerAPI.js';
  import { ParagramViewerUI } from 'path/to/ParagramViewerUI.js';
  const api = new ParagramViewerAPI('#viewerFrame');
  const ui = new ParagramViewerUI('#paragramUIContainer', api);
</script>

<iframe id="viewerFrame" src="path/to/your/iframe.html"></iframe>
<div id="paragramUIContainer"></div>