Manually Generated Controls
These type of controls are written directly into the HTML document as HTML input elements, select element or in a different way. This allows complete freedom in placing them with respect to other content. There is no container element needed here, as it is required for the auto-controls. When the configurator gets started, the input elements get activated and control the input and output of the respective configurator's parameters.
Manually generated controls are based on the module "controls" that needs to be included into the document:
Example
<head>
<script src="https://libs.paramate.trinckle.com/paramateConfigurator-latest.js"></script>
<script src="https://libs.paramate.trinckle.com/paramateControls-latest.js"></script>
...
</head>
The creation of the controls object works mostly similar as in the case of auto-generated controls:
Example
<script>
...
var configurator = new Paramate.Configurator({ ... });
var controls = new Paramate.Controls({
configurator: configurator
});
configurator.controls = controls;
...
</script>
Input and Select Elements
Each input or select element must belong to class paramateParam. In addition it must contain an attribute data-paramate-paramName that identifies the open parameter by name. This name must be equal to the one defined in the paramate CAD model the configurator is based on. Also the type of the input must fit to the respective open parameter according to the following list:
| Input Type / Select | Open Parameter Type |
| checkbox | bool |
| color | color |
| file | file |
| number | int or float |
| radio | any (set values accordingly) |
| range | int or float |
| text | any |
| select element | any (set values accordingly) |
The following example attaches two input elements and one select element to the configurator: a checkbox that controls a boolean parameter, a text box that controls a string or number parameter and a select control that controls a second boolean parameter:
Example
<body>
<input type="checkbox" class="paramateParam" data-paramate-paramName="main:myFirstBool" >
<input type="text" class="paramateParam" data-paramate-paramName="main:myStringOrNumber">
<select class="paramateParam" data-paramate-paramName="main:mySecondBool">
<option value="false">Off</option>
<option value="true">On</option>
</select>
...
</body>
Settings
For number parameters (number and range input) it is often useful to set the step and precision attributes. These can be set in the properties of the open parameter, like in the following example:
Example
{
style = "precision: 2; step: 0.5"
}
Clickable Elements
Sometimes it is required that the user makes a selection by mouse clicking onto certain HTML elements like texts, icons or images. This can be achieved by attributing the elements to class paramateParamClickable. The name of the open parameter must be provided as attribute data-paramate-paramName and a value must be given as attribute data-paramate-paramValue. By this, the elements are turned into controls that set the open parameter to the given values when being clicked.
The element that contains the current value of the open parameter is attributed to class paramateParamClickableActive. Since this class attribution gets updated permanently during the execution of the configurator, this can be used to individualize the style of the active elements.
Remark
If paramateParamClickableActive is used to style the active clickable element, an initial switching of the styles may occur on starting the configurator when the open parameter values get initialized. To avoid such "flickering", the element that contains the initial open parameter value (if this is known a priori) can be preset to class paramateParamClickableActive. This is done for the second clickable element in the following example.
Example
<body>
<img class="paramateParamClickable" data-paramate-paramName="main:myParam" data-paramate-paramValue="1" src="one.png" alt="One">
<img class="paramateParamClickable paramateParamClickableActive" data-paramate-paramName="main:myParam" data-paramate-paramValue="2" src="two.png" alt="Two">
<img class="paramateParamClickable" data-paramate-paramName="main:myParam" data-paramate-paramValue="3" src="three.png" alt="Three">
...
</body>
File Parameters
File parameters have some special features. Setting up a file parameter control is easy, you can use a regular file input element. When you select a file with this file input, it will automatically start the upload and then change the open parameter value. The element can have an attribute called data-paramate-progress, where the value of it is a function to be called as the upload progresses.
Remark
The function specified in the data-paramate-progress attribute gets called with an object as an argument, containing the loaded and total numbers, which can be used to show the progress rate of the upload.
Example
<head>
<script>
function showProgress()
{
// show a progress bar
...
}
function setProgress(e)
{
// set the progress bar to the right value
var percent = Math.floor(e.loaded / e.total * 100);
}
</script>
</head>
<body>
<input type="file" class="paramateParam" data-paramate-paramName="main:myParam" data-paramate-progress="setProgress" onChange="showProgress();">
...
</body>
Displaying Open Parameter Value and Attributes
The paramate JavaScript API has means to obtain the value or an attribute of an open parameter directly via functions getParamValue() and getParamAttrValue(). However for displaying such value somewhere on a web page, it often is more convenient to use an utilized span tag (or any other HTML element with innerHTML property) instead. To do so, the element must be attributed to either class paramateParamValue or paramateParamAttr and the open parameter's name must be specified as attribute data-paramate-paramName. In the case of class paramateParamAttr, the name of the open parameter's attribute must additionally be given as data-paramate-paramAttr. The element will then be filled with text of the respective value. In the case of class paramateParamValue, special settings may be applied to the value, for example the number of decimals if it is set in the style property of the open parameter.
Example
<body>
Min.: <span class="paramateParamAttr"
data-paramate-paramName="main:minSize"
data-paramate-paramAttr="min"></span> mm
...
</body>
Output
Min: 22 mm
Array Open Parameters
By using the paramate JavaScript API it is possible to access elements of an array open parameter. To do so, the usual input and select elements can be used and the attribute data-paramate-paramName has to be filled with the name of the open parameter and an additional array index. In this case the control will work as it does for the other types. When an array open parameter is used without the index (or in case of a multi-dimensional array not for the last index) the value will be a JSON string representing the referenced array.
Example
<body>
<input type="checkbox" class="paramateParam" data-paramate-paramName="main:myBoolArray[0]" >
<input type="checkbox" class="paramateParam" data-paramate-paramName="main:myBoolArray[1]" >
<input type="text" class="paramateParam" data-paramate-paramName="main:myStringArray[0]">
...
</body>
AfterConfigure Callback
By using the data-paramate-afterConfigure attribute it is possible to specify a callback function that will be called after the configuration, just like the onAfterConfigure function specified for the configurator, but in this case only when this parameter is changed. The value of the attribute can be a function name or some javascript code.
Example
<body>
<input type="text" class="paramateParam" data-paramate-paramName="main:myStringOrNumber" data-paramate-afterConfigure="myfunction">
<input type="text" class="paramateParam" data-paramate-paramName="main:myOtherStringOrNumber" data-paramate-afterConfigure="alert('configured');">
...
</body>
BeforeConfigure Callback
By using the data-paramate-beforeConfigure attribute it is possible to specify a callback function that will be called before the configuration, just like the onBeforeConfigure function specified for the configurator, but in this case only when this parameter is changed. The value of the attribute can be a function name or some javascript code. The function is called with the value that will be used for the configuration and the function has to return true to let the configuration happen.
Example
<script>
function myfunction(val)
{
if (confirm('do you want to configure with the value ' + val + '?'))
return true;
else
return false;
}
</script>
<body>
<input type="text" class="paramateParam" data-paramate-paramName="main:myStringOrNumber" data-paramate-beforeConfigure="myfunction">
<input type="text" class="paramateParam" data-paramate-paramName="main:myOtherStringOrNumber" data-paramate-beforeConfigure="alert('will configure'); return true;">
...
</body>
Multiple Configurators
Having multiple configurators on the same page can cause ambiguity if multiple configurators have the same open parameter names. To avoid this, the controls object can take a name in its constructor and the same name has to be used in the data-paramate-controlsName attribute.
Example
<script>
...
var configurator1 = new Paramate.Configurator({ ... });
var controls1 = new Paramate.Controls({
configurator: configurator1,
name: 'controls1'
});
configurator1.controls = controls1;
var configurator2 = new Paramate.Configurator({ ... });
var controls2 = new Paramate.Controls({
configurator: configurator2,
name: 'controls2'
});
configurator2.controls = controls2;
...
</script>
<body>
<input type="text" class="paramateParam" data-paramate-paramName="main:myParam" data-paramate-controlsName="controls1">
<input type="text" class="paramateParam" data-paramate-paramName="main:myParam" data-paramate-controlsName="controls2">
...
</body>
