Shoper Visual Editor Configuration Schema¶

Configuration contains a list of groups. Every group has a list of elements. Configuration is in JSON format.

Below you can see an example module image with groups and elements in groups. Elements can have children elements (more information you will find below in children section).

First ("Galeria zdjęć") and last section ("Widoczność na urządzeniach") for modules are build in groups. You cannot change them. You do not pass those build-in section in your JSON configuration. You can add list of groups only between those sections. If you are creating configuration for theme or JavaScript please check here which sections are build-in, and you do not need to put it in your JSON configuration.

On screen below we have two groups: Widok główny galerii and Widok pełnoekranowy. First group has 5 elements. Two elements (Urządzenia mobilne, Komputery) have children elements. Second group has 2 elements type of infobox and checkbox.

module

Below you can see example configuration that module.

Module configuration schema

[
  {
    "state":"unfolded",
    "label":"Gallery main view",
    "elements":[
      {
        "type" : "header",
        "name" : "header_mobile_devices",
        "label" : "Mobile devices",
        "options" : {
          "icon" : "mobile_devices"
        },
        "children": [
          {
            "type" : "checkbox",
            "name" : "navigation_arrows_mobile_devices",
            "label" : "Enable navigation arrows",
            "defaultValue" : 1
          }
        ]
      },
      {
        "type" : "header",
        "name" : "header_computers",
        "label" : "Computers",
        "options" : {
          "icon" : "computers"
        },
        "children": [
          {
            "type" : "checkbox",
            "name" : "navigation_arrows_computers",
            "label" : "Enable navigation arrows",
            "defaultValue" : 1
          },
          {
            "type" : "radio",
            "name" : "thumbnail_position",
            "label": "Thumbnail display position",
            "options": {
              "radioOptions" : [
                { "key" : "left", "label" : "On the left of the photo" },
                { "key" : "right", "label" : "On the right of the photo" },
                { "key" : "under", "label" : "Under the photo" }
              ]
            }
          }
        ]
      }
    ]
  },
  {
    "state": "unfolded",
    "label": "Full screen view",
    "elements": [
      {
        "type": "infobox",
        "name": "infobox",
        "options": {
          "type" : "warning",
          "message" : "Changes to the settings in this section will not be visible in the live view. To see the changes, save them, click \"Preview\" and click on the photo in the gallery."
        }
      },
      {
        "type" : "checkbox",
        "name" : "display_photo_description",
        "label" : "Display photo description \/ file name",
        "defaultValue" : 1
      }
    ]
  }
]

Group of elements¶

group1

Group schema

