# Parameters

# Parameter attributes

The Configurator always displays the Parameter of the selected Component. If no Component is selected, the Parameters of the root Component are displayed. If there are some global parameters and nothing is selected, all global parameters are displayed and they are assigned to Components in the Configuration.

IMPORTANT: In Configurations, Parameters' values are saved. All other values and internal variables must always depend on one actual set of Parameters' values or docking setup and can not be dependend on any of previous values, as the previous states are not saved. This means for you, that you must ensure that all the values can be computed properly and all conditional paths must always be reachable.

Let's look at the parameter and its attributes:

{
    "key": "identifier",
    "labels": {
        "en": "Label",
        "de": "Beschriftung"
    },
    "defaultValue": 1000,
    "type": "Decimal",
    "unitType": "length",
    "global": false,
    "sort": 1,
    "group": "default",
    "enabled": "true",
    "visible": "true",
    "visibleAsGlobal": "false",
    "visibleInPartList": "false",
    "highlighted": "false",
    "validValues": [],
    "valueObjects": [],
    "validGroups": [],
    "conditionalGroups": [],
    "validRange": {},
    "onValueChange": "otherParameter = thisParameter * yetAnotherParameter + 5"
}
  • key A unique identifier you will be using to refer to the values of this Parameter. Use camelCase, do not use PascalCase, do not use underlines_to_separate_words. To correctly name the parameters, see the [Naming Convention] chapter.
  • group Key of a group to which this parameter is assigned to.
  • labels The label of the Parameter in the Configurator UI. You can use different languages. If there is no label, the key is used. English is used as a fallback value, therefore it should always be defined.
  • defaultValue The value this Parameter will have in its default state, unless overriden with Configuration, supposing the value's condition is true.
  • type The value type of this Parameter. Can be: Boolean, Integer, Decimal, String, Material
  • unitType Sets a special behaviour in representation of the values. Can be: length, area, count, angle.
  • global Whether this Parameter is global (creates a global context shown if nothing is selected in the configurator, which is shared with other docked components).
  • sort By default, the order of displayed Parameters matches the order in the JSON. You can override this by putting integer values, where the lowest value is on the top.
    Hint: use multiplies of 10 or 100 to sort the parameters, allowing you to add new parameters in between without having to change the order of all of them.
  • enabled If this is evaluated as false, the UI control will be greyed out and the user won't be able to interact with this component. Also, global value is not assigned.
  • visible Whether it is visible or hidden as a local Parameter, when the component is selected. This attribute should always be explicitely used.
  • visibleAsGlobal If this Parameter is global, determines whether it will be visible if nothing is selected, in the global context.
  • visibleInPartList Whether this parameter and its value is visible as a part list entry.
  • highlighted Currently unused by the configurator. Intended to highlight the parameter in UI.
  • validValues Plain list of possible values. They are always shown.
  • valueObjects List of value objects, which acts as valid values, but can override labels, show thumbnail images and disable themselves using conditions.
  • validGroups Plain list of material tags. If type is Material, it will show all materials carrying the tags.
  • conditionalGroups List of value objects, where the values are tags. Usable with Material.
  • validRange Changes an Integer or Decimal Parameter's UI to a slider. Can not be combined with discrete values.
  • onValueChange Can assign different values to other Parameters. This is an advanced thing and should be used only when you know what you're doing, as this is not fired on Configuration load.

# Parameter's Relevant Values

Parameters should be written in a way, that only values that are relevant can be used in that parameter. This can be a problem with parameters that are hidden from UI, where they could be changed to something else via a configuration JSON, bringing unexpected behaviour. This override can also happen, if more objects are selected at once (using multi-selection tool).

# Parameter Types and Unit Types

The type key in a Parameter is not the same as a data type. Description of RoomleScript data types can be found in [RoomleScript Overview]. Parameter types follow:

