Theme Customization Options

The Store Design > Customize page enables nontechnical users to customize theme options defined by the theme developer without needing to edit Twig, HTML or CSS code. The Store Design > Customize menu item will only be visible in a LemonStand store's admin panel for a theme that is being edited that has customization options.

Editing Custom Theme Options

From the Store Design > Customize page, you'll see a form that includes editable fields for the theme if any are defined (as described below). For the fields available, non-technical users can upload images, choose colors from a visual color picker, edit text values, and check or uncheck checkboxes depending on their preferences.

Defining Custom Theme Options

If you expand the Customization options section, you'll see that you have an easy way to create an unlimited number of user editable theme options that make it easy for a non technical user to customize their theme without any knowledge of HTML, CSS or Twig code. Users can edit these options for the currently active theme in their LemonStand admin from Store Design > Customize.

There are 4 types of theme options you can create. Each is described in more detail below along with some examples of potential uses. The examples provided are just a small sampling, possible uses are literally endless.

Type Description Examples of potential uses
Text Text options allow you to create user defined labels, content and even numeric limits that can be applied to easily customize the theme. Users will be presented with a text box to edit the value of this field from the Customize menu.
  1. Title text for the store
  2. Text labels (ie. heading text for a Featured Items section on your home page)
  3. Button labels (ie. customized label for the "Add to Cart" button)
  4. Contact details for use in a header, footer or contact page
  5. Social links for major social networks
  6. Pagination limits (ie. number of products displayed per page on a category listing page)
Color Colors are hexadecimal color values like #006fb9 that can be used to define colors used throughout your theme. When editing option fields of this type, users will be able to select a color using a visual color picker, which will select the hexadecimal value for them. More advanced users can enter the hex value for the color they'd like to use directly.
  1. Background colors
  2. Menu colors
  3. Button colors
  4. Footer colors
  5. Font colors
  6. Link colors
  7. Border colors
Image Image options define images that can be included as default images with your theme. You can reference them by using either an absolute path such as:
http://placehold.it/200X100
            
or a relative path that that theme. For example:
@images/zest-logo.png
            
Once defined users can optionally upload their own.
  1. Logo images
  2. Background images
  3. Favicons
  4. Carousel images
Checkbox Checkbox options define toggles for theme elements that users can turn on (by checking the checkbox) or off (by unchecking it).
  1. Include a subnavigation
  2. Turn a sidebar on or off
  3. Show an image carousel on the home page


You can add new theme options by clicking on the Add Row button, and remove selected options by clicking on the Remove Selected button.

Each theme option type you create must also include:

  • Code: This will define the code by which you'll reference this option value within your theme's Twig code. You can learn more about about how to access custom field values in your theme templates below.
  • Title: This is the label for the field that users will see in when editing your Theme's custom options.
  • Default: This is the default value for the theme option. We recommend that all theme options you add include a value for the default so that users can see how they affect the theme and change them if desired.

Accessing Custom Field Values in Theme Templates

Theme developers can create custom theme option fields as described above and access them from their theme's Twig code. The global theme object is a container for the theme customization options. The options are accessible by their code. Examples for each of the custom option types are below.

Text:

<title>{{ theme.title }}</title>>

Color:

<div style="background-color: {{ theme.footerColor }}">

Checkbox:

{% if theme.displayFooter %}     Footer markup {% endif %}

Image:

<img src="{{ theme.logoImage.thumbnail(500, 'auto') }}">

For CSS, you can include a style tag in the theme header, such as:

<style>
.something {
    background: {{ theme.somethingBackground }};
}
</style>

If the image is not uploaded, the default image will be used. Alternatively, Twig's default tag could be used for supplying default values for any custom field type.

Hidden Developer Features

Theme customization options can also be edited directly for advanced developers who work on their themes locally by editing the theme.yaml file that is included in any theme export ZIP file. There are also two theme customization features that are not currently visible in the LemonStand UI but can be used by advanced developers for theme customization directly in the theme.yaml file. Custom theme options support the comment field which, if provided, is displayed on the theme customization form below the corresponding UI element. Another hidden feature is the drop-down field type, which can be defined in the YAML format. Example:

customFields:
    headerColor: { type: color, title: 'Header color :-)', default: '#ff0000', comment: 'Header color comment' }
    someDropdown: { type: dropdown, title: 'Some dropdown', default: first, options: { first: 'First option', second: 'Second option' } }

The drop-down options are displayed as drop-down fields on the theme customization page.

Note: When defining custom theme options directly in the theme.yaml file, make sure to include them inside the ---. For example:

---
name: 'Zest Theme'
author: 'LemonStand'
website: 'https://lemonstand.com'
engine: twig
404: '404'
customFields:
    logoImage: { type: image, title: 'Logo Image', default: '@images/zest-logo.png', comment: 'Upload your logo! Recommended height of 77px.' }
    bannerImage: { type: image, title: 'Banner Image', default: '@images/zest-banner-bg.jpg', comment: 'Upload your own homepage banner! Recommended dimensions of 960px by 368px.' }
    bannerTitleText: { type: text, title: 'Banner Title Text', default: 'Zest', comment: 'Text used for the homepage banner title.' }
    bannerSentenceText: { type: text, title: 'Banner Sentence Text', default: 'A responsive LemonStand theme', comment: 'Text used for the homepage banner sentence.' }
    globalLinkColor: { type: color, title: 'Global Link Color', default: '#DC3E2F', comment: 'Color used for links throughout the website, including product names.' }
    globalLinkHoverColor: { type: color, title: 'Global Link Hover Color', default: '#9f261b', comment: 'Color used for links throughout the website when you hover your mouse cursor over.' }
    salePriceColor: { type: color, title: 'Sale Price Color', default: '#DC3E2F', comment: 'Color used for the sale price on the product page (old price is crossed out).' }
    saleBadgeColor: { type: color, title: 'Sale Badge Color', default: '#DC3E2F', comment: 'Color used for the sale badge displayed in product lists, when a product is on sale.' }
    buttonColor: { type: color, title: 'Button Color', default: '#DC3E2F', comment: 'Color used for Add To Cart and Checkout buttons.' }
    buttonHoverColor: { type: color, title: 'Button Hover Color', default: '#b92c1f', comment: 'Button color when you hover your mouse cursor over.' }
    buttonBorderColor: { type: color, title: 'Button Border Color', default: '#DC3E2F', comment: 'Border color for buttons.' }
    faviconImage: { type: image, title: 'Favicon Image', default: '@images/favicon.png', comment: 'Upload your favicon. Recommended dimmensions of 16px by 16px. You must use a .png file.' }
---