Organize Variables for Display in SMT

This topic applies to

Applies to

SuiteCommerce Web Stores

When you expose Sass variables for customization, SMT displays each exposed variable in the side panel. Without any organizational structure, these variables do not display in any meaningful, intuitive way. To aid SMT administrators when customizing their theme, you can define how each exposed variable displays in the SMT side panel. You do this by creating group metadata using the group() function as described in this section.

You can create group metadata in any Sass files within your theme.

To group variables in the SMT side panel:

  1. Open the Sass file within your theme development files that contains the exposed variable you want to group.

    You can place this in any location within the Sass file.

  2. Use the group() function within comment tags to create an organization scheme.

    Build your group schema here. See The group() Function for details.

  3. 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.

  4. Repeat this for every new variable you want to expose for your theme.

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. Note that you must also activate your theme to make these changes available for SMT. See Activate Themes and Extensions for details.

Related Topics

The group() Function

You introduce the group() function within comments, as you do with the editable() function. However, group() does not need to be located immediately after a variable declaration within a Sass file.

Note

Functionally, you can add the group() function at any point within your theme’s Sass files. However, as a best practice, introduce group() in the same file that contains the associated variable.


Each group() function call accepts a JSON object as its single argument with the following properties:

  • id – declares the group ID. This is used to define and reference the group.

  • label – provides a formatted string for the group to be shown in the SMT Theme Customizer.

  • description – describes the group in a long-formatted string. This property is optional.

  • children – provides an array of variable names or group IDs (for a nested subgroup). If declaring a variable, you must precede the variable with $. The SMT user interface mirrors the order of any children declared here.

    Note

    Any variables or subgroups listed here do not need to be defined before the group definition to be referenced as a group children.


This function lets you declare groups and organize your Sass variables in an intuitive way within the SMT side panel.

  1. Parent (Group)

  2. Child (Subgroup)

  3. Child (Variable)

A top-level (parent) group displays as a heading in the SMT side panel, such PALETTE. Should a further subgroup be necessary, nested children appear as expandable/collapsible subgroups, such as Theme palette. Children of a subgroup are variables exposed for editing. SMT only supports two group levels.

Example

The following code declares one parent group called Pallette-color and four children to create subgroups. Each of these children is defined later in the code. Any children of the subgroups are declared variables.

/*
group({
   "id": "palette-color",
   "label": "Palette",
   "description": "",
   "children": [
      "theme-palette",
      "neutral-shades",
      "text-colors",
      "container-colors"
   ]
})
*/

/*
group({
   "id": "theme-palette",
   "label": "Theme palette",
   "description": "",
   "children": [
      "$sc-color-theme",
      "$sc-color-theme-900",
      "$sc-color-theme-700",
      "$sc-color-theme-500",
      "$sc-color-theme-300",
      "$sc-color-theme-100",
      "$sc-color-primary",
      "$sc-color-secondary"
   ]
})
*/

/*
group({
   "id": "neutral-shades",
   "label": "Neutral palette",
   "description": "",
   "children": [
      "$sc-neutral-shade",
      "$sc-neutral-shade-700",
      "$sc-neutral-shade-500",
      "$sc-neutral-shade-300",
      "$sc-neutral-shade-0"
   ]
})
*/

/*
group({
   "id": "text-colors",
   "label": "Text",
   "description": "",
   "children": [
      "$sc-color-copy",
      "$sc-color-copy-dark",
      "$sc-color-copy-light",
      "$sc-color-link",
      "$sc-color-link-hover",
      "$sc-color-link-active"
   ]
})
*/

/*
group({
   "id": "container-colors",
   "label": "Containers",
   "description": "",
   "children": [
      "$sc-color-body-background",
      "$sc-color-theme-background",
      "$sc-color-theme-border",
      "$sc-color-theme-border-light"
   ]
})
*/

The preceding code, after it is deployed and activated for a domain, displays in the SMT side panel as depicted in the following images. The first image shows the parent group, Palette. and the four nested subgroups: Theme palette, Neutral shades, Text colors, and Containers.

Children of the parent group are the nested subgroups. Children of each subgroup must be variable names because SMT does not support more than two group levels. These appear as expandable/collapsible groups. SMT administrators can now edit the settings as they please.

Note

The design architecture style definitions used to maintain the Sass structures use derived/calculated values. By exposing derived colors, as in this example, any UI selections of the base value results in changes of any derived values automatically. SMT admins can further edit each derived value within the UI as well, assuming those variables are exposed for editing. See Style Definitions for more information on how these Sass structures work.