Custom Theme Settings Overview (Theme Designer Perspective)


Theme Settings for the Theme Designer


This update is aimed at the technical side of theme settings. This information is for designers using our prebuilt themes.

Theme designers can create arbitrary setting for further control over the theme.This includes things like:

  • Logo
  • Tagline
  • Showing/Hiding things
  • Having multiple options for things.
  • Changing Colors/Backgrounds/Fonts for specific elements
  • On and on.


To create these settings, the easiest way is to use the Custom Theme Settings editor in the Theme Admin.


NOTE: This option is only available on sites flagged as Designer Sandboxes. You will need to contact Support to have this feature enabled.



To create a setting Click New

Part 1 : Configuration Settings

This page lets you configure a new setting, and how it will look in the UI.



The bottom of the overlay will show how the actual setting information is stored.


If the Theme Designer fancies him/herself as being advanced, he/she can edit the settings data directly: 


It’s important to not create duplicate Setting Names since the name is how the settings are looked up.


Settings can be either “Config” or “Style”



Settings can be grouped together in any group.



Groups are created by the Theme Designer also and can be created by selecting “Other/New Group”



Selecting the input type determines how the setting will be used and appear in the UI.



Whichever Input type the designer allows them to set the default value for that setting.






The UI for “dropdown” is a little different as the User has to add the available options for the dropdown



Settings can also be targeted to only show on specific Page Types (Category, Product, Login, etc)



NOTE: By default, settings are Global and will appear in the Global Theme Settings section in Live Design.


Part 2 : Implementing the setting(s)



Settings can be implemented in the theme several ways.


1. Plain Merge code:

##SETTING[Name of Setting]##
##THEMESETTING[Name of Setting]##

##SETTING[]## and ##THEMESETTING[]## are interchangeable.

If the setting is a “text” input it will simply render out the text of the field (with merges processed) 

NOTE: This will render a <span> tag around the text for live updating in live design, so if <span>’s have some kind of styling, it could create a discrepancy between admin/non-admin sessions.
To avoid this, see next option:


2. Merge Code with options:

The ##THEMESETTING[]## merge can take a second parameter of ‘text’, ‘value’, or ‘img’


will render the text of what is shown for the selected option of a dropdown setting. This will also render just plain text without the <span> wrapper as mentioned before.
##THEMESETTING[Test Dropdown Setting,text]##



This will render the value of the selected option for a dropdown setting:
##THEMESETTING[Test Dropdown Setting,value]##



This will render the setting as the “src” of an image:



this also allows for live updating via Live Design:

without the ‘img’ parameter you get something silly and useless:



3. Conditional

There is a new conditional syntax that can be used with theme settings. The new syntax supports things like else, elseif, as well as nesting.

An example use case of a nested conditional:

Show Social Icons – If off it hides the whole social icon section
Show [Service] Icon – hides individual social service icons but only if the first setting is checked.



Valid tags are <ac:if> <ac:else> <ac:elseif>

The available attributes are “setting” and “value”

These can be used on any type of setting. Checkbox settings are just assumed to be checking true/false so the value attribute is not necessary, other types of settings you can specify what value to check:



Part 3 : Style settings


Style settings allow the theme designer to give the user limited control over specific page elements.


They are configured similar to config settings but have a few different options.


They must come up with a good CSS selector for the element(s) they are trying to target as well as which properties they want to be changeable.


If they select a PageType they setting will only show up when viewing that pagetype AND the selector is prepended with a specific class for that PageType. This keeps the css from applying to the same elements but on other pages.




The Add to Cart button on the Product page can be styled differently from the Add to Cart buttons on Category pages, or anywhere else an Add To Cart button may be.



The available settings in the “Page Settings” section will vary from page to page based on this. Some pages will not have any “Page Settings”




Depending on which properties are checked determines where the setting will show up in the panel.


Colors = Text Color, Border Color, and BG Color (only if BG Image is not also selected)

Backgrounds = BG Color and BG Image

Fonts = Font Family and Font Size



NOTE: BG Color will ONLY show up in the Colors section if BG Image is NOT also selected. This is intentional due to the fact that background-image in CSS overrides a color. This is to eliminate possible confusion if something has a bgimage set and the customer is trying to change the color but doesn’t see changes applying.

This really could be confusing either way so this may change based on feedback.


All style settings apply in real time (but are only temporary until saved)


Color picker control:



The Background Image picker allows to choose from over a 100 default patterns.


Theme Designers can add their own background images to this list by uploading images to /Shared/Themes/[Theme]/Settings/Backgrounds



There is also an upload/insert icon to the right of the preview which is a miniature version of the Admin Filepicker.


Customers can insert from the store, upload via normal system file browser, external url, or from a list of recent files.




The Font editor is pretty self-explanatory



They can choose the font family and font size (if allowed) as well as choose Bold, Italic, Underline, or Strike

Have more questions? Submit a request