Add Plugin Configuration
The Shopware plugin system
provides you with the option to create a configuration page for your plugin without any knowledge of templating or the Shopware Administration
.
Prerequisites
To build your own configuration page for your plugin, you first need a plugin as base. Therefore, you can refer to the Plugin Base Guide.
Create your plugin configuration
Backend Development - Adding a plugin configuration - YouTube
INFO
This video is part of the online training "Backend Development" available on Shopware Academy for free.
All you need to do is create a config.xml
file inside a Resources/config
directory in your plugin root. The content of the config.xml
will be dynamically rendered in the Administration. Below you'll find an example structure:
└── plugins
└── SwagBasicExample
├── src
│ ├── Resources
│ │ └── config
│ │ └── config.xml
│ └── SwagBasicExample.php
└── composer.json
Fill your plugin configuration with settings
As you now know how to create configurations, you can start to fill it with life using various configuration options.
Cards in your configuration
The config.xml
follows a simple syntax. You can organize the content in <card>
elements. Every config.xml
must contain a minimum of one <card>
element and each <card>
must contain one <title>
and at least one <input-field>
. See the minimum config.xml
below:
<!--<plugin root>/src/Resources/config/config.xml-->
<?xml version="1.0" encoding="UTF-8"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/System/SystemConfig/Schema/config.xsd">
<card>
<title>Minimal configuration</title>
<input-field>
<name>example</name>
</input-field>
</card>
</config>
Please make sure to specify the xsi:noNamespaceSchemaLocation
as shown above and fetch the external resource into your IDE if possible. This enables auto-completion and suggestions for this XML file and will therefore help you to prevent issues and bugs.
Card Titles
A <card>
<title>
is translatable, this is managed via the lang
attribute. By default, the lang
attribute is set to en-GB
, to change the locale of a <title>
just add the attribute as follows:
...
<card>
<title>English Title</title>
<title lang="de-DE">German Titel</title>
</card>
...
Input fields
As you can see above, every <input-field>
has to contain at least a <name>
element. The <name>
element is not translatable and has to be unique, since it will be used as the technical identifier for the config element. The field <name>
must at least be 4 characters long and consist of only lower and upper case letters. It can contain numbers, but not at first place - see this RegEx pattern: [a-zA-Z][a-zA-Z0-9]*
The different types of input field
Your <input-field>
can be of different types, this is managed via the type
attribute. Unless defined otherwise, your <input-field>
will be a text field. Below you'll find a list of all available <input-field type="?">
.
Type | Configuration settings | Renders | Default value example |
---|---|---|---|
text | copyable, placeholder, length | Text field | Some text |
textarea | copyable, placeholder | Text area | Some more text |
text-editor | placeholder | HTML editor | Some text with HTML <div> tags</div> |
url | copyable, placeholder, length | URL field | https://example.com |
password | placeholder, length | Password field | ******** |
int | length | Number field | 42 |
float | length | Number field | 42.42 |
bool | Switch | true or false | |
checkbox | Checkbox | true or false | |
datetime | Date-time picker | 2024-04-04T12:00:00.000Z | |
date | Date picker | 2024-04-05T00:00:00 | |
time | Time picker | 11:00:00 | |
colorpicker | Color picker | #189EFF | |
single-select | options, placeholder | Single-Select box | option_id |
multi-select | options, placeholder | Multi-Select box | [option_id1, option_id2] |
Input field settings
These settings are used to configure your <input-field>
. Every <input-field>
has to start with the <name>
element. After the <name>
element you can configure any of the other settings mentioned above. Beside these settings, they have the following in common: label, helpText, defaultValue, disabled, and required.
Label, placeholder and help text
The settings <label>
, <placeholder>
and <helpText>
are used to label and explain your <input-field>
and are translatable. You define your <label>
, <placeholder>
and <helpText>
the same way as the <card><title>
, with the lang
attribute. Please remember, that the lang
attribute is set to en-GB
per default.
defaultValue
Add the defaultValue
setting to your <input-field>
to define a default value for it. This value will be imported into the database on installing and updating the plugin. We use Symfony\Component\Config\Util\XmlUtils for casting the values into the correct PHP types.
Below, you'll find an example of how to use this setting.
<input-field type="text">
<name>textField</name>
<label>Test field with default value</label>
<defaultValue>test</defaultValue>
</input-field>
disabled
You can add the <disabled>
setting to any of your <input-field>
elements to disable it.
Below, you'll find an example of how to use this setting.
<input-field>
<name>email</name>
<disabled>true</disabled>
</input-field>
Please note, <disabled>
only accepts boolean values.
required
You can add the <required>
setting to any of your <input-field>
elements to mark it accordingly.
Below, you'll find an example of how to use this setting.
<input-field>
<name>email</name>
<required>true</required>
</input-field>
Please note, <required>
only accepts boolean values.
copyable
You can add the <copyable>
setting to your <input-field>
which are of type text
or extensions of it. This will add a button at the right, which on click copies the content of your <input-field>
into the clipboard.
Below, you'll find an example of how to use this setting.
<input-field>
<name>email</name>
<copyable>true</copyable>
</input-field>
Please note, that <copyable>
only accepts boolean values
Text length restrictions
You can add the <minLength>
/<maxLength>
settings to your <input-field>
which are of type text
, url
or password
. With those you can restrict the length of the input.
Below, you'll find an example of how to use this setting.
<input-field type="password">
<name>token</name>
<minLength>5</minLength>
<maxLength>20</maxLength>
</input-field>
Number length restrictions
You can add the <min>
/<max>
settings to your <input-field>
which are of type int
or float
. With those you can restrict the minimum and maximum value of the input.
Below, you'll find an example of how to use this setting.
<input-field type="int">
<name>token</name>
<min>5</min>
<max>20</max>
</input-field>
options
You can use <options>
to add settings to a <input-field>
of the types single-select
and multi-select
. Each <option>
represents one setting you can select.
Below you'll find an example.
<input-field type="single-select">
<name>mailMethod</name>
<options>
<option>
<id>smtp</id>
<name>English label</name>
<name lang="de-DE">German label</name>
</option>
<option>
<id>pop3</id>
<name>English label</name>
<name lang="de-DE">German label</name>
</option>
</options>
</input-field>
Each <options>
element must contain at least one <option>
element. Each <option>
element must contain at least one <id>
and one <name>
element. As you can see above, <name>
elements are translatable via the lang
attribute.
Advanced custom input fields
For more complex and advanced configurations it is possible to declare a <component name="componentName">
element. This element can render many admin components. It is also possible to render your own admin component which you could deliver with your plugin. The name of the component has to match the components name in the Administration, for example sw-entity-single-select
. The component also needs a <name>
element first. All other elements within the component element will be passed to the rendered admin component as properties. For some components you could also use label
and placeholder
.
Here are some examples:
Entity single select for products
<component name="sw-entity-single-select">
<name>exampleProduct</name>
<entity>product</entity>
<label>Choose a product for the plugin configuration</label>
</component>
Stores the ID of the selected product into the system config.
Entity multi ID select for products
<component name="sw-entity-multi-id-select">
<name>exampleMultiProductIds</name>
<entity>product</entity>
<label>Choose multiple products IDs for the plugin configuration</label>
</component>
Stores an array with IDs of the selected products into the system config.
Media selection
<component name="sw-media-field">
<name>pluginMedia</name>
<label>Upload media or choose one from the media manager</label>
</component>
Text editor
<component name="sw-text-editor">
<name>textEditor</name>
<label>Write some nice text with WYSIWYG editor</label>
</component>
Snippet field
<component name="sw-snippet-field">
<name>snippetField</name>
<label>Description</label>
<snippet>myPlugin.test.snippet</snippet>
</component>
Allows you to edit snippet values within the configuration page. This component does not store values in the system config, but changes the translations for the snippet key. Note: This field is only available from 6.3.4.0 onward.
Supported component types
Please Note: It is impossible to allow every component in the config.xml
, due to their complexities. If you can't efficiently resolve your plugin's necessities with, it is probably better to create an own module instead. Therefore, Shopware supports the following components by default (also to be found in the ConfigValidator class):
- sw-entity-single-select
- sw-entity-multi-id-select
- sw-media-field
- sw-text-editor
- sw-snippet-field
Example
Now all that's left to do is to present you a working example config.xml
and show you the result.
<!--<plugin root>/src/Resources/config/config.xml-->
<?xml version="1.0" encoding="UTF-8"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/System/SystemConfig/Schema/config.xsd">
<card>
<title>Basic Configuration</title>
<title lang="de-DE">Grundeinstellungen</title>
<input-field>
<name>email</name>
<copyable>true</copyable>
<label>eMail address</label>
<label lang="de-DE">E-Mailadresse</label>
<placeholder>you@example.com</placeholder>
<placeholder lang="de-DE">du@beispiel.de</placeholder>
<helpText>Please fill in your personal eMail address</helpText>
<helpText lang="de-DE">Bitte trage deine persönliche E-Mailadresse ein</helpText>
</input-field>
<input-field type="single-select">
<name>mailMethod</name>
<options>
<option>
<id>smtp</id>
<name>English smtp</name>
<name lang="de-DE">German smtp</name>
</option>
<option>
<id>pop3</id>
<name>English pop3</name>
<name lang="de-DE">German pop3</name>
</option>
</options>
<defaultValue>smtp</defaultValue>
<label>Mail method</label>
<label lang="de-DE">Versand-Protokoll</label>
</input-field>
</card>
<card>
<title>Advanced Configuration</title>
<title lang="de-DE">Erweiterte Einstellungen</title>
<input-field type="password">
<name>secret</name>
<label>Secret token</label>
<label lang="de-DE">Geheimschlüssel</label>
<helpText>Your secret token for xyz...</helpText>
<helpText lang="de-DE">Dein geheimer Schlüssel für xyz...</helpText>
</input-field>
</card>
</config>
Add values to your configuration
After adding your input fields to the config.xml
, you can add values to your configuration. To do so, navigate from the sidebar to the Extensions
> My extensions
> Apps
tab and click Configure
. Now you can see the Configuration
tab and fill in the values for your input fields.
Next steps
Now you've added your own plugin configuration. But how do you actually read which configurations the shop owner used? This will be covered in our guide about Using the plugin configuration.