Url¶

Url element is a link input. The merchant can type an external URL or a relative path, or pick a shop object (information page, category, product, bundle) from a list that opens after typing /. A picked object is stored as a reference (shoper://product/123) and resolved to the object's URL in the rendered language when the module is rendered. A product or category reference works for every language of the shop; an information page is a separate object per language, so its reference has to be set in every language of the module (see Element value).

The element is available behind the sve_dev_url_picker feature flag. While the flag is off a schema with url is rejected ("Element type 'url' is not available."), and a stored url element renders in the editor as a plain text input with the url validator; stored references keep working on the storefront regardless of the flag. The built-in modules button, picture, icon_with_text, countdown_timer and list_context_products keep text in their stored schema and get the url element only while the flag is on. url is supported in module schemas only: a skin settings schema rejects it regardless of the flag ("Element type "url" is not allowed."), and the skin style schema accepts a fixed list of types without it.

Switching the flag off converts the stored data, once before the switch and once more right after it (to catch anything saved meanwhile): every shoper://… reference in module values — instances and the per-skin values of integration modules — becomes the object's address in each active language, and every url element in a stored module schema — at the top level, in children and in the sub-schemas of repeater and deviceDependent (options.elements), together with the values in their rows and devices — becomes text with the url validator. A reference the schema does not describe (a removed field, a language the shop no longer has) is blanked. A module's schema is converted only once every value row of it converted; a row that fails leaves the flag on and the next attempt converts the module again. A row that cannot be read is skipped unless it can hold a reference or a url element. The conversion is one-way — switching the flag back on does not bring the references back — and a reference to an object that no longer exists becomes an empty value.

References never leave the shop: skin and application export write the objects' addresses instead (in instance values, in schema defaultValue and in predefined links; a predefined link to an object that no longer exists is removed). A module schema with url imported while the flag is off is stored with text and the url validator (a reference in defaultValue is dropped).

Options¶

prefix¶

string Optional parameter.

postfix¶

string Optional parameter.

placeholder¶

string Optional parameter. Placeholder in input.

sections¶

array Optional parameter. Which groups of shop objects the picker offers. Allowed values: infoPage, category, product (regular products and gift cards), bundle. Default: all four. An empty array hides the shop objects and leaves only links.

links¶

array Optional parameter. Predefined links offered by the picker. Every entry has a label (translated like other schema phrases) and a url, which may be an external URL, a relative path or an object reference, and may have a group (translated as well). Entries sharing a group form a group of their own, listed after the shop sections and opened with /<group label in lowercase, spaces as dashes> (e.g. /documents); entries without group are listed directly in the picker and selected with one click. A group label equal to a shop section keyword does not form a group: its entries are listed directly.

An entry from links is always accepted on save, regardless of sections and isCustomUrlAllowed, and an object reference in links is not checked against the shop's data. Object ids are per shop, so a reference in links (e.g. shoper://infoPage/1) only makes sense in a module built for one particular shop; a module installed in many shops should list external URLs or relative paths there.

isCustomUrlAllowed¶

bool Optional parameter, default true. When false, only entries from the picker (shop objects and links) are accepted; a URL typed by hand is rejected on save.

JSON

{
  "options":
    {
      "placeholder" : "https:// or /",
      "sections" : ["product", "category"],
      "links" : [
        { "label" : "Terms and conditions", "url" : "shoper://infoPage/1", "group" : "Documents" },
        { "label" : "Privacy policy", "url" : "shoper://infoPage/2", "group" : "Documents" },
        { "label" : "Contact", "url" : "/contact" }
      ],
      "isCustomUrlAllowed" : true
    }
}

Build-in Validators¶

Element has build-in validators:

text type
link: an external URL, a relative path starting with /, or an object reference whose object exists. The reference type must match sections unless the value is one of the links entries, and with isCustomUrlAllowed: false a hand-typed URL is rejected. A links entry is accepted as it is. defaultValue in the schema is checked for syntax and sections only, not for the object's existence, so a schema stays valid in every shop. Without the sve_dev_url_picker flag the editor shows a plain text input, so sections and isCustomUrlAllowed are not enforced on save.

Available Validators¶

Element has available validators:

length

Relations Support¶

Element supports relations between elements.

Configuration output schema¶

schema

{
  "<element_type>" : "url",
  "<element_name>" : string,
  "<element_label>" : string,
  "<element_labelDescription>" : string,
  "<element_isRequired>" : bool,
  "<element_isHidden>" : bool,
  "<element_supportsTranslations>" : bool,
  "<element_defaultValue>" : string,
  "<element_options>" : {
    "<element_option_prefix>" : string,
    "<element_option_postfix>" : string,
    "<element_option_placeholder>" : string,
    "<element_option_sections>" : [string],
    "<element_option_links>" : [{ "label" : string, "url" : string, "group" : string }],
    "<element_option_isCustomUrlAllowed>" : bool
  },
  "<element_validators>" : []
}

example

{
  "type" : "url",
  "name" : "url",
  "label" : "Webpage URL",
  "isRequired" : true,
  "supportsTranslations" : true,
  "options": {
    "placeholder" : "https:// or /"
  }
}

Element value¶

If value is filled: string with the final URL. A stored reference is replaced by the object's URL for the rendered language (own SEO route when the object has one). When the object does not exist, is inactive or has no translation in that language, the value is an empty string, so the template should guard the link.

Keep the field translatable (supportsTranslations) when the module may also link to external pages that differ per language. A product or category reference inherited from the default language resolves correctly in every language. An information page is a separate object per language, so its reference resolves only in the language of that page: inherited by another language it renders as an empty string, and the merchant has to pick the page of that language separately.

usage in module TWIG

{% if moduleConfig.url %}
    <a href="{{ moduleConfig.url }}">{{ moduleConfig.label }}</a>
{% endif %}

Example of module¶

Twig¶

Twig

{% if moduleConfig.url %}
    <a class="button" href="{{ moduleConfig.url }}">{{ moduleConfig.label }}</a>
{% endif %}

JSON configuration¶

JSON configuration

[
  {
    "label": "Button",
    "state": "unfolded",
    "elements": [
      {
        "type": "text",
        "name": "label",
        "label": "Button label",
        "isRequired": true,
        "supportsTranslations": true
      },
      {
        "type": "url",
        "name": "url",
        "label": "Webpage URL",
        "isRequired": true,
        "supportsTranslations": true,
        "options": {
          "placeholder": "https:// or /",
          "sections": ["product", "category", "infoPage"]
        }
      }
    ]
  }
]

JSON translations¶

JSON translations

{
  "schema": {
    "pl_PL": {
      "Button": "Przycisk",
      "Button label": "Etykieta przycisku",
      "Webpage URL": "Adres URL"
    },
    "en_US": {
      "Button": "Button",
      "Button label": "Button label",
      "Webpage URL": "Webpage URL"
    }
  }
}