# Configurator Parameter Overrides

### Purpose

This documentation explains how the system dynamically **overrides parameters** in a configurator’s `parameter_list` based on **API user input**. The logic ensures only the necessary fields are updated without breaking unrelated configuration data.

***

### 🔑 Trigger Conditions

Overrides are applied **only if all** the following are true:

1. `open_api_for_user = true` (passed as request attribute).
2. Matching override data exists in the **options field** of the `open_api_tokens` table.
3. The current configurator option has a **matching ID** in the `parameter_list`.

***

### 📦 Data Source

Override data is stored in the `options` column of the **open\_api\_tokens** table as a JSON object.

**Example structure:**

```json
{
  "1400": {
    "id": -47801593,
    "model_id": 606,
    "material_id": 600,
    "material_category_id": 113
  },
  "1401": {
    "id": -18512702,
    "model_id": 606,
    "material_id": 603,
    "material_category_id": 114
  },
  "1402": {
    "id": -52272568,
    "selected": false
  },
  "1403": {
    "id": -17245477,
    "text_value": "Coffee time",
    "custom_color": true,
    "text_font_size": "52",
    "text_font_family": "Birthstone Bounce",
    "text_color_category_id": -1
  }
}

```

### 🧠 Option-Type-Based Logic

| **Option Type**                                | **Fields Updated**                                                                           | **Notes**                                              |
| ---------------------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| select, radio, checkbox, select\_thumb, arrows | `selected`                                                                                   | Set `selected = true` when `option.id == override.id`. |
| material                                       | `model_id`, `material_id`, `material_category_id`                                            | Replaces full material info when IDs match.            |
| text                                           | `text_value`, `custom_color`, `text_font_size`, `text_font_family`, `text_color_category_id` | Used for custom text overrides.                        |
| numeral                                        | `numerical_default`                                                                          | Updates quantity or numeric inputs.                    |
| patterns                                       | *(n/a)*                                                                                      | No updates; reserved for future extension.             |
| default                                        | *(n/a)*                                                                                      | No action taken.                                       |

***

### 📌 Example Use Case

**Overriding configurator options with Open API Token data**

Stored JSON in `options` column:

```json
{
  "1445": {
    "id": -16245477,
    "numerical_default": 3
  },
  "1403": {
    "id": -17245477,
    "text_value": "Coffee time",
    "custom_color": false,
    "text_font_size": "52",
    "text_font_family": "Birthstone Bounce",
    "text_color_category_id": -1
  }
}
```

***

### Override Logic (by Type)

#### 1. Select, Radio, Checkbox, Select\_Thumb, Arrows

```php
$option['selected'] = ($option['id'] === $overrideData['id']);
```

#### 2. Material

```php
if ($option['id'] === $overrideData['id']) {
    $option['model_id']             = $overrideData['model_id'] ?? $option['model_id'];
    $option['material_id']          = $overrideData['material_id'] ?? $option['material_id'];
    $option['material_category_id'] = $overrideData['material_category_id'] ?? $option['material_category_id'];
}
```

#### 3. Text

```php
if ($option['id'] === $overrideData['id']) {
    $option['text_value']             = $overrideData['text_value'] ?? $option['text_value'];
    $option['custom_color']           = $overrideData['custom_color'] ?? $option['custom_color'];
    $option['text_font_size']         = $overrideData['text_font_size'] ?? $option['text_font_size'];
    $option['text_font_family']       = $overrideData['text_font_family'] ?? $option['text_font_family'];
    $option['text_color_category_id'] = $overrideData['text_color_category_id'] ?? $option['text_color_category_id'];
}
```

#### 4. Numeral

```php
if ($option['id'] === $overrideData['id'] && isset($overrideData['numerical_default'])) {
    $option['numerical_default'] = $overrideData['numerical_default'];
}
```

#### 5. Patterns

No override logic is applied.

#### 6. Default

No action is taken.

***

### 📌 Example API Request

**Endpoint:**

```
POST /api/open-api/v1/configurator-options/set/new-options
```

**Body (form-data):**

```
options = {"1436":{"id":-47801593,"model_id":606,"material_id":600,"selected_parts":["Rugby_Ball"]}}
```

***

### 🔄 Example API Response

```json
{
  "data": "http://simp3d.local/configurator/share/fc34308a4984b8d65e9d3dd0538feab4/web/eyJpdiI6Ii9ideCoyRU80ejBLUVJvRjI4U3hxZFE9PSIsInZhbHVlIjoiRzJKTU0...",
  "success": true,
  "message": "Configurator options updated successfully."
}
```

The `data` key contains a **shareable URL** that loads the configurator with the applied overrides.

***

### ✅ Summary

* Override logic is **modular per option\_type**.
* Supports **external control** via API tokens.
* Ensures **data validation** before applying overrides.
* Prevents breaking the structure or overriding unrelated parameters.