As you develop your custom uStore NG theme, you can choose to either hard code values, or make your theme flexible by using the Theme Editor in uStore Admin to allow non-technical administrators to easily customize your theme for different stores on the uStore server.

On the left, the Theme Editor displays a collapsable panel with different sections each with different controls that customize the selected theme. The panel includes sections that are configurable, and others that are pre-defined automatically by uStore.

The controls in the different Theme Editor sections can pass values to the theme as CSS Variables that are used to change colors, images, text, URLs, fonts, sizes and other attributes.

To add a control to the Theme Editor that passes a value to your theme, there are two parts to the process:

1. Adding or changing the configuration file (config.json) that controls the Theme Editor options.

2. Using the CSS Variables in your theme's React JS code.

The following documentation describes the config.json file stucture, how to define Theme Editor controls, and how to access the CSS Variables in your custom uStore theme.

The config.json file is in the top level of the theme package folder. It is used to pass information about the theme to uStore.

Since the config.json file is unique for each theme, each theme can have different Theme Editor controls in uStore Admin.

The JSON file has five top-level name-value pairs, four of which should not be modified:

• engineVersion - This is the theme engine version and should not be changed.
• uStoreVersion - This defines the version of uStore that the theme is designed to work with. In general, you will create a theme by starting the the AquaBlue theme from the same uStore version, so you will not change this. When upgrading a custom theme to a new uStore version, you should follow the instructions here: https://github.com/XMPieLab/uStore-NG/wiki/Upgrading-a-Custom-Theme
• name - This is set automatically by the theme publish script.
• displayName - This is set automatically by the theme publish script.

The customization object in the JSON is where you can control the Theme Editor.

The customization object contains two arrays:

• variables

  The variables array defines each of the individual controls in the theme editor.

• sections

  The sections array defines the:

  • top level sections that are shown in the Theme Editor, and
  • sub sections that are used to group the controls or variables displayed in the parent section.

In the sections array, you can change or add to the configurable sections that appear as the top-level collapsible panel menu on the left of the Theme Editor.

"sections":[ 
   { 
      "name": "Typography", 
      "displayName": "Typography" 
   }, 
   ...Other sections... 
] 

Subsections can also be defined if needed:

"sections":[ 
   { 
      "name": "HeaderAndFooter", 
      "displayName": "Header And Footer" 
      "subSections":[ 
         { 
            "name": "Header", 
            "displayName": "Header" 
         }, 
         { 
            "name": "Footer", 
            "displayName": "Footer" 
         } 
      ] 
   }, 
   ...Other sections... 
] 

The graphic below shows how the different areas of the above section code will appear:

Note that a dividing line will automatically appear in between subsections.

The variables array defines the controls that are available in the Theme Editor and the section on which they appear.

"variables": [
   {
      "cssVariableName": "--font-family",
      "defaultValue": "Open Sans",
      "control": {
         "type": "font-picker",
         "section": "Typography",
         "displayTexts": [
            {
               "key": "Title",
               "value": "Storefront font"
            }
         ]
      }
   },
   ...Other variables... 
] 

cssVariableName - (string) The name of the CSS variable that will be created in the theme. The name should be unique and start with "--". In your React code, you will get the value by the cssVariableName.

defaultValue - (string) Optional. The default value that will be pre-defined in the Theme Editor.

control - (object) A JSON object defining the type of control to display in the Theme Editor.

type - (string) One of: color-picker, font-picker, image-uploader, number-input, number-picker, text-input. (See below)

options - (object) An object containing specific parameters for the control. (See below)

displayTexts - (object) A set of strings to display in the control. (See below)

Control Type	Example	Options	Description
color-picker			Allows selection of a color that could be used in your theme for example: font color, line color, or background color.
font-picker			Allows selection of a web font that could be used in your theme.
image-uploader			Allows upload of an image asset that could be used in your theme. For example: a logo, banner or map.
number-input		{"unit": "px", "min": 50, "max": 300}	Allows selection of a number. For example: width, or height value. The Options define the unit of measurement (px, pt, etc) and minimum and maximum permitted values.
number-picker		{"unit": "px", "min": 50, "max": 300}	Allows selection of a number. For example width or height value. The Options define the unit of measurement (px, pt, etc) and minimum and maximum permitted values.
text-input		{"rows": 2}	Allows entry of a text value. For example a page title, heading or other text. The Options define the height of the text box displayed for the control.

