Expose Sass Variables for Customization

You control which variables your theme exposes to site administrators by introducing metadata into your Sass files. Expose variables using the editable() function, as described in this section.

To expose a variable for customization:

Open the Sass file containing the variable you want to expose.

Create an inline comment (//) or a block comment (/* ... */) immediately following the variable declaration.

You can use either comment method. For example:

                $sc-primary-color: red; //

                $sc-primary-color: red; /*  */

Use the editable() function within your comment tags to declare the variable as editable.

See The editable() Function for details. This function is required.
Save the file.

If you are creating a new Sass file, you must declare the file within the theme’s manifest file and in the appropriate application entry point.

For example, you can define and declare a Sass variable that works in Checkout only. You add the containing Sass file to the theme manifest and the Checkout entry point. Later, when viewing your theme in the SMT Theme Skin Manager, your variable only appears in the SMT user interface when navigating to Checkout. If you want your variable to appear in multiple applications, you must declare the new file within each. Limiting global definitions to the BaseSassStyles module helps ensure functionality of global variables.

See Add a New File to a Theme for details.
Repeat this procedure for every variable you want to expose.

When ready, use the theme developer tools to test or deploy your theme. See Test and Deploy Your Theme for procedures on how to use these tools. Note that you must also activate your theme to make these changes available for SMT. See Manage Themes and Extensions for details.

The editable() Function

The metadata to expose a variable takes the form of an editable() function call wrapped inside a comment in your Sass files. This function call accepts a JSON object as its single argument with the following properties:

type – declares the variable type. This property is required.

Possible values include:
- color – displays a color picker in SMT.
- string – declares a value as a string (font-weight, font-style, thumbnail size, etc.).
Important:
SMT only supports color and string as values for the type property. To declare a number value or a font, use a string.
label – provides a formatted string to reference the variable in the SMT user interface. If not defined, SMT displays the Sass variable name as the label.
description – describes the variable in a long-formatted string. This property is optional.
options – provides a list of options as an array for the variable. Use this property to limit possible values using a dropdown list. See Limit Selections. This property is optional.

The following code snippet is an example of how to expose a color variable using inline notation:

            $sc-primary-color: red; // editable({"type": "color", "label": "Primary Color"})

You can also use the editable() function with block notation:

            $sc-primary-color: red; /* editable({
   "type": "color",
   "label": "Primary Color",
   "description": "Used mainly for 'call to action' elements."
})*/

Important:

The comment must start immediately after the variable declaration. This is essential for the Sass preprocessor to relate the variable name with the declared metadata in the comment.

Limit Selections

You can use the options property of the editable() function to specify one or more values within a dropdown list in SMT.

For example, you can declare a list of available font weights as selections within a list instead of requiring SMT administrators to manually enter a numeric value as a string.

In this example, each option’s value property is the value to be processed for $base-font-weight, and the text property is the corresponding option as viewed in the dropdown list:

              $base-font-weight: 200; /* editable({
    "type": "string",
    "label": "Font Weight",
    "options": [
        {"value": 200, "text": "light"},
        {"value": 400, "text": "normal"},
        {"value": 800, "text": "bold"}]
}) */

You can also apply this option to colors. Using the option property on a color requires the SMT administrator to choose from a list of possible colors instead of using a color picker. Note that the option value must be a string in this case.

The following example displays a list of color options:

              $feedback-color: white ; /* editable({
    "type": "color",
    "label": "Feedback Color",
    "options": [
        {"value": "white", "text": "normal"},
        {"value": "black", "text": 'contrast'},
        {"value": "#ededed", "text": 'low contrast'}
    ]
}) */

To expose a variable for customization:

The editable() Function

Limit Selections

Related Topics