Launching a Configurator

In this section we build a simple HTLM page that contains a minimal configurator that is handled by the paramate JavaScript API. This is done in the following steps:

At the end the complete minimal example is show.

In order to launch a paramate configurator, a configurable model must to be present on the paramate cloud platform (todo: link). We assume this to be the case here (todo: prepare a valid example).

Many steps allow to further modify the behavior of the configurator, e.g. by adding user events. The reference sections contain more information about that.

Adding the paramate JavaScript API to your web page

Each of the five modules of the API is contained in a single JavaScript library file that can either be downloaded or included from the paramate hosted source. In addition one css file is available for beeing using in combination with the viewport libraries.

Downloading the API

The paramate API is hosted as pre-built files on paramate. It is also hosted on npm (todo: add link) from where it can be downloaded and built.

Including hosted version of the API

In addition, the JavaScript files are also hosted on paramate from where they can be included directly into the HTML file:

Example

<head>
<link rel="stylesheet" type="text/css" href="https://libs.paramate.trinckle.com/paramateViewport-latest.css">
<script src="https://libs.paramate.trinckle.com/paramateConfigurator-latest.js"></script>
<script src="https://libs.paramate.trinckle.com/paramateControlsAuto-latest.js"></script>
<script src="https://libs.paramate.trinckle.com/paramateViewport-latest.js"></script>
</head>

Note

Please consider that using the ending "-latest" will load the latest version of the libraries and css files. This may require adjustments on the HTML page when some definitions are changed in a later version. To avoid incompatibility, there are the also the latest versions of each major version always available with names like "paramateConfigurator-1.latest.js". It is recommended to use this with the major version used when developing the application rather than the simple "-latest" ending, thus avoiding incompatibilities in the future.

Setting Up the Configurator

A paramate configurator is started by creating a new configurator object via its constructor. The information that need to be provided are at least the URL of the paramate API hub, the configurator ID, the API key and, if the configurator is handled in a secure mode, a proxy URL:

Example

var configurator = new Paramate.Configurator({
  APIHub: 'https://api.paramate.trinckle.com',
  APIKey: '64c82bb593e5a2b9af693a603200e57e',
  configuratorId: 'c50e355f-93ee-46df-a1dd-1f66a7cc40d1'
});

Setting Up the Viewport

In order to create a new viewport, an empty HTML host container that can be addressed by id must be present in the current document to accommodate the viewport element. You should also give it some width and height to actually get a usable viewport.

Calling the viewport constructor creates the viewport. The attributes that are non-optional are the configurator object and the host container:

Example

<body>
<div id="viewPort" style="width: 200px; height: 200px;"></div>
...
</body>
<script>
...
var viewPort = new Paramate.Viewport({
  configurator: configurator,
  viewportElement: document.getElementById('viewPort')
});
</script>

Setting Up the Controls

Like for the configurator and the viewport, the controls are set up by calling the respective constructor. One can choose between the constructor for auto-generated controls and the constructor for manually generated controls. Here we use auto-controls since we want to keep the example code small.

The auto-controls constructor takes two mandatory arguments: the configurator object and the ID of an empty HTML element that acts as host container for the auto-generated HTML control elements.

Example

<body>
<div id="controls"></div>
...
</body>
<script>
...
var controls = new Paramate.ControlsAuto({
  configurator: configurator,
  containerElement: document.getElementById('controls')
});
</script>

For more information about controls hav a look at the section about controls.

Registering the Viewport and the Controls

At this point is is required that the configurator object learns about the viewport object and the controls object:

Example

configurator.viewPort = viewPort;
configurator.controls = controls;

Start the Configurator

Now its time to start the configurator:

Example

configurator.initialize();

Full Minimal Example

If we assemble all the steps, we come up with the following minimal example of a paramate configurator. Note that the JavaScript functions are executed after the page has loaded.

Example

<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Example paramate Configurator</title>
<link rel="stylesheet" type="text/css" href="https://libs.paramate.trinckle.com/paramateViewport-latest.css">
<script src="https://libs.paramate.trinckle.com/paramateConfigurator-latest.js"></script>
<script src="https://libs.paramate.trinckle.com/paramateControlsAuto-latest.js"></script>
<script src="https://libs.paramate.trinckle.com/paramateViewport-latest.js"></script>
</head>
<body>
<div id="viewport" style="width: 200px; height: 200px;"></div>
<div id="controls"></div>
<script>
var configurator;
var viewport;
var controls;

window.onload = function(){

  // Create configurator object
  configurator = new Paramate.Configurator({
    APIHub: 'https://api.paramate.trinckle.com',
    APIKey: '64c82bb593e5a2b9af693a603200e57e',
    configuratorId: 'c50e355f-93ee-46df-a1dd-1f66a7cc40d1'
  });

  // Create viewport object
  viewport = new Paramate.Viewport({
    configurator: configurator,
    viewportElement: document.getElementById('viewport')
  });

  // Create controls object
  controls = new Paramate.ControlsAuto({
    configurator: configurator,
    containerElement: document.getElementById('controls')
  });

  // Register viewport and controls
  configurator.viewPort = viewport;
  configurator.controls = controls;

  // Start configurator
  configurator.initialize();
}
</script>
</body>
</html>