paramate

Using a file from a URL as a parameter value

Sometimes you need to upload a file to a configurator via JavaScript that is not coming from the user's input.

How it works

Files can be used as open parameters. Most of the time the files come from the user, and there is a built-in control for that in the JavaScript libraries. However, it might be needed to upload a file without the user's interaction, for example an image that is generated by another service.

In this short tutorial you can see how to use an online generated image in the configurator.

trCAD code

For the tutorial we use a very simple example code.

open file img 
{
  name = "Image"
  descr = "Image to be transformed to a solid"
  value = ""
}

make img_to_solid( image( img ), 15.0, 25.0 )

The explanation of this code is out of the scope of the tutorial, enough to know that the configurator expects an image and turns it into a mesh.

The JavaScript code

The entire solution is very short but it can get tricky. The next lines will do the trick though. All we have to do is download the image via XMLHttpRequest, then upload it to the paramate system and when that is done, set the img open paramater to the right value.

var oReq = new XMLHttpRequest();
oReq.open("GET", "https://picsum.photos/200/300");
oReq.responseType = 'arraybuffer';

oReq.onload = function(e)
{
  configurator.doRequest(
  {
    url: configurator.APIHub + '/configSessions/' + configurator.configSession + '/files/' + btoa('main:img'),
    method: 'PUT',
    contentType: 'image/jpeg',
    responseType: 'json',
    data: oReq.response,
    success: function(res)
    {
      configurator.setParamValue('main:img', res.token);
    }
  });
}

oReq.send();

The explanation of the most important parts of the code:

```
oReq.open("GET", "https://picsum.photos/200/300");
```
The url https://picsum.photos/200/300 gives back a random 200x300 pixels big image.
```
oReq.responseType = 'arraybuffer';
```
It is important to request an arraybuffer type so we can easily work with that later.
```
oReq.onload = function(e)
```
We set up the onload event handler for the XMLHttpRequest that downloads the image, so when that is done, this event handler will be called.
```
configurator.doRequest(
```
We use the doRequest function on the configurator object implemented in the Paramate Configurator library to make it easier to do the upload.
```
url: configurator.APIHub + '/configSessions/' + configurator.configSession + '/files/' + btoa('main:img'),
```
In this line the btoa('main:img') could be anything else, it is just an identifier base64 encoded so it's url-safe. We use this specific one, because the same is used by the automatic controls, so it will be compatible with that too. That also means, that we won't waste resources when we use an automatic control too for the same open parameter.
```
contentType: 'image/jpeg',
```
Setting the right content type for our image is very important.
```
data: oReq.response,
```
We use the result of the download.

success: function(res)
{
  configurator.setParamValue('main:img', res.token);
}

When the upload is done, we do the configuration on the configurator object.