The displayTexts is an array of objects that defines the text strings that are displayed for the control. For example:

If your uStore Admin will be used in different languages, you can make a change to your config.json file so that the display names in the Theme Editor will come from the Localization database instead of being only in the langauge defined in the config.json file.

If multiple languages are required, each displayName or displayTexts object can be edited to include a localizationKey:

"sections": [
   {
      "name": "Typography",
      "displayName": "Typography",
      "localizationKey": "ThemeEditor_TypographySectionName"
   }

The localizationKey should be a unique and descriptive value.

To add the localizationKey to the uStore Localization database, follow these steps:

1. Login to uStore admin and go to Presets > System Setup > Localization Resource.
2. Click Add New.
3. In the StringID field, enter the localizationKey name exactly as defined in the config.json. Select "AdminApp" as the ApplicationTypeID, and Save.
4. At the bottom of the list, click the arrow to go to the last page.
5. Your new localizationKey should be the last entry. Click the Edit icon next to your localizationKey.
6. Click Edit Localized Text.
7. Click Add New.
8. Next to CultureID, select one of the languages you will use in uStore Admin. Enter the localized text for the Section Name, or Control Name in that language, and click Save.
9. Repeat steps 4-8 for any other languages you will use in uStore admin.
10. Repeat steps 1-9 for any additional localizationKeys that you add to the config.json file.
11. After adding all the localizationKeys into the database via the uStore admin backoffice, you need to restart IIS to force uStore admin to re-read the localization. To do this, either reboot the uStore server, or run "iisreset" command in a cmd window on the server.

NOTE: If the localizationKey field is defined, the displayName or displayText field is ignored and a value is queried from the database. If the localizationKey is not found in the database for the culture used by uStore admin, "[no localization]" will be displayed instead.

If the control is setting a value that you want to use in your CSS files, you can use them easily in the usual way for CSS variables:

.header {
    padding: var(--header-padding-desktop);
    background: var(--header-background-color);
    border-bottom: 1px solid var(--color-line);
    color: var(--text-color-header);
    font-size: var(--text-size-regular);
    height: var(--header-height-desktop);
}

If the control is setting a value that you want to place as text, a graphic or URL in your theme, then a little more work is required:

First import a utility class to your React JS page:

import { getVariableValue } from '$ustoreinternal/services/cssVariables'

The getVariableValue function can then be used to get the value by specifying the CSS Variable name that you defined in the config.json file:

const title = getVariableValue('--aboutus-title')

Note that there are additional parameters that can be used with the getVariableValue function: getVariableValue(varName, defaultValue, isImageURL, isURL)

varName - (string) The name of the CSS variable to get the value from.

defaultValue - (string) A value to use if the CSS variable is null or empty.

isImageURL - (boolean) True or false, is the value an image? Images uploaded with the image-uploader control type will be stored in the assets folder, and setting this parameter to true will correctly apply the required path to the image.

isURL - (boolean) True or false, is the value a URL? When set to true, the function will check for local paths (for example: /product/10 or /category/2 ) and apply the correct prefix for the current theme, store id and culture.

A small code sample showing several examples is below:

render() {
   const title = getVariableValue('--aboutus-title', 'About Us')
   const logo = getVariableValue('--logo-image', require(`$assets/images/logo.png`), true)
   const pageURL = getVariableValue('--homepage-carousel-slide-1-button-url', '', false, true)

   return(
      <div>
         {/* text example */}
         <div>{title}</div>
	  
         {/* image example */}
         <div>
            <img src={logo} alt="logo" />
         </div>

         {/* URL example */}
         <div>
            <Link to={pageURL}>
               <a>Click Here</a>
            </Link>
         </div>
      </div>
   )
}