Custom Data Fields

Overview

You can add custom fields to Shopware and thus add your own fields to extending data records. The user is able to modify this fields from within the Shopware Administration.

To make use of the custom fields, register your custom field sets in your manifest file:

<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-3.0.xsd">
    <meta>
        ...
    </meta>
    <custom-fields>
        <custom-field-set>
            <name>swag_example_set</name>
            <label>Example Set</label>
            <label lang="de-DE">Beispiel-Set</label>
            <related-entities>
                <order/>
            </related-entities>
            <fields>
                <text name="swag_code">
                    <position>1</position>
                    <label>Example field</label>
                </text>
            </fields>
        </custom-field-set>
    </custom-fields>
</manifest>

For a complete reference of the structure of the manifest file, take a look at the Manifest reference.

WARNING

Defining custom fields inline in manifest.xml via the <custom-fields> element is deprecated since Shopware 6.7.13.0 and will be removed in Shopware 6.8.0.0. Define your custom fields in a separate Resources/config/custom-fields.xml file instead (see below).

Defining custom fields in Resources/config/custom-fields.xml

INFO

Available starting with Shopware 6.7.13.0.

Instead of the inline <custom-fields> section in manifest.xml, you can define your custom field sets in a dedicated Resources/config/custom-fields.xml file at the root of your app. The format inside <custom-fields> is identical to the inline manifest definition:

<?xml version="1.0" encoding="UTF-8"?>
<custom-fields xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/System/CustomField/Schema/custom-fields-1.0.xsd">
    <!-- register each custom field set you may want to add -->
    <custom-field-set>
        <!-- the technical name of the custom field set, needs to be unique, therefore use your vendor prefix -->
        <name>swag_example_set</name>
        <!-- Translatable, the label of the field set -->
        <label>Example Set</label>
        <label lang="de-DE">Beispiel-Set</label>
        <!-- define the entities to which your field set should be assigned -->
        <related-entities>
            <product/>
        </related-entities>
        <!-- define the fields in your set -->
        <fields>
            <!-- the element type defines the type of the field -->
            <!-- the name needs to be unique, therefore use your vendor prefix -->
            <int name="swag_example_weight">
                <!-- Translatable, the label of the field -->
                <label>Weight</label>
                <!-- Optional, Default = 1, order your fields by specifying the position -->
                <position>1</position>
            </int>
            <text name="swag_example_code">
                <label>Example field</label>
                <position>2</position>
                <!-- Optional, Default = false, mark a field as required -->
                <required>false</required>
                <!-- Optional, Translatable, the help text for the field -->
                <help-text>Example field</help-text>
            </text>
        </fields>
    </custom-field-set>
</custom-fields>

When both a Resources/config/custom-fields.xml file and an inline <custom-fields> section in manifest.xml are present, the separate file takes priority. If only the inline definition exists, a deprecation warning is triggered. The same file format is also available for plugins.

For the data needed, please refer to the custom fields in general: At first, you need a custom field set, as custom fields in Shopware are organised in sets. Here you need to consider some important fields:

• name: A technical name for your set
• label: This element provides the label of the text and can be used for defining translations of the label as well.
• related-entities: With this element set the entities the custom field set is used in
• fields: Finally, the fields are configured in this section.

WARNING

The names of the custom fields are global and therefore should always contain a vendor prefix, like "swag" for "shopware ag", to keep them unique. This holds true for the name of the custom field set, as well as each name of the fields itself.

When defining custom fields in the <fields> element, you can configure additional properties of the fields. For example a placeholder, min, max and step size of a float field:

<float name="swag_test_float_field">
    <label>Test float field</label>
    <label lang="de-DE">Test-Kommazahlenfeld</label>
    <help-text>This is an float field.</help-text>
    <position>2</position>
    <placeholder>Enter an float...</placeholder>
    <min>0.5</min>
    <max>1.6</max>
    <steps>0.2</steps>
</float>

Refer to the custom field documentation for further details.