Expose Sass Variables for Customization

This topic applies to

Applies to

SuiteCommerce Web Stores

You control the variables that your theme exposes for customization by introducing metadata into your Sass files. You expose variables using the editable() function as described in this section.

To expose a variable for customization:

  1. Open the Sass file containing the variable you want exposed.

  2. 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; /*  */
  3. Use the editable() function within your comment tags to declare the variable as editable.

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

  4. Save the file.

    If you are creating a new Sass file, you must declare the file within the manifest file and the appropriate application entry point. See Add a New File to a Theme for details.

  5. Repeat this procedure for every variable you want to expose.

For exposed variables to appear in Site Management Tools, you must declare the Sass file containing the variable and its metadata in the manifest file and entry points for each application using that variable.

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 Customizer, 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.

When you are ready, use the theme developer tools to test or deploy your theme. See Theme Developer Tools for procedures on how to use these tools. See

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. If you wish to declare a number value or a font, you must do so as 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'}
    ]
}) */