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:

my_custom_field_set.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"
    ]
}

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>

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:

key	type	description	Required	Default
name	string	The name of the custom field set. Must be identical to the json file name	yes
label	object	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.	yes
label > de-DE	string	The label in german	yes
label > en-GB	string	The label in english	yes
translated	bool	Bool whether the custom field set should be translated or not	yes
editable	bool	If set to false users are not able to edit or delete the custom field set in administration	no	false
position	integer	The position of the custom field set on entity detail pages	no	1
customFields	object	An object containing the custom fields with the property name as the custom field name.	yes
relations	array of strings	A list of all entity names related to this custom field set	yes

Custom fields

Custom fields are located under the customFields key of your custom field set json file.

...
{
    "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.

key	type	description	Required	Default
type	string	The type of the custom field. Must be one of: - bool - colorpicker - datetime - entity - float - int - price - html - media - select - text - json	yes
allowStoreApiWrite	bool	Boolean whether the custom field should be modifyable via store api	no	false
allowCartExpose	bool	Boolean whether the custom field should be available in carts	no	false
position	integer	The position of the custom field in the administration	no	1
label	object	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.	yes
label > de-DE	string	The label of the custom field in german	yes
label > en-GB	string	The label of the custom field in english	yes
helpText	object	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.	no
helpText > de-DE	string	The help text in german	yes
helpText > en-GB	string	The help text in english	yes
required	bool	A boolean whether the custom field is a required field	no	false

Custom field types

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

Boolean

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

key	type	description	Required	Default
config > component	string	"switch" or "checkbox". The component to use in the Shopware administration	yes

Text

...
{
    "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
    }
}
...

key	type	description	Required	Default
placeholder	object	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.	no
placeholder > de-DE	string	The placeholder of the custom field in german	yes
placeholder > en-GB	string	The placeholder of the custom field in english	yes
config > large	bool	If set to true a textarea is used in Shopware administration instead of a text field.	no	false

Integer

...
{
    "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
    }
}
...

key	type	description	Required	Default
placeholder	object	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.	no
placeholder > de-DE	string	The placeholder of the custom field in german	yes
placeholder > en-GB	string	The placeholder of the custom field in english	yes
config > max	int	The maximum value	no
config > min	int	The minimum value	no
config > step	int	Step size of the values	no	1
config > allowEmpty	bool	If set to false an empty input field will be converted to 0 - null otherwise	no	false

Float

...
{
    "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
    }
}
...

key	type	description	Required	Default
placeholder	object	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.	no
placeholder > de-DE	string	The placeholder of the custom field in german	yes
placeholder > en-GB	string	The placeholder of the custom field in english	yes
config > max	float	The maximum value	no
config > min	float	The minimum value	no
config > step	float	Step size of the values	no
config > allowEmpty	bool	If set to false an empty input field will be converted to 0 - null otherwise	no	false
config > digits	int	Amount of allowed digits	no	4

Selection

...
{
    "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"
                }
            }    
        ]
    }
}
...

key	type	description	Required	Default
placeholder	object	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.	no
placeholder > de-DE	string	The placeholder of the custom field in german	yes
placeholder > en-GB	string	The placeholder of the custom field in english	yes
config > multiselect	bool	Boolean whether it should be possible to select multiple values	yes
config > options	array	A list of possible options	yes
config > options > value	string	The value which will be saved when this option was selected	yes
config > options > label	object	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.	yes
config > options > label > de-DE	string	The option label in german	yes
config > options > label > en-GB	string	The option label in english	yes

Colorpicker

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

Datetime

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

key	type	description	Required	Default
placeholder	object	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.	no
placeholder > de-DE	string	The placeholder of the custom field in german	yes
placeholder > en-GB	string	The placeholder of the custom field in english	yes

Entity selection

...
{
    "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
    }
}
...

key	type	description	Required	Default
placeholder	object	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.	no
placeholder > de-DE	string	The placeholder of the custom field in german	yes
placeholder > en-GB	string	The placeholder of the custom field in english	yes
config > entity	string	The name of the entity to select	yes
config > multiselect	bool	Boolean whether it should be possible to select multiple values	yes

Price

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

HTML

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

key	type	description	Required	Default
placeholder	object	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.	no
placeholder > de-DE	string	The placeholder of the custom field in german	yes
placeholder > en-GB	string	The placeholder of the custom field in english	yes

Media selection

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

JSON

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

key	type	description	Required	Default
placeholder	object	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.	no
placeholder > de-DE	string	The placeholder of the custom field in german	yes
placeholder > en-GB	string	The placeholder of the custom field in english	yes