# Advanced Partlist Topics

Roomle platform supports various partlist features. These include aggregating more pieces of one artilce into packages in defined sizes, change article number based on the package and change the article name accordingly.

# Packaging

Packaging is a feature that will aggregate the articles into packages that have defined number of pieces. Take chair endcaps as example: they are individual pieces and you need (usually) 4. It makes perfect sense that they come packed in sets of 4 pieces. Screws can also be counted individually, but also come in packages with many pieces. Packaging is a defined feature of the component. Amount of one partlist entry in the whole configuration is shown in the partlist as the count. If the entries have defined package sizes, they will divide into those packages. You define packaging on the component level, using either packageSizes or packaging. While packageSizes is a plain list of integers, packaging allows you to define the package sizes using conditional values.

Let's take a closer look at a following demonstration example of packaging.

{
    "id": "demoCatalogId:example_packagesize",
    "parameters": [
        {
            "key": "count",
            "defaultValue": 0,
            "type": "Integer",
            "validRange": {
                "valueFrom": 0,
                "valueTo": 100,
                "step": 1
            },
            "enabled": true,
            "visible": true,
            "visibleInPartList": true
        }
    ],
    "subComponents": [
        {
            "internalId": "SELF",
            "componentId": "demoCatalogId:example_packagesize",
            "numberInPartList": "count"
        }
    ],
    "packageSizes": [
        1,
        5,
        10
    ]
}

You can see that there is a range parameter called count, which influences the number in partlist of the back-referred component (see Partlist Entry part of the SubComponents chapter). This way you can define how many times this component should be present in the partlist. The packageSizes define that the articles should be divided into packages of 1, 5 and 10 pieces - and they will do. If you load this and set the count variable to 29, you will see 3 partlist entries with counts of 2, 1 and 4 (2 * 10 + 1 * 5 + 4 * 1 = 29). In order to distinguish between what is a package, what is a piece etc., you can compute the article numbers for the individual packaging:

{
    "articleNr": "
        if (packageSize == 1) { articleNr = '120.079.031'; }
        if (packageSize == 5) { articleNr = '120.079.785'; }
        if (packageSize == 10) { articleNr = '120.079.310'; }
    "
}

Resulting partlist looks like this:

partlist

There are also cases where you need conditional package sizes - the packaging. Typical usecase: a shelf comes in two sizes. One of the sizes comes in packaging of 2 or 4, the other one only in the double package:

{
    "parameters": [
        {
            "key": "shelfWidth",
            "type": "Decimal",
            "labels": {
                "en": "Width"
            },
            "defaultValue": 245,
            "enabled": "true",
            "visible": "true",
            "validValues": [
                245,
                435
            ]
        },
    ],
    "packaging": [
        {
            "size": "2",
            "condition": "true"
        },
        {
            "size": "4",
            "condition": "shelfWidth == '245'"
        }
    ],
    "articleNr": "
        if (shelfWidth == 245) {
            if (packageSize == 2) { articleNr = '645.010'; }
            if (packageSize == 4) { articleNr = '645.020'; }
        }
        if (shelfWidth == 435) { articleNr = '645.030'; } 
    "
}

# Component Label

Component-level label is what is shown in the partlist as the entry name. In the example above, this label is the example_packagesize and comes from the Rubens Admin entry label. To batch upload these labels, see Rubens Admin CSV Examples.

However, sometimes you need this label to be variable. Typical example: the packaging. Let's add the label to the examples where the packageSizes have been explained:

{
    "label": "
        if (articleNr == '120.079.031') { label = 'example_packageSize'; }
        if (articleNr == '120.079.785') { label = 'example_packageSize' | ', blister of 5'; }
        if (articleNr == '120.079.310') { label = 'example_packageSize' | ', box of 10'; }
    "
}

Note: you can use packageSize in the label script as you did in the articleNr script - feel free to do so:

{
    "label": "
        if (packageSize == 1) { label = 'example_packageSize'; }
        if (packageSize == 5) { label = 'example_packageSize' | ', blister of 5'; }
        if (packageSize == 10) { label = 'example_packageSize' | ', box of 10'; }
    "
}

The result will be the same, but keep in mind, that tables of article numbers and labels are commonly provided. If you have the data at your disposal in a formalized way, like in a table or in a database, best approach is to generate the code from it. See following Excel formula as an example:

="if (articleNr == '"&A1&"') { label = '"&B1&"'; }", supposing there is articleNumber in the column A and label in the column B.

To be able to translate to other languages, you can use language getter, which is accessible in the label script:

{
    "label": "
        if (packageSize == 1) { label = 'example_packageSize'; }
        if (packageSize == 5) { label = 'example_packageSize' | ', blister of 5'; }
        if (packageSize == 10) { label = 'example_packageSize' | ', box of 10'; }
        if (language == 'de') {
            if (articleNr == '120.079.031') { label = 'beispiel_packageSize'; }
            if (articleNr == '120.079.785') { label = 'beispiel_packageSize' | ', 5 Stück im Blister'; }
            if (articleNr == '120.079.310') { label = 'beispiel_packageSize' | ', Box mit 10 Stück'; }
        }
    "
}

Important: Because English is used as a fallback language in the Roomle platform, it is the scripters' responsibility, that there are always the labels defined in a way that it always gets to a fallback value. A good approach is to define label in English, then eventually override it by other languages (like in the example above).

# Where are component labels used?

Currently the configurator shows the main label and the sub label:

Content of those labels follows this pseudo-code:

const label = rootComponentLabel || rapiItemLabel || catalogName || '';
const catalogLabel = (label === catalogName) ? null : catalogName;
const subLabel = (price) ? label : catalogLabel;
const mainLabel = price ? price : label;

Where:

  • rootComponentLabel is the constant database label of the component (component.label script is not used here)
  • rapiItemLabel if configurator is loaded by itemId, catalogue label of the item
  • catalogName is the constant database label of the catalogue
  • price is shown if pricing is used

To change labels in Rubens Admin, you can also upload the CSV with translations, see Adding translations (opens new window).

Partlist entries show the label from component.label script or the component label in the database:

Note: component.labels (notice the difference with the previous - plural vs singular) object is legacy and is not used in current version of the Roomle Rubens Configurator.