Go to the new documentation
EN IT

Custom variables

In addition to the predefined variables, you can define your own variables whose values can be set in the admin without having to edit the template source code.

Custom variables are defined in the editor.json file, inside the template folder, and they will have a unique name that you choose, a type (for example checkbox, text, etc.), a label and notes used to build the admin interface where the value can be changed. Besides these properties there are others that vary according to the variable type.

Example

We want a simple way to show or hide promotions on the store home page whenever we need.

Define the variable

In the editor.json file you can define a new variable called showPromotions of type checkbox with a default value of true and with a label in English and Italian:

    "variables": [
        …
        {
            "name" : "showPromotions",
            "type" : "checkbox",
            "label" : {
                "en" : "Display promotions on the home page",
                "it" : "Mostra le promozioni sulla home page"
            },
            "default" : true
        },
        …
    ]

Set a value

The admin interface is generated automatically based on the custom variables that have been defined. So in the admin you can set a value and change it whenever you want:

Use it in the template

In the template you can use it, in this example only on the home page, like this:

  <!-- .if editor.showPromotions -->
  <!-- .show promotions -->
  ...
  <!-- .end -->
  <!-- .end if -->

So the site pages can change accordingly to the value set in the admin.

Note that the name of a custom variable, when used in the template, must always be preceded by "editor." so it can be distinguished from predefined variables.

Fields

The following are the fields that can be used when defining a custom variable in the editor.json file.

Field Description
"name" Name. There must not be multiple variables with the same name. The name is case insensitive, for example "welcome" and "Welcome" are considered the same name
"type" Type. It can be "text", "textarea", "checkbox", "radio", "select" or "image"
"label" Label with the translation for each admin language. It is shown in the admin to briefly describe the field
"description" Variable description. It is shown in the admin
"placeholder" Placeholder. If the variable is multi-language then the translation for each site language should be present
"isMultiLanguage" Indicates whether values change based on the site language
"groups" Option groups. Used only for the "select" type and optional. In the "group" field of each option you can indicate the index of the group in which to show the option
"options" Possible options. Required for "radio" and "select" types
"default" Default value. It is not meaningful if "isMultiLanguage" is equal to true. For "radio" and "select" variables, if present it must be equal to the value of one of the options. For "image" variables, if present it is the image URL in the form "https://www.domain.com/image.jpg" or "/image.jpg" if the image is in the template folder

Custom variable types

The following are the custom variable types with the possible fields for each type and optional fields in gray.

text

editor.json

"variables" : [ … {
    "name" : "welcome",
    "type" : "text",
    "label" : {
        "en" : "Welcome message",
        "it" : "Messaggio di benvenuto"
    },
    "description" : {
        "en" : "Welcome message to show when the customer is logged",
        "it" : "Messaggio di benvenuto da mostare quanto il cliente è loggato"
    },
    "placeholder" : {
        "en" : "Welcome",
        "it" : "Benvenuto",
        "es" : "Bienvenido"
    },
    "isMultiLanguage" : true,
    "default" : ""
}, … ],

textarea

editor.json

"variables" : [ … {
    "name" : "welcome",
    "type" : "textarea",
    "label" : {
        "en" : "Welcome message",
        "it" : "Messaggio di benvenuto"
    },
    "description" : {
        "en" : "Welcome message to show when the customer is logged",
        "it" : "Messaggio di benvenuto da mostare quanto il cliente è loggato"
    },
    "placeholder" : "Benvenuto",
    "isMultiLanguage" : false,
    "default" : "Benvenuto sul nostro sito"
}, … ],

checkbox

editor.json

"variables" : [ … {
    "name" : "showPromotions",
    "type" : "checkbox",
    "label" : {
        "en" : "Display promotions on the home page",
        "it" : "Mostra le promozioni sulla home page"
    },
    "description" : {
        "en" : "Indicates whatever display the promotions on the home page",
        "it" : "Indica se mostrare le promozioni sulla home page"
    },
    "default" : true
}, … ],

radio

editor.json

"variables" : [ … {
    "name" : "align",
    "type" : "radio",
    "label" : {
        "en" : "Image align",
        "it" : "Allineamento immagine"
    },
    "description" : {
        "en" : "Choose whether to align the images to the left, center or to the right",
        "it" : "Scegliere se allineare le immagini a sinistra, al centro o a destra"
    },
    "options" : [ {
        "label" : {
            "en" : "Left",
            "it" : "Sinistra"
        },
        "value" : "left"
    }, … ],
    "default" : "left"
}, … ],

select

editor.json

"variables" : [ … {
    "name" : "color",
    "type" : "select",
    "label" : {
        "en" : "Color",
        "it" : "Colore"
    },
    "description" : {
        "en" : "Color of page title",
        "it" : "Colore del titolo della pagina"
    },
    "groups" : [ {
        "label" : {
            "en" : "Reds",
            "it" : "Rossi"
        }
    }, … ],
    "options" : [ {
        "label" : {
            "en" : "Tomato",
            "it" : "Pomodoro"
        },
        "value" : "#FF6347",
        "group" : 0
    }, … ],
    "default" : "#FF6347"
}, … ],

image

Credit card logos:

editor.json

"variables" : [ … {
    "name" : "showPromotions",
    "type" : "image",
    "label" : {
        "en" : "Credit card logos",
        "it" : "Loghi carte di credito"
    },
    "description" : {
        "en" : "Image for credit cart logos",
        "it" : "Immagine per i loghi delle carte di credito"
    },
    "default" : "/images/credit-cards.png"
}, … ],