# types:

  • Boolean A checkbox UI control with the Parameter-level next to it. The value which is stored is 1 for true and 0 for false.
  • Integer A button UI control where the Parameter holds Integer values.
  • Decimal A button UI control where the Parameter holds Decimal values. The values labels will have two decimal places displayed (e.g. 100.00).
  • String A button UI control where the Parameter holds String values. The labels are matching the values.
  • Material A material thumbnail + viewable name list UI control from the material database. The values are the materialIds or materials categoryIds and the data type of the values is String.

# unitTypes:

  • length Converts numeric value to cm, mm, based on configurator settings and locale.
  • area Shows numeric value as square meters
  • angle Shows numberic value as degrees
  • count

# Working with Imperial Measurements - Inches and Feet

The default unit of the configurator can not be set - it is always milimeters. If you are working in inches, convert all your computations to milimeters using an milimeter to inch ratio 2.54. In order to show the parameters in feet and inches, use parameter values in milimeters, use "unitType": "length" and let the configurator settings convert the milimeters to inches for you. To view the inches in the test site, set Embedding > Main > Unit to inches and reload the configurator. To set direct links of the configurator to inches, use &unit=inchfeet&precisionInch=X as additional arguments, where X is the count of decimal spaces. Unless you really need to, do not convert the parameters to inches or feet values, which you actually can achieve by not using the unitType and overriding valueObject labels. If you do so, you will have to recompute all coordinates and distances using the 2.54 at some point.

# Value Objects

You often need to limit some combinations of values, modify their labels or add thumbnails to them. To be able to achieve this, the plain list of values is not enough and we need something more complex, which are the valueObjects. A Parameter can have either validValues or valueObjects, not both (there will also be validRange, but we will get to it).

A valueObject has following structure:

{
    "value": "132",
    "condition": "booleanExpression",
    "thumbnail": "url-to-an-image-in-PDC",
    "labels":{
        "en": "Custom label",
        "de": "Definierte Beschriftung"
    }
}
  • value The value that will be internally used and stored in Configurations.
  • condition A boolean expression that defines the visibility and possibility to select this valueObject. Once the condition gets to false when this valueObject is selected, first valid valueObject from the list is the fallback.
  • thumbnail URL to a thumnbail image from the Roomle PDC.
  • labels The custom labels data structure.

# Example: Parametrized Table Value Combinations

To best describe the usage of the valueObjects, let's say the table widths are called S, M and L and the table comes in two depth options: Standard and Extra, where the S width is not available in the Extra depth. To keep using the original numerical length values for the width and depth, we use valueObjects and we will modify the labels. For limiting the options combinations, we use the condition. The parameters field of the table will look like this:

Unfold to see the final parameters code.
"parameters": [
    {
        "key": "width",
        "type": "Decimal",
        "labels": {
            "en": "Width",
            "de": "Breite"
        },
        "unitType": "length",
        "defaultValue": 1000,
        "valueObjects": [
            {
                "value": 800,
                "condition": "depth < 700",
                "labels": {
                    "en": "S",
                    "de": "klein"
                }
            },
            {
                "value": 1000,
                "labels": {
                    "en": "M",
                    "de": "medium"
                }
            },
            {
                "value": 1200,
                "labels": {
                    "en": "L",
                    "de": "groƟ"
                }
            }
        ],
        "enabled": true,
        "visible": true,
        "visibleInPartList": true
    },
    {
        "key": "depth",
        "type": "Decimal",
        "labels": {
            "en": "Depth",
            "de": "Tiefe"
        },
        "unitType": "length",
        "defaultValue": 600,
        "valueObjects": [
            {
                "value": 600,
                "labels": {
                    "en": "Standard",
                    "de": "standard"
                }
            },
            {
                "value": 700,
                "condition": "width > 800",
                "labels": {
                    "en": "Extra",
                    "de": "extra"
                }
            }
        ],
        "enabled": true,
        "visible": true,
        "visibleInPartList": true
    }
]

