Is this article helpful?
 
(optional) let us know why:

Plugin configuration - config.json

Format of the plugin configuration file

The new format beginning with formatVersion 1.0 provides:

  • versioning to ensure backwards compatibility
  • multilingualism
  • unlimited menu nesting levels
  • new configuration field types
  • structured definitions of your configuration and configuration fields

The old format is still supported.

If you are using the old format, see this page for the old plugin configuration.

You can convert your config.json to the new format with this tool.

Each configuration needs the following properties:

PluginXY/config.json
{
  "formatVersion": 1.0,
  "menu": {
     "global": {
        "label": "Config.global",
        "fullWidth": true,
        "formFields": {
           "global.headerLogo": {
              "type": "inputFile",
              "required": true,
              "label": "Config.globalHeaderLogoLabel",
              "options": {
                 "tooltip": "Config.globalHeaderLogoTooltip",
                 "defaultValue": ""
              }
           },
           "global.category": {
              "type": "categoryPicker",
              "required": true,
              "label": "Config.globalCategoryLabel",
              "options": {
                 "tooltip": "Config.globalCategoryTooltip",
                 "defaultValue": ""
              }
           },
           "global.container": {
              "type": "verticalContainer",
              "label": "Config.globalContainerLabel",
              "options": {
                 "containerEntries":
                 {
                    "global.container.apiKey": {
                       "type": "inputText",
                       "label": "Config.globalContainerApiKeyLabel",
                       "required": false
                    }
                 }
              }
           }
        }
     },
     "additional": {
        "label": "Config.additionalSettings",
        "menu": {
           "languages": {
              "label": "Config.additionalSettingsLanguagesLabel",
              "formFields": {
                 "additional.languages.supportedLanguages": {
                    "type": "multiCheckBox",
                    "required": false,
                    "label": "Config.additionalSettingsSupportedLanguagesLabel",
                    "options": {
                       "tooltip": "Config.additionalSettingsSupportedLanguagesTooltip",
                       "defaultValue": "de, en",
                       "checkBoxValues": [
                          {
                             "value": "de",
                             "caption":"Config.languageGerman"
                          },
                          {
                             "value": "en",
                             "caption": "Config.languageEnglish"
                          },
                          {
                             "value": "fr",
                             "caption": "Config.languageFrench"
                          },
                          {
                             "value": "es",
                             "caption": "Config.languageSpanish"
                          }
                       ]
                    }
                 }
              }
           },
           "moreSettings": {
              "label": "Config.additionalSettingsMoreLabel",
              "formFields": {
                 "additional.more.fulfillmentClient": {
                    "type": "selectBox",
                    "required": false,
                    "label": "Config.additionalSettingsMoreFulfillmentClientLabel",
                    "options": {
                       "tooltip": "Config.additionalSettingsMoreFulfillmentClientTooltip",
                       "defaultValue": "dhl",
                       "selectBoxValues": [
                          {
                             "value": "dhl",
                             "caption": "Config.fulfillmentDHL"
                          },
                          {
                             "value": "ups",
                             "caption": "Config.fulfillmentUPS"
                          },
                          {
                             "value": "hermes",
                             "caption": "Config.fulfillmentHermes"
                          },
                          {
                             "value": "dpd",
                             "caption": "Config.fulfillmentDPD"
                          }
                       ]
                    }
                 }
              }
           }
        }
     }
  }
}

The key menu states whether the following value is interpreted as a menu entry. A menu entry must have a label property and can have another menu or formFields or a fullWidth property. With another menu property, a new menu level is created. With fullWidth set to true, the configuration is rendered with 100% width. Default value for fullWidth is false.

The formFields property must be an object containing all the form fields to be shown when clicking on the related menu entry. Every key in this object corresponds to the configuration field’s key defined by the plugin. A form field has the following properties:

  • type
  • required
  • label
  • options

The options property can include more properties that are optional, e.g.:

  • tooltip
  • defaultValue
  • checkBoxValues, selectBoxValues or containerEntries

The following types are available:

  • inputFile
  • inputText
  • inputTextArea
  • inputNumber
  • inputDouble
  • categoryPicker
  • colorPicker
  • datePicker
  • checkBox
  • selectBox
  • multiCheckBox
  • verticalContainer
  • horizontalContainer

Vertical and horizontal containers offer more flexibility for the layout of the configuration view. In a specific menu entry, form fields can be grouped in vertical and horizontal containers. Next to the label property the options.containerEntries property must be set. The containerEntries property contains the form fields that should be grouped in the corresponding container.

Default values of the picker elements

The various picker elements use the following default values:

  • categoryPicker: the id of the proposed category
  • colorPicker: the color code in hex format as string, e.g. “#ffffff”
  • datePicker: the date in RFC2822 or ISO 8601 date format (with time) as string

Accessing plugin options from PhpClass.php

// access configuration from PHP
function getTitle(ConfigRepository $config):string
    {
        if( $config->get('MyPlugin.show_title') == "1" )
            {
                return $config->get('MyPlugin.title_text');
                    }
                        else
                    {
                return "";
            }
    }

Accessing plugin options from Template.twig


{% if config('MyPlugin.show_title') == "1" %}
    <h1>{{ config('MyPlugin.title_text') }}</h1>
{% endif %}