Plugin configuration

This document will give you a brief introduction about how to set configuration options for legacy plugins, which parameters are available and how to use them. By using the new plugin system (since 5.2) the following code examples are deprecated. With the new plugin system all configurations can be done with help of config.xml file resulting in the examples shown here.

Introduction

After getting a short introduction by reading the Plugin Quick Introduction, we will now be introduced to the configuration options for plugins. Shopware delivers a big amount of helper functions for generating standard configuration fields in backend.

Creating forms

A plugin configuration can be created with a Resources/config.xml file.

<?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/5.2/engine/Shopware/Components/Plugin/schema/config.xsd">
    <elements>

    </elements>
</config>

Now add elements in the elements tag.

A textfield would be defined as followed:

<?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/5.2/engine/Shopware/Components/Plugin/schema/config.xsd">
    <elements>
        <element required="true" type="text" scope="locale">
            <name>simpleTextField</name>
            <label lang="de">Text</label>
            <label lang="en">Text</label>
            <value>preselection</value>
            <description lang="de">Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut.</description>
            <description lang="en">Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut.</description>
        </element>
    </elements>
</config>

Which would lead to a simple textfield.

Simple textfield

Options Parameter

The options parameter of the setElement function allows to set several configurations on the form element.

Label

The label parameter allows to create a simple descriptional label for the form element.

<label lang="de">Dein Label</label>
<label lang="en">Your label</label>

Textfield with label

Value

The value parameter stands for the default value of the field if this hasn´t been edited yet. It will directly be shown in the configuration element.

<value>preselection</value>

Textfield with default value

Required

The required attribute specifies whether the configuration item is mandatory or not.

<element required="true" ... >

Textfield marked as required

Scope

With help of the scope parameter it is possible to generate subshop specific configurations. Leaving this option out results in a configuration option that applies for all subshops.

 <element ... scope="locale">

Configuration with scope

You can read more on subshop specific configuration at the end of this article reading the Subshop specific configuration part.

Description

The description parameter allows to provide a more detailed description of the configuration element.

<description lang="de">Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut.</description>
<description lang="en">Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut.</description>

Textfield with description

Element Types

Below all supported configuration elements including their design and source code are described again.

Colorpicker

<element required="true" type="color">
    ...
</element>

Colorpicker

Datefield

<element required="true" type="date">
    ...
</element>

Datefield

Datetime field

<element required="true" type="datetime">
    ...
</element>

Datetime field

HTML editor

<element required="true" type="html">
    ...
</element>

HTML editor

Time interval

<element required="true" type="interval">
    ...
</element>

Time interval

Mediaselection

<element required="true" type="mediaselection">
    ...
</element>

Mediaselection

Numberfield

<element required="true" type="number">
    ...
</element>

Numberfield

Selectionfield / combobox

<element required="true" type="select" >
    <store>
        <option>
            <value>1</value>
            <label lang="de">DE 1</label>
            <label lang="en">EN 1</label>
        </option>
        <option>
            <value>TWO</value>
            <label lang="de">DE 2</label>
            <label lang="en">EN 2</label>
        </option>
        <option>
            <value>3</value>
            <label>Test</label>
        </option>
        <option>
            <value>4</value>
            <label>Test default</label>
            <label lang="de">Test</label>
        </option>
    </store>
</element>

Combobox

Selectionfield / remote combobox

<element required="true" type="combo">
    ...
    <store>Shopware.apps.Base.store.CustomerGroup</store>
</element>

Remotecombobox

Textfield

<element required="true" type="text">
    ...
</element>

Textfield

Textarea

<element required="true" type="textarea">
    ...
</element>

Textarea

Timefield

<element required="true" type="time">
    ...
</element>

Timefield

Configure basic settings

The plugin configurations of the various plugins are automatically reachable via the basic settings under the "Additional settings" entry:

<?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/5.2/engine/Shopware/Components/Plugin/schema/config.xsd">
    <elements>
        <element required="true" type="text" scope="locale">
            <name>simpleTextField</name>
            <label lang="de">Text</label>
            <label lang="en">Text</label>
            <value>preselection</value>
            <description lang="de">Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut.</description>
            <description lang="en">Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut.</description>
        </element>
    </elements>
</config>

Plugin configuration in base settigns

Subshop specific plugin configuration

In this chapter we want to show how to make your configurations subshop specific. To demonstrate this we write a little plugin which replaces the Shopware logo with random text.

<?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/5.2/engine/Shopware/Components/Plugin/schema/config.xsd">
    <elements>
        <element required="false" type="boolean" scope="shop">
            <name>show</name>
            <label lang="de">Anzeigen</label>
            <label lang="en">Show</label>
            <description lang="de">Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut.</description>
            <description lang="en">Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut.</description>
        </element>
    </elements>
</config>

With the help of the scope parameter we can assign configurations per subshop. Without the scope parameter the configuration is used in all subshops. We´ve mentioned this earlier this article.

public function onPostDispatch(Enlight_Event_EventArgs $arguments)
{
    $config = $this->container->get('shopware.plugin.config_reader')->getByPluginName('PluginName');
    if (empty($config->show)) {
        return;
    }
 
    $controller = $arguments->getSubject();
    $view = $controller->View();
 
    $view->assign('swagSubshopVisibility', 'Test text.');
 
    $view->addTemplateDir($this->pluginBasePath . '/Resources/views/');
}

Within the onPostDispatch() method in a subscriber read the configuration with help of the service. Afterwards we test for the just created show attribute. If this attribute is empty the method ends and the plugin will not be executed or shown any further. If show is set the template is loaded and assigned via smarty.

{extends file="parent:frontend/index/logo-container.tpl"}
{block name="frontend_index_logo"}
    <div style="padding-top: 10px">
        <h1>{$swagSubshopVisibility}</h1>
    </div>
{/block}

Our new template extends the parent logo-container.tpl and overwrites the frontend_index_logo block and sets the text. Now we can open the plugin configuration via Plugin Manager and configure it differently for every subshop.

What's next? Continue reading about the new Shopware 5.2 Plugin System.