IMPORTANT: In the last example, you can notice that the parameters' valueObjects conditions influence each other. If you are not careful, this can lead to a deadlock where you won't be able to select a certain combination of values and get back out of a such combination. For example, size L is available only with Extra depth and the Extra depth is available only in size L.

# Ranges

Ranges allow you to make a slider UI control. You can specify the lower and upper bounds of the range and optionally also a constant step size. An example of a range Parameter follows:

{
    "key": "range",
    "defaultValue": 150,
    "type": "Decimal",
    "validRange": {
        "valueFrom": "100",
        "valueTo": "300",
        "step": "50"
    },
    "enabled": true,
    "visible": true,
    "visibleInPartList": true
}

Note: As of 2020, there is no possibility to combine a range with valueObjects or validValues to have these values on a slider. On the other hand, there is a possibility to have the bounds parametrized, but you must do it like in the following example so that the kernel parses the bounds as expressions and not as strings:

{
    "key": "range",
    "defaultValue": 150,
    "type": "Decimal",
    "validRange": {
        "valueFrom": "0 + lowerBound",
        "valueTo": "0 + upperBound",
        "step": "1 * stepSize"
    },
    "enabled": true,
    "visible": true,
    "visibleInPartList": true
}

# Parameter Groups

In order to provide better user experience, you can divide parameters into groups. Groups will appear as sections in the Roomle Configurator, leading the end users through the process of configuring their products in a wizard-like manner. The groups are defined in the parameterGroups list and will be shown in the configurator, when at least one member parameter is visible in the current context.

Rule: All parameters should either be grouped or non-grouped. Combination of grouped and non-grouped parameter is not recommended.

To define a parameter group, use following list at the root of the component:

...
"parameterGroups": [
    {
        "key": "grpKey",
        "labels": {
            "en": "group label"
        }
    }
],
...

