Getting Started
Paragram enables you to embed high-fidelity, fully configurable 3D models into your website. Here you'll learn the basics of integrating the Paragram Viewer into your website.
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 build all of 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
andunselectOption
. - 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.
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/viewer" style="width:100%; height:100vh;"></iframe>
URL Parameters
You can customize the appearance of the iframe with the following URL parameters:
Parameter | Values | Description |
---|---|---|
uiLoader |
1 or 0 |
Enable or disable the default loading bar |
uiConfiguration |
1 or 0 |
Enable or disable the default configuration UI |
uiResetControls |
1 or 0 |
Enable or disable the default "reset controls" button |
uiAR |
1 or 0 |
Enable or disable the default "augmented reality" button |
Using the Viewer API
The Paragram Viewer API allows you to configure your 3D model programmatically using simple Javascript.
Add the Viewer API script tag to your HTML page
Include a <script>
tag referring to the Paragram Viewer API script. We recommend adding this element somewhere in the <body>
element of the page.
<script src="https://code.paragram.io/1.2.10/ParagramViewerAPI.js"></script>
Instantiate the Viewer API
Instantiate the ParagramViewerAPI
, passing in a query selector for your iframe element.
<script>
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();
});
Viewer API Reference
Methods
api.selectOption(optionGroupID, optionID)
Use this method to select an option. Typically you will call this method in the onchange
event of a checkbox or radio input on your webpage.
api.unselectOption(optionGroupID, optionID)
Use this method to unselect an option. This is only applicable to "select multiple" option groups. Typically you will call this method in the onchange
event of a checkbox input on your webpage.
api.transitionControls(controlsID)
Use this method to initiate a transition to a different camera controller.
api.resetControls()
Use this method to reset to the default camera view.
api.showSpatialUI()
Use this method to show spatial UI elements (e.g. annotations).
api.hideSpatialUI()
Use this method to hide spatial UI elements (e.g. annotations).
api.getImageDataURL(callback)
Use this method to generate a base64 encoded image. The returned image data is a JPEG with 80% quality.
Text Personalizations
api.setTextPersonalizationValue(optionGroupId, value)
Use this method to set the value of a text personalization.
api.setTextPersonalizationFont(optionGroupId, fontName)
Use this method to set the font family of a text personalization. fontName
must match a font enabled in your viewer.
api.setTextPersonalizationFontSize(optionGroupId, fontSize)
Use this method to set the font size of a text personalization. fontSize
must be a number representing pixels.
api.setTextPersonalizationTextAlign(optionGroupId, textAlign)
Use this method to set the horizontal alignment of a text personalization. Valid values are left
, right
, center
, start
, and end
.
api.setTextPersonalizationTextBaseline(optionGroupId, textBaseline)
Use this method to set the vertical alignment of a text personalization. Valid values are top
, bottom
, middle
, ideographic
, and hanging
.
Events
paragramViewerLoadingProgress
This event fires when loading progress changes. loadingProgress
is a value from 0 to 1.
window.addEventListener('paragramViewerLoadingProgress', (e) => {
console.log(e.detail.loadingProgress);
});
paragramViewerLoaded
This event fires when loading is complete.
window.addEventListener('paragramViewerLoaded', () => {
console.log('Paragram viewer loaded!');
});
paragramViewerControlsChanged
This event fires when the camera controller changes. This can be used, for example, to display a "reset controls" button when the user leaves the default camera view.
window.addEventListener('paragramViewerControlsChanged', (e) => {
console.log(e.detail.controlsIndex);
});
paragramViewerAnnotationSelected
This event fires when an annotation is selected. The optionGroupId
and optionId
associated with the annotation is provided in the event detail object.
window.addEventListener('paragramViewerAnnotationSelected', (e) => {
console.log(e.detail.optionGroupId, e.detail.optionId);
});
Using the Viewer UI
The Paragram Viewer UI is an optional script you can include that automatically builds a simple configuration UI in your webpage.
Add the Viewer UI script tag to your HTML page
Include a <script>
tag referring to the Paragram Viewer UI script. Be sure to include this after the Paragram Viewer API script.
<script src="https://code.paragram.io/1.2.10/ParagramViewerAPI.js"></script>
<script src="https://code.paragram.io/1.2.10/ParagramViewerUI.js"></script>
Instantiate the Viewer UI
Instantiate the ParagramViewerUI
, passing in a query selector for a container element as well as the ParagramViewerAPI
instance.
<script>
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>