Template Files
Templates Directory
Custom Templates
Customize Stencil Checkout
Handlebars Syntax and Helpers
Handlebars.js
Handlebars Helpers
Stencil Object Model
Stencil Objects

Custom Sass Functions

stencilColor Function

stencilColor accepts (as a string) the key name of a color that you have defined in config.json as editable. It returns the color’s hexadecimal value.

In Stencil’s Cornerstone (1.4.0) base theme, the optimized-checkout.scss file sets the background color for the page’s header with the following code:

.optimizedCheckout-header {
    background-color: stencilColor("optimizedCheckout-header-backgroundColor");
    // scss-lint:disable StringQuotes
    background-image: url(stencilImage('optimizedCheckout-backgroundImage', 'optimizedCheckout-backgroundImage-size'));
    // scss-lint:enable StringQuotes
    background-size: cover;
    ...
}

The above CSS fetches the background-color property’s value by using the stencilColor() function to retrieve the optimizedCheckout-header-backgroundColor key’s current value.

That optimizedCheckout-header-backgroundColor key is defined, and assigned a default value, in config.json. However, merchants can use Theme Editor to change the value at any time. So using this stencilColor() call, the key’s current value (which might have been altered from the static default value in config.json) will be fetched from a BigCommerce settings server.


stencilFontFamily Function

stencilFontFamily accepts (as a string) the name of a font key that you have defined in config.json. It returns the corresponding font-family value, also as a string. For a key named “headings-font” and defined as Google Open Sans, stencilFontFamily would return a value like this to Sass variables:

$headings-‐font-‐family: 'Open Sans';

(The above example’s name and definition in config.json are both arbitrary.)

Your Sass stylesheet must call stencilFontFamily for each config.json font key whose font-family value you want to provide to Sass variables. You would call the function in the following format (again assuming a key arbitrarily named “headings-font”):

$headings-font-family: stencilFontFamily("headings-font");


stencilFontWeight Function

stencilFontWeight accepts (as a string) the key name of a font that you have defined in config.json. It returns (as an integer) the corresponding font-weight value. For a key arbitrarily named “headings-font” and defined as 700, it would return a value like this to Sass variables:

$headings-‐font-‐weight: 700;

Your Sass stylesheet may optionally call stencilFontWeight for each config.json font key whose weight value you want to provide to Sass variables. You would call the function in the following format:

$headings-font-weight: stencilFontWeight("headings-font");


stencilNumber Function

stencilNumber accepts (as a string) a key name that you have defined in config.json as editable. It also accepts (also as a string) an optional second parameter to define the unit. (This second parameter’s value defaults to "px".) It returns the corresponding numeric value, postfixed with the defined unit.

You can use this function with arithmetical operators. For example, assume that your config.json contains a "font-size" value of "3". The following statement would evaluate to 9rem.

stencilNumber("font-size", "rem") * 3


stencilString Function

stencilString accepts (as a string) a key name that you have defined in config.json as editable. It returns (also as a string) the key’s value. This function is used for purposes like defining font family names, or defining paths to images.


stencilImage Function

stencilImage accepts (as a string) a key name for an image url that you have defined in config.json. It also accepts (as a string) the key name for the image size that you have defined in config.json. It returns the string value of the image URL and the size.

Compiling Custom Sass Files

If you want to add your own custom Sass files, initiate auto-compilation of those files by including the associated tag in your HTML markup. Cornerstone’s Sass file is named:

/cornerstone/assets/scss/theme.scss

To add a custom Sass file, place it at this path location, using an arbitrary filename prefix as shown:

<theme-name>/assets/scss/<your-theme-or-file-name>.scss

For example, to use the Foundation Sass framework, you might need:

<theme-name>/assets/scss/main.scss <theme-name>/assets/scss/widgets.scss

Next, be sure the following tag is included within your <theme-name>/templates/layout/base.html file’s <head> tag, to compile your Sass to the specified object file:

{{stylesheet '/assets/css/theme.css'}}

While stencil start is running, it will recompile your custom Sass files to the specified <theme-name>/assets/css/theme.css file. (Note that this object file’s name is always the same, and is independent of your custom Sass files’ names.) For an additional example, please see Replacing Content Blocks.

Before You Customize

The Stencil framework is designed to support your incorporation of custom Sass files/frameworks. However, BigCommerce does not offer technical assistance on substitutions for, or customized versions of, Stencil’s default dependencies.