To use the group, add a group attribute with the matching key of the group you want to a parameter:

    ...
    "parameters": [
        {
            "key": "key",
            "group": "grpKey",
            ...

# Example: Parameter Grouping

In this example, we will show how to prepare parameters for a table, that consist of a tabletop, a frame and four cylindrical telescopic adjustable legs, allowing to set the table's worktop height between 680 and 730 mm.

Because the main product defining parameter are the dimensions, they will go in a group called "Size". In order to let the users visualize all possible heights of the table, we will use another group, "View", with a parameter called "Tabletop height"

Unfold to see the source code that injects groups and a range parameter into the previous example.
{
    "id": "catalog_id:component",
    "parameterGroups": [
        {
            "key": "grpSize",
            "labels": {
                "en": "Size"
            },
            "collapsed": false,
            "sort": 0
        },
        {
            "key": "grpView",
            "labels": {
                "en": "View"
            },
            "collapsed": false,
            "sort": 0
        }
    ],
    "parameters": [
        {
            "key": "width",
            "group": "grpSize",
            "labels": {
                "en": "Width"
            },
            "type": "Decimal",
            "unitType": "length",
            "defaultValue": 1000,
            "validValues": [
                800,
                1000,
                1200
            ],
            "enabled": true,
            "visible": true,
            "visibleInPartList": true
        },
        {
            "key": "depth",
            "group": "grpSize",
            "labels": {
                "en": "Depth"
            },
            "type": "Decimal",
            "unitType": "length",
            "defaultValue": 600,
            "validValues": [
                600,
                700
            ],
            "enabled": true,
            "visible": true,
            "visibleInPartList": true
        },
        {
            "key": "tabletopHeight",
            "group": "grpView",
            "labels": {
                "en": "Tabletop Height"
            },
            "type": "Decimal",
            "unitType": "length",
            "defaultValue": 710,
            "validRange": {
                "valueFrom": 680,
                "valueTo": 730
            },
      
            "enabled": true,
            "visible": true,
            "visibleInPartList": true
        }
    ],
    "onUpdate": "",
    "geometry": "AddCube(Vector3f{width, depth, 1000});",
    "articleNr": "'123.465'"
}

# Examples of Parameters and their UI Represenatations

# Type: Boolean - Yes/No Option

A boolean parameter will always show Yes and No as options, regardless on language. This is automatic, boolean values can not be overriden.

{
    "id": "example:parameter_boolean",
    "parameters": [
        {
            "key": "boolean",
            "labels": {
                "en": "Boolean Parameter"
            },
            "type": "Boolean",
            "defaultValue": true,
            "validValues": [
                true,
                false
            ]
        }
    ]
}

Boolean Parameters Display

# Type: Integer and Decimal

Integer and decimal parameters will automatically create clickable options showing the numbers. Keep in mind, that decimal is always displayed with two trailing decimal spaces, regardless of how many of them you define in the values.

{
    "id": "example:parameter_integer",
    "parameters": [
        {
            "key": "integer",
            "labels": {
                "en": "Integer Parameter"
            },
            "type": "Integer",
            "defaultValue": true,
            "validValues": [
                -5,
                0,
                2,
                3000
            ]
        },
        {
            "key": "decimal",
            "labels": {
                "en": "Decimal Parameter"
            },
            "type": "Decimal",
            "defaultValue": true,
            "validValues": [
                -5,
                0,
                3.1415,
                3000.00
            ]
        }
    ]
}

Integer and Decimal Parameters Display

# Unit Type: Length

This will automatically create labels based on what the current value of the configurator's unit attribute is. Therefore following code will have different results based on the locale of the language and area settings of the machine the configurator is running on.

{
    "id": "example:parameter_decimal",
    "parameters": [
        {
            "key": "decimal",
            "labels": {
                "en": "Decimal Parameter"
            },
            "type": "Decimal",
            "unitType":"length",
            "validValues": [
                -5,
                0,
                25.4,
                3000.00
            ]
        }
    ]
}

default or unit=cm

Length Parameter in CM

unit=inchFeet

Length Parameter in Inches

unit=mm

Length Parameter in MM

# Material or Parameter with Thumbnails

Up to 5 thumbnail fit on a single line. If there are more parameters, the rest of them will be compacted behind the "Show all" button, replacing the 5th thumbnail, unless that parameter is not the only one in the group. Thumbnails are links to images defined in valueObject.thumbnail.

A single thumbnail parameter in the group context will display unfolded.

{
    "id": "example:parameter_full_thumbnail",
    "parameters": [
        {
            "key": "elementType",
            "type": "String",
            "labels":{
                "en": "Element Type"
            },
            "valueObjects": [
                {
                    "value": "inline", "labels": {"en": "Inline element"},
                    "thumbnail": "https://catalog.roomle.com/85dbd885-7582-4780-bdd7-f976ec6b49d9/items/bestsofa_inline/perspectiveimage.png?marker=1590759964"           
                },
                {
                    "value": "armchair", "labels": {"en": "Chair"},
                    "thumbnail": "https://catalog.roomle.com/85dbd885-7582-4780-bdd7-f976ec6b49d9/items/bestsofa_armchair/perspectiveimage.png?marker=1598434263"
                },
                {
                    "value": "sofa", "labels": {"en": "Sofa"},
                    "thumbnail": "https://catalog.roomle.com/85dbd885-7582-4780-bdd7-f976ec6b49d9/items/bestsofa_sofa/perspectiveimage.png?marker=1598434181"
                },
                {
                    "value": "inlinearmrest_left", "labels": {"en": "Armrest element left"},
                    "thumbnail": "https://catalog.roomle.com/85dbd885-7582-4780-bdd7-f976ec6b49d9/items/bestsofa_inlinearmrest_left/perspectiveimage.png?marker=1590759310"
                },
                {
                    "value": "inlinearmrest_right", "labels": {"en": "Armrest element right"},
                    "thumbnail": "https://catalog.roomle.com/85dbd885-7582-4780-bdd7-f976ec6b49d9/items/bestsofa_inlinearmrest_right/perspectiveimage.png?marker=1590758015"
                },
                {
                    "value": "longchair_left", "labels": {"en": "Longchair left"},
                    "thumbnail": "https://catalog.roomle.com/85dbd885-7582-4780-bdd7-f976ec6b49d9/items/bestsofa_longchair_left/perspectiveimage.png?marker=1590758913"
                },
                {
                    "value": "longchair_right", "labels": {"en": "Longchair right"},
                    "thumbnail": "https://catalog.roomle.com/85dbd885-7582-4780-bdd7-f976ec6b49d9/items/bestsofa_longchair_right/perspectiveimage.png?marker=1590759065"
                }
            ]
        }
    ]
}

Unwrapped thumbnail parameter

Materials parameters are automatically displayed with thumbnails. The source of the image is the thumbnail of the material in the PDC. If the material has no diffuse map and there is no custom thumbnail, the plain colour is used. If we combine the elementType parameter with a new material parameter in a single group context, they both will be compacted (unless they have less then 5 valid options), displaying first 4 and a "Show all" button.

{
    "id": "example:parameter_compacted_thumbnail",
    "parameters": [
        {
            "key": "elementType",
            "type": "String",
            "labels":{
                "en": "Element Type"
            },
            "valueObjects": [
                {
                    "value": "inline", "labels": {"en": "Inline element"},
                    "thumbnail": "https://catalog.roomle.com/85dbd885-7582-4780-bdd7-f976ec6b49d9/items/bestsofa_inline/perspectiveimage.png?marker=1590759964"           
                },
                ...
            ]
        },
        {
            "key": "material",
            "type": "Material",
            "labels":{
                "en": "Material"
            },
            "validValues": [
                "candy:florida_anthrazit",
                "candy:florida_beige",
                "candy:florida_chocolate",
                "candy:florida_dark_grey",
                "candy:florida_deep_ocean",
                "candy:florida_espresso",
                "candy:florida_grey",
                "candy:florida_light_blue",
                "candy:florida_rot",
                "candy:florida_saphran",
                "candy:florida_stone"
            ]
        }
    ]
}

Compacted thumbnail parameter

# Buttons vs Dropdown

Following parameters differ in nothing but the count of validValues. The first will be displayed as button options, the second as a dropdown. The configurator itself decides which of them to display. If the values fit to a single line, buttons are displayed, otherwise this changes to a dropdown.

{
    "id": "example:parameter_buttons_dropdown",
    "parameters": [
        {
            "key": "buttons",
            "labels": {
                "en": "Buttons"
            },
            "type": "Integer",
            "validValues": [
                1,2,3
            ]
        },
        {
            "key": "dropdown",
            "labels": {
                "en": "Dropdown"
            },
            "type": "Integer",
            "validValues": [
                1,2,3,4,5,6,7,8,9,10,11,12
            ]
        }
    ]
}

Length Parameter in MM

# Range

To create a slider, use validRange instead of validValues or valueObjects in a parameter of type Integer or Decimal. unitType applies for ranges in the same way like for a standard numeric parameter. valueFrom, valueTo and step are of Script<float> type, therefore expression can be used in them. Keep in mind, that although the step can be variable, the step is uniform. Maximum value is lesser or equal to valueTo, while minimum value equals to valueFrom.

{
    "id": "example:parameter_buttons_dropdown",
    "parameters": [
        {
            "key": "rangeStep",
            "type": "Decimal",
            "validValues": [1, 10, 100]
        },
        {
            "key": "range",
            "defaultValue": 0,
            "type": "Decimal",
            "unitType":"length",
            "validRange": {
                "valueFrom": -1000,
                "valueTo": 999,
                "step": "rangeStep"
            },
            "enabled": true,
            "visible": true,
            "visibleInPartList": true
        }
    ]
}

Range Parameter in CM