Organize Variables for Display in SMT

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

When you expose multiple variables in SMT, you should group those variables to make them more meaningful and intuitive to site administrators. Use the group() function to create group metadata in any Sass files within your theme as described in the following procedure.

To group variables in the SMT side panel:

Open the Sass file that contains the exposed variable you want to group.
Use the group() function within the comment tags to create an organizational scheme.

See The group() Function for details.
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.
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 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 group() Function

You introduce the group() function within comments, as you do with the editable() function. However, the group() function 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 Skin Manager.
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 of children.

Example group, child subgroup, and child variables in SMT side panel.

Parent (Group)
Child (Subgroup)
Child (Variable)

A top-level (parent) group displays as a heading in the SMT side panel, like PALETTE in the preceding example. If you add another subgroup, nested children display as expandable/collapsible subgroups, like Theme palette in the preceding example. 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.

Parent group and four nested subgroups as displayed in SMT side panel.

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.

Subgroup children, which must be variable names, appear as expandable/collapsible groups in SMT side panel.

Note:

The 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 automatically results in changes of any derived values. SMT administrators can further edit each derived value within the UI as well, assuming those variables are exposed for editing. See Style Definitions for more information about how these Sass structures work.

To group variables in the SMT side panel:

The group() Function

Example

Related Topics