{
  "state": "unfolded",
  "label": "General settings",
  "elements": [
    {
      "type": "imageUpload",
      "name": "image",
      "label": "Image",
      "isRequired": true,
      "supportsTranslations": true,
      "hint": "The file name is important for SEO and should describe the content of the image. Use dashes to separate words.",
      "options": {
        "allowedExtensions": [
          "webp",
          "svg",
          "jpg",
          "png",
          "gif"
        ]
      }
    },
    {
      "type": "text",
      "name": "alt",
      "label": "Alternative image description (\"alt\")",
      "supportsTranslations": true,
      "isRequired": true,
      "hint": "Alternative text (\"alt\" attribute) should contain a description of what the graphic presents. This description is read by software for the blind and analyzed when search engines index the page."
    },
    {
      "type": "checkbox",
      "name": "allowImageAsLink",
      "label": "Image as a link",
      "supportsTranslations": true,
      "defaultValue": 1,
      "children": [
        {
          "type": "text",
          "name": "link",
          "label": "Webpage URL",
          "supportsTranslations": true,
          "options":
          {
            "placeholder" : "https://"
          },
          "relations": [
            {
              "parentName": "allowImageAsLink",
              "parentValueToActionsMap": [
                {
                  "value": 0,
                  "actions": [
                    "setHiddenAndOptional",
                    "setDisabled"
                  ]
                },
                {
                  "value": 1,
                  "actions": [
                    "setVisibleAndRequired",
                    "setAvailable"
                  ]
                }
              ]
            }
          ]
        },
        {
          "type": "checkbox",
          "name": "shouldOpenLinkInNewTab",
          "label": "Open the link in the same tab",
          "supportsTranslations": true,
          "hint": "Opening links in the same tab makes navigation easier: using the \"back\" button is possible. The customer can decide to open the page in a new tab.",
          "relations": [
            {
              "parentName": "allowImageAsLink",
              "parentValueToActionsMap": [
                {
                  "value": 0,
                  "actions": [
                    "setHidden",
                    "setDisabled"
                  ]
                },
                {
                  "value": 1,
                  "actions": [
                    "setVisible",
                    "setAvailable"
                  ]
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "type": "number",
      "name": "borderRadius",
      "label": "Round corners of the image",
      "labelDescription": "0% - rectangular, 100% - round image",
      "defaultValue": 0,
      "options": {
        "placeholder": "0%"
      }
    }
  ]
}

label¶

string Label for group of elements. For example: 'General settings'.

state¶

string State of group.

Available states:

static - group of elements will be shown and cannot be folded.
unfolded - group of elements will be unfolded, but user can fold that group.
folded - group of elements will be folded, but user can unfold that group.

elements¶

array List of elements.

Element¶

Element configuration

{
  "type" : "text", 
  "name" : "module_name",
  "label" : "Module label",
  "labelDescription" : "Additional description of label",
  "options" : {
    "prefix" : "+48",
    "placeholder" : "phone number"
  },
  "hint" : "Hint for element.",
  "relations" : [],
  "isHidden" : false,
  "isRequired" : true,
  "defaultValue" : "Default text",
  "supportsTranslations" : true,
  "validators" : [
    { "type" : "length", "options" : { "min" : 9, "max" : 12 }}
  ],
  "children": [
    { "type" : "text", "name" : "title", "label" : "Module title"},
    { "type" : "textarea", "name" : "description", "label" : "Module description"}
  ]
}

type¶

string Type of element. Depending on passed type, required fields for element may be different.

Available element types¶

options¶

array Options for element. Depending on passed element type, options may be different. For some elements this parameter is required. Refer to concrete element specification.

name¶

string Name of element. Name must be different for every element in configuration.

label¶

string Represents label which will be shown for user. For example if you choose checkbox element, this label will be shown next to input. Field is not required only for infobox element. Infobox does not use this field. Check out infobox documentation to find out more.

labelDescription¶

string Optional parameter. Represents additional information about element shown beneath label.

hint¶

string|array Optional parameter. This option will show question mark next to a label. When user will mouse over, tooltip with your hint will be shown.

If you want to use placeholders you need to pass array. If you do not use placeholders, pass string for hint.

JSON - hint as an array

{
  "hint" : {
    "message" : "Message as markdown with placeholders %s %s",
    "placeholderValues" : ["placeholder 1", "placeholder 2"]
  }
}

JSON - hint as a string

{
  "hint" : "Message as markdown"
}

For message in array and when hint is type of string you can pass Markdown.

placeholderValues represents list of placeholders (string, int, float) which will be placed in message. They are useful when you have for example links in message. If you place link in placeholderValues, in translations you do not need to pass links. To place placeholder in message is used printf function. For example if you want place text placeholder in message, you must put %s in your message. Whole documentation with list of parameters you can use, you can find here.

Example¶

Hint for element type of checkbox:

hint

hint for element

{
  "type": "text",
  "name": "alt",
  "label": "Alternative image description (\"alt\")",
  "supportsTranslations": true,
  "isRequired": true,
  "hint": "Alternative text (\"alt\" attribute) should contain a description of what the graphic presents. This description is read by software for the blind and analyzed when search engines index the page."
}

relations¶

array Optional parameter. List of relations. Represents that element is related to another element. Element can have multiple relations.

JSON

{
  "relations": [
    {
      "parentName" : "display_title",
      "parentValueToActionsMap" : [
        {
          "value" : "value1",
          "actions" : ["setDisabled"]
        },
        {
          "value" : "value2",
          "actions" : ["setAvailable"]
        }
      ]
    },
    {
      "parentName" : "display_all",
      "parentValueToActionsMap" : [
        {
          "value" : "value1",
          "actions" : ["setDisabled"]
        },
        {
          "value" : "value2",
          "actions" : ["setAvailable"]
        }
      ]
    }
  ]
}

relations.parentName¶

string Represents name of the parent element. Parent element must support relations. You can find this information in concrete element documentation in section Relations Support.

relations.parentValueToActionsMap¶

array Represents type of relation to parent.

JSON

{
  "value" : "value1",
  "actions" : ["setDisabled"]
}

value represents value of parent element on which this element have to react.

actions is a list of actions to do when parent element has concrete value.

Available actions:

setRequired - make this element required
setOptional - make this element optional
setVisible - make this element visible
setHidden - hide this element
setAvailable - make this element available
setDisabled - disable element, this element will be still visible but nobody can change value of this element
setHiddenAndOptional - make this element hidden and optional
setVisibleAndRequired - make this element visible and required

Example of relations

For example assume you have 2 elements in your group. Element type of `radio` and `text`. In radio element you define 2 options "list_of_products" and "url". When user clicks "list_of_products", you want to show text field to write additional info. When user clicks "url", you want to hide, disabled and make optional text element.

example

[
  {
    "state" : "unfolded",
    "label" : "Gallery main view",
    "elements" : [
      {
        "type" : "radio",
        "name" : "vendor_logo_click",
        "label" : "After clicking on the vendor's name\/logo, move to:",
        "defaultValue" : "url",
        "options" : {
          "radioOptions" : [
            {
              "key" : "list_of_products",
              "label" : "list of this vendor's products in the store (recommended)"
            },
            {
              "key" : "url",
              "label" : "URL address from vendor's settings (if added)"
            }
          ]
        }
      },
      { 
        "type" : "text", 
        "name" : "info", 
        "label" : "Additional info",
        "relations" : [
          {
            "parentName" : "vendor_logo_click",
            "parentValueToActionsMap" : [
              {
                "value" : "list_of_products",
                "actions" : ["setAvailable", "setRequired", "setVisible"]
              },
              {
                "value" : "url",
                "actions" : ["setDisabled", "setOptional", "setHidden"]
              }
            ]
          }
        ]
      }
    ]
  }
]

isHidden¶

bool Optional parameter. Defines if element will be hidden at the start. You can change the state by adding relations. Default value is false.

isRequired¶

bool Optional parameter. Defines if element is required. Default value is false.

defaultValue¶

mixed Optional parameter. Represents default value for element. If element is type of text this value will be in the input on start. If element is type of radio this value will represent chosen option.

supportsTranslations¶

bool Optional parameter. Defines if user can have different value for different languages.

For instance, suppose a shop has two languages.: PL, EN. Your element is type of text. When supportsTranslations is true, user can pass Dostawa for PL and Delivery for EN. When supportsTranslations is false, user can pass one value which will be shown on PL and EN version of a shop.

pl-version en-version

children¶

array Optional parameter. List of elements. Every element can have children elements. It is recommended to use one level of nest. More levels can make module unreadable. You can see how children elements are shown in the first image on this page.

Element with children configuration

{
  "type" : "text",
  "name" : "module_name",
  "label" : "Module label",
  "children" : [
    { "type" : "text", "name" : "title", "label" : "Module title" },
    { "type" : "textarea", "name" : "description", "label" : "Module description" }
  ]
}

validators¶

array Optional parameter. List of validators. For every element list of available validator may be different. Some elements do not have any available validators. If you use a validator that is not available for the element, you will receive an error message that your configuration is incorrect.

Shoper Visual Editor Configuration Schema¶

Group of elements¶

label¶

state¶

elements¶

Element¶

type¶

Available element types¶

options¶

name¶

label¶

labelDescription¶

hint¶

Example¶

relations¶

relations.parentName¶

relations.parentValueToActionsMap¶

isHidden¶

isRequired¶

defaultValue¶

supportsTranslations¶

children¶

validators¶

Available validators¶