> For the complete documentation index, see [llms.txt](https://dustinsimon.gitbook.io/shopware-utils/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dustinsimon.gitbook.io/shopware-utils/adding-resources/custom-fields.md).

# Custom fields

dustin/shopware-utils takes away the pain many Shopware developers had before: Installing custom fields with a plugin! All you have to do is to create a json file!

Custom field sets and custom fields will automatically be installed and updated with your plugin/AdditionalBundle. They will also be removed on plugin uninstallation.

Here is an example of a custom field set json file:

{% code title="my\_custom\_field\_set.json" %}

```json
{
    "name": "my_custom_field_set",
    "editable": false,
    "label": {
        "de-DE": "Mein CustomField Set",
        "en-GB": "My custom field set"
    },
    "translated": true,
    "position": 2,
    "customFields": {
        "my_custom_field": {
            "type": "text",
            "label": {
                "de-DE": "Mein CustomField",
                "en-GB": "My custom field"
            },
            "helpText": {
                "de-DE": "Ein hilfeicher Text",
                "en-GB": "A helpful text"
            },
        },
        "my_other_custom_field": {
            "type": "int",
            "label": {
                "de-DE": "Mein anderes CustomField",
                "en-GB": "My other custom field"
            }
        }
    },
    "relations": [
        "product",
        "category"
    ]
}
```

{% endcode %}

{% hint style="success" %}
After you've created your custom field set json file you have to run the following command to update or install your custom fields:

`bin/console plugin:update <PluginName>`&#x20;
{% endhint %}

## Create a custom field set

For each custom field set you need to create a json file in *Resources/custom\_fields/* of your plugin or AdditionalBundle. The name of the json file needs to be identical to the name of the custom field set. You can use the example from above to create a first set.\
\
Here is a list of all possible options:

<table><thead><tr><th width="203.83203125">key</th><th width="100.91796875">type</th><th width="265.79296875">description</th><th width="92.53515625">Required</th><th width="74.40234375">Default</th></tr></thead><tbody><tr><td>name</td><td>string</td><td>The name of the custom field set. Must be identical to the json file name</td><td>yes</td><td></td></tr><tr><td>label</td><td>object</td><td>Holds the label of the custom field set in different languages. de-DE and en-GB are required. You can add more translations if you want.</td><td>yes</td><td></td></tr><tr><td>label > de-DE</td><td>string</td><td>The label in german</td><td>yes</td><td></td></tr><tr><td>label > en-GB</td><td>string</td><td>The label in english</td><td>yes</td><td></td></tr><tr><td>translated</td><td>bool</td><td>Bool whether the custom field set should be translated or not</td><td>yes</td><td></td></tr><tr><td>editable</td><td>bool</td><td>If set to false users are not able to edit or delete the custom field set in administration</td><td>no</td><td>false</td></tr><tr><td>position</td><td>integer</td><td>The position of the custom field set on entity detail pages</td><td>no</td><td>1</td></tr><tr><td>customFields</td><td>object</td><td>An object containing the custom fields with the property name as the custom field name.</td><td>yes</td><td></td></tr><tr><td>relations</td><td>array of strings</td><td>A list of all entity names related to this custom field set</td><td>yes</td><td></td></tr></tbody></table>

## Custom fields

Custom fields are located under the *customFields* key of your custom field set json file.&#x20;

```json
...
{
    "type": "text",
    "allowStoreApiWrite": false,
    "allowCartExpose": false,
    "position": 5,
    "label": {
        "de-DE": "Mein CustomField",
        "en-GB": "My custom field"
    },
    "helpText": {
        "de-DE": "Ein hilfreicher Text",
        "en-GB": "A helpful text"
    },
    "required": false
}
...
```

Here is a list with all options all custom fields have in common. There are some more options available per type. You will learn about them below.

<table><thead><tr><th width="203.83203125">key</th><th width="100.91796875">type</th><th width="265.79296875">description</th><th width="92.53515625">Required</th><th width="74.40234375">Default</th></tr></thead><tbody><tr><td>type</td><td>string</td><td>The type of the custom field. Must be one of:<br>- bool<br>- colorpicker<br>- datetime<br>- entity<br>- float<br>- int<br>- price<br>- html<br>- media<br>- select<br>- text<br>- json</td><td>yes</td><td></td></tr><tr><td>allowStoreApiWrite</td><td>bool</td><td>Boolean whether the custom field should be modifyable via store api</td><td>no</td><td>false</td></tr><tr><td>allowCartExpose</td><td>bool</td><td>Boolean whether the custom field should be available in carts</td><td>no</td><td>false</td></tr><tr><td>position</td><td>integer</td><td>The position of the custom field in the administration</td><td>no</td><td>1</td></tr><tr><td>label</td><td>object</td><td>Holds the label of the custom field in different languages. de-DE and en-GB are required. You can add more translations if you want.</td><td>yes</td><td></td></tr><tr><td>label > de-DE</td><td>string</td><td>The label of the custom field in german</td><td>yes</td><td></td></tr><tr><td>label > en-GB</td><td>string</td><td>The label of the custom field in english</td><td>yes</td><td></td></tr><tr><td>helpText</td><td>object</td><td>Holds a help text of the custom field in different languages. de-DE and en-GB are required. You can add more translations if you want.</td><td>no</td><td></td></tr><tr><td>helpText > de-DE</td><td>string</td><td>The help text in german</td><td>yes</td><td></td></tr><tr><td>helpText > en-GB</td><td>string</td><td>The help text in english</td><td>yes</td><td></td></tr><tr><td>required</td><td>bool</td><td>A boolean whether the custom field is a required field</td><td>no</td><td>false</td></tr></tbody></table>

## Custom field types

There are several types of custom fields. Each brings it's own config options.

### Boolean

```json
...
{
    "type": "bool",
    "label": {
        "de-DE": "Mein CustomField",
        "en-GB": "My custom field"
    },
    "config": {
        "component": "switch"
    }
}
...
```

<table><thead><tr><th width="203.83203125">key</th><th width="100.91796875">type</th><th width="265.79296875">description</th><th width="92.53515625">Required</th><th width="74.40234375">Default</th></tr></thead><tbody><tr><td>config > component</td><td>string</td><td>"switch" or "checkbox". The component to use in the Shopware administration</td><td>yes</td><td></td></tr></tbody></table>

### Text

```json
...
{
    "type": "text",
    "label": {
        "de-DE": "Mein CustomField",
        "en-GB": "My custom field"
    },
    "placeholder": {
        "de-DE": "Ein Platzhalter-Text",
        "en-GB": "A placeholder"
    },
    "config": {
        "large": false
    }
}
...
```

<table><thead><tr><th width="203.83203125">key</th><th width="100.91796875">type</th><th width="265.79296875">description</th><th width="92.53515625">Required</th><th width="74.40234375">Default</th></tr></thead><tbody><tr><td>placeholder</td><td>object</td><td>Holds a placeholder text for the custom field component in different languages. de-DE and en-GB are required. You can add more translations if you want.</td><td>no</td><td></td></tr><tr><td>placeholder > de-DE</td><td>string</td><td>The placeholder of the custom field in german</td><td>yes</td><td></td></tr><tr><td>placeholder > en-GB</td><td>string</td><td>The placeholder of the custom field in english</td><td>yes</td><td></td></tr><tr><td>config > large</td><td>bool</td><td>If set to true a textarea is used in Shopware administration instead of a text field.</td><td>no</td><td>false</td></tr></tbody></table>

### Integer

```json
...
{
    "type": "int",
    "label": {
        "de-DE": "Mein CustomField",
        "en-GB": "My custom field"
    },
    "placeholder": {
        "de-DE": "Ein Platzhalter-Text",
        "en-GB": "A placeholder"
    },
    "config": {
        "max": 100,
        "min": 10,
        "step": 10,
        "allowEmpty": true
    }
}
...
```

<table><thead><tr><th width="203.83203125">key</th><th width="100.91796875">type</th><th width="265.79296875">description</th><th width="92.53515625">Required</th><th width="74.40234375">Default</th></tr></thead><tbody><tr><td>placeholder</td><td>object</td><td>Holds a placeholder text for the custom field component in different languages. de-DE and en-GB are required. You can add more translations if you want.</td><td>no</td><td></td></tr><tr><td>placeholder > de-DE</td><td>string</td><td>The placeholder of the custom field in german</td><td>yes</td><td></td></tr><tr><td>placeholder > en-GB</td><td>string</td><td>The placeholder of the custom field in english</td><td>yes</td><td></td></tr><tr><td>config > max</td><td>int</td><td>The maximum value</td><td>no</td><td></td></tr><tr><td>config > min</td><td>int</td><td>The minimum value</td><td>no</td><td></td></tr><tr><td>config > step</td><td>int</td><td>Step size of the values</td><td>no</td><td>1</td></tr><tr><td>config > allowEmpty</td><td>bool</td><td>If set to false an empty input field will be converted to 0 - null otherwise</td><td>no</td><td>false</td></tr></tbody></table>

### Float

```json
...
{
    "type": "float",
    "label": {
        "de-DE": "Mein CustomField",
        "en-GB": "My custom field"
    },
    "placeholder": {
        "de-DE": "Ein Platzhalter-Text",
        "en-GB": "A placeholder"
    },
    "config": {
        "max": 100.0,
        "min": 10.0,
        "step": 10.0,
        "allowEmpty": true,
        "digits": 5
    }
}
...
```

<table><thead><tr><th width="203.83203125">key</th><th width="100.91796875">type</th><th width="265.79296875">description</th><th width="92.53515625">Required</th><th width="74.40234375">Default</th></tr></thead><tbody><tr><td>placeholder</td><td>object</td><td>Holds a placeholder text for the custom field component in different languages. de-DE and en-GB are required. You can add more translations if you want.</td><td>no</td><td></td></tr><tr><td>placeholder > de-DE</td><td>string</td><td>The placeholder of the custom field in german</td><td>yes</td><td></td></tr><tr><td>placeholder > en-GB</td><td>string</td><td>The placeholder of the custom field in english</td><td>yes</td><td></td></tr><tr><td>config > max</td><td>float</td><td>The maximum value</td><td>no</td><td></td></tr><tr><td>config > min</td><td>float</td><td>The minimum value</td><td>no</td><td></td></tr><tr><td>config > step</td><td>float</td><td>Step size of the values</td><td>no</td><td></td></tr><tr><td>config > allowEmpty</td><td>bool</td><td>If set to false an empty input field will be converted to 0 - null otherwise</td><td>no</td><td>false</td></tr><tr><td>config > digits</td><td>int</td><td>Amount of allowed digits</td><td>no</td><td>4</td></tr></tbody></table>

### Selection

```json
...
{
    "type": "select",
    "label": {
        "de-DE": "Mein CustomField",
        "en-GB": "My custom field"
    },
    "placeholder": {
        "de-DE": "Ein Platzhalter-Text",
        "en-GB": "A placeholder"
    },
    "config": {
        "multiselect": true,
        "options": [
            {
                "value": "first-value",
                "label": {
                    "de-DE": "Erster Wert",
                    "en-GB": "First value"
                }
            }, 
            {
                "value": "second-value",
                "label": {
                    "de-DE": "Zweiter Wert",
                    "en-GB": "Second value"
                }
            }    
        ]
    }
}
...
```

<table><thead><tr><th width="203.83203125">key</th><th width="100.91796875">type</th><th width="265.79296875">description</th><th width="92.53515625">Required</th><th width="74.40234375">Default</th></tr></thead><tbody><tr><td>placeholder</td><td>object</td><td>Holds a placeholder text for the custom field component in different languages. de-DE and en-GB are required. You can add more translations if you want.</td><td>no</td><td></td></tr><tr><td>placeholder > de-DE</td><td>string</td><td>The placeholder of the custom field in german</td><td>yes</td><td></td></tr><tr><td>placeholder > en-GB</td><td>string</td><td>The placeholder of the custom field in english</td><td>yes</td><td></td></tr><tr><td>config > multiselect</td><td>bool</td><td>Boolean whether it should be possible to select multiple values</td><td>yes</td><td></td></tr><tr><td>config > options</td><td>array</td><td>A list of possible options</td><td>yes</td><td></td></tr><tr><td>config > options > value</td><td>string</td><td>The value which will be saved when this option was selected</td><td>yes</td><td></td></tr><tr><td>config > options > label</td><td>object</td><td>Holds a label for the option which will be displayed in the Shopware administration in different languages. de-DE and en-GB are required. You can add more translations if you want.</td><td>yes</td><td></td></tr><tr><td>config > options > label > de-DE</td><td>string</td><td>The option label in german</td><td>yes</td><td></td></tr><tr><td>config > options > label > en-GB</td><td>string</td><td>The option label in english</td><td>yes</td><td></td></tr></tbody></table>

### Colorpicker

```json
...
{
    "type": "colorpicker",
    "label": {
        "de-DE": "Mein CustomField",
        "en-GB": "My custom field"
    }
}
...
```

### Datetime

```json
...
{
    "type": "datetime",
    "label": {
        "de-DE": "Mein CustomField",
        "en-GB": "My custom field"
    },
    "placeholder": {
        "de-DE": "Ein Platzhalter-Text",
        "en-GB": "A placeholder"
    }
}
...
```

<table><thead><tr><th width="203.83203125">key</th><th width="100.91796875">type</th><th width="265.79296875">description</th><th width="92.53515625">Required</th><th width="74.40234375">Default</th></tr></thead><tbody><tr><td>placeholder</td><td>object</td><td>Holds a placeholder text for the custom field component in different languages. de-DE and en-GB are required. You can add more translations if you want.</td><td>no</td><td></td></tr><tr><td>placeholder > de-DE</td><td>string</td><td>The placeholder of the custom field in german</td><td>yes</td><td></td></tr><tr><td>placeholder > en-GB</td><td>string</td><td>The placeholder of the custom field in english</td><td>yes</td><td></td></tr></tbody></table>

### Entity selection

```json
...
{
    "type": "entity",
    "label": {
        "de-DE": "Mein CustomField",
        "en-GB": "My custom field"
    },
    "placeholder": {
        "de-DE": "Ein Platzhalter-Text",
        "en-GB": "A placeholder"
    },
    "config": {
        "entity": "product",
        "multiselect": false
    }
}
...
```

<table><thead><tr><th width="203.83203125">key</th><th width="100.91796875">type</th><th width="265.79296875">description</th><th width="92.53515625">Required</th><th width="74.40234375">Default</th></tr></thead><tbody><tr><td>placeholder</td><td>object</td><td>Holds a placeholder text for the custom field component in different languages. de-DE and en-GB are required. You can add more translations if you want.</td><td>no</td><td></td></tr><tr><td>placeholder > de-DE</td><td>string</td><td>The placeholder of the custom field in german</td><td>yes</td><td></td></tr><tr><td>placeholder > en-GB</td><td>string</td><td>The placeholder of the custom field in english</td><td>yes</td><td></td></tr><tr><td>config > entity</td><td>string</td><td>The name of the entity to select</td><td>yes</td><td></td></tr><tr><td>config > multiselect</td><td>bool</td><td>Boolean whether it should be possible to select multiple values</td><td>yes</td><td></td></tr></tbody></table>

### Price

```json
...
{
    "type": "price",
    "label": {
        "de-DE": "Mein CustomField",
        "en-GB": "My custom field"
    }
}
...
```

### HTML

```json
...
{
    "type": "html",
    "label": {
        "de-DE": "Mein CustomField",
        "en-GB": "My custom field"
    },
    "placeholder": {
        "de-DE": "Ein Platzhalter-Text",
        "en-GB": "A placeholder"
    }
}
...
```

<table><thead><tr><th width="203.83203125">key</th><th width="100.91796875">type</th><th width="265.79296875">description</th><th width="92.53515625">Required</th><th width="74.40234375">Default</th></tr></thead><tbody><tr><td>placeholder</td><td>object</td><td>Holds a placeholder text for the custom field component in different languages. de-DE and en-GB are required. You can add more translations if you want.</td><td>no</td><td></td></tr><tr><td>placeholder > de-DE</td><td>string</td><td>The placeholder of the custom field in german</td><td>yes</td><td></td></tr><tr><td>placeholder > en-GB</td><td>string</td><td>The placeholder of the custom field in english</td><td>yes</td><td></td></tr></tbody></table>

### Media selection

```json
...
{
    "type": "media",
    "label": {
        "de-DE": "Mein CustomField",
        "en-GB": "My custom field"
    }
}
...
```

### JSON

```json
...
{
    "type": "json",
    "label": {
        "de-DE": "Mein CustomField",
        "en-GB": "My custom field"
    },
    "placeholder": {
        "de-DE": "Ein Platzhalter-Text",
        "en-GB": "A placeholder"
    }
}
...
```

<table><thead><tr><th width="203.83203125">key</th><th width="100.91796875">type</th><th width="265.79296875">description</th><th width="92.53515625">Required</th><th width="74.40234375">Default</th></tr></thead><tbody><tr><td>placeholder</td><td>object</td><td>Holds a placeholder text for the custom field component in different languages. de-DE and en-GB are required. You can add more translations if you want.</td><td>no</td><td></td></tr><tr><td>placeholder > de-DE</td><td>string</td><td>The placeholder of the custom field in german</td><td>yes</td><td></td></tr><tr><td>placeholder > en-GB</td><td>string</td><td>The placeholder of the custom field in english</td><td>yes</td><td></td></tr></tbody></table>