{"_id":"560b39ae4a1f990d00dc733a","__v":29,"user":"55a6caa022cfa321008e01d6","version":{"_id":"55a6e72f8cc73e0d00096638","project":"55a6e72e8cc73e0d00096635","hasReference":false,"__v":29,"hasDoc":true,"createdAt":"2015-07-15T23:05:19.125Z","releaseDate":"2015-07-15T23:05:19.125Z","categories":["55a6e7308cc73e0d00096639","55b7ed07aea7c8190058badb","5604567c0c78b00d0039b191","5605e6f23a93940d002b3e4a","5605f2bba4574a0d00811365","5605f309a4574a0d00811366","5608e3b98aedf50d0004cf8f","5608e4318aedf50d0004cf90","5608e6b5a7cc2f0d00d9754d","5608e6d331beb60d001b6560","5608f879a7cc2f0d00d97580","560b097887b71d0d000d3bd9","560b13cbafa0990d00979545","560b5cbec341310d00de2a01","560b5cd0c341310d00de2a02","566a35b81e08750d00a0c49b","566a3e8503b4b20d00d02a4a","567889d307bf6a0d0083edc8","569c8b7c15bb390d00db6f9d","56b254dc65ddf50d0076ba8f","57a8ebc4cdeea20e001d2a63","57e48a4000c8680e00fae6e7","5808216773557d0f00a1e428","58105ad54a8aa50f00aa4cba","58105bf298aea40f00afa3ba","58105f548a4aed0f00d67536","581061b898aea40f00afa3be","584b3de7e5f3a42300df6ef7","596839a75965d400155bb750"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"category":{"_id":"560b13cbafa0990d00979545","project":"55a6e72e8cc73e0d00096635","version":"55a6e72f8cc73e0d00096638","pages":["560b13f987b71d0d000d3bf6","560b394aaf40a70d003df31e","560b39669c7be70d00100bef","560b397d4a1f990d00dc7338","560b3991c341310d00de29de","560b39ae4a1f990d00dc733a","562ffd364445ae1900383e84","5642a810cc9d8e0d00adda69","5660daef89e82f0d008f6823","56a1e0b42255370d00ad5e9c"],"__v":10,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-09-29T22:42:19.181Z","from_sync":false,"order":13,"slug":"css-javascript-design-resources","title":"CSS and Design Assets"},"parentDoc":null,"project":"55a6e72e8cc73e0d00096635","updates":["5655165ad667280d00252ab1"],"next":{"pages":[],"description":""},"createdAt":"2015-09-30T01:23:58.158Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":5,"body":"[block:html]\n{\n  \"html\": \"<A NAME=\\\"CustomSassFn\\\"></a>Stencil provides several custom <a href=\\\"http://sass-lang.com/documentation/file.SASS_REFERENCE.html\\\">Sass</a> functions, which enable your Sass to access options that you have defined in your theme’s <a href=\\\"/docs/configjson-reference\\\"><span class=\\\"inline-code\\\">config.json</span> file</a> as editable in Theme Editor.<br>\\n\\n<p></p>This page covers:<br>\\n\\n<ul>\\n <li><a href=\\\"#Color\\\">stencilColor Function</a></li>\\n <li><a href=\\\"#FontFamily\\\">stencilFontFamily Function</a></li>\\n <li><a href=\\\"#FontWeight\\\">stencilFontWeight Function</a></li>\\n <li><a href=\\\"#Number\\\">StencilNumber Function</a></li>\\n <li><a href=\\\"#String\\\">stencilString Function</a></li>\\n <li><a href=\\\"#Compiling\\\">Compiling Custom Sass Files</a></li>\\n</ul>\\n\\n<h2> <A NAME=\\\"Color\\\"></a>stencilColor Function</h2>\\n\\n<span class=\\\"inline-code\\\">stencilColor</span> accepts (as a string) the key name of a color that you have defined in <span class=\\\"inline-code\\\">config.json</span> as editable. <NOBR>It returns</nobr> the color’s hexadecimal value.\"\n}\n[/block]\nIn 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:\n\n```\n.optimizedCheckout-header {\n    background-color: stencilColor(\"optimizedCheckout-header-backgroundColor\");\n    // scss-lint:disable StringQuotes\n    background-image: url(stencilImage('optimizedCheckout-backgroundImage', 'optimizedCheckout-backgroundImage-size'));\n    // scss-lint:enable StringQuotes\n    background-size: cover;\n    ...\n}\n```\n\nThe above CSS fetches the `background-color` property's value by using the `stencilColor()` function to retrieve the `optimizedCheckout-header-backgroundColor` key's current value.\n\nThat `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.\n[block:html]\n{\n  \"html\": \"<h2> <A NAME=\\\"FontFamily\\\"></a>stencilFontFamily Function</h2>\\n\\n<span class=\\\"inline-code\\\">stencilFontFamily</span> accepts (as a string) the name of a font key that you have defined in <span class=\\\"inline-code\\\">config.json</span>. It returns the corresponding font-family value, also as a string. For a key named <span class=\\\"inline-code\\\">\\\"headings-font\\\"</span> and defined as Google <NOBR>Open Sans,</nobr> <span class=\\\"inline-code\\\">stencilFontFamily</span> would return a value like this to Sass variables:<br>\\n\\n<p></p><pre>\\n$headings-‐font-‐family: 'Open Sans';\\n</pre>\\n\\n(The above example's name and definition in <span class=\\\"inline-code\\\">config.json</span> are both arbitrary.)<br><br>\\n\\nYour <a href=\\\"https://stencil.bigcommerce.com/v1.0/docs/settings-directory\\\">Sass stylesheet</a> must call <span class=\\\"inline-code\\\">stencilFontFamily</span> for each <span class=\\\"inline-code\\\">config.json</span> 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 <NOBR><span class=\\\"inline-code\\\">\\\"headings-font\\\"</span></nobr>):<br>\\n\\n<p></p><pre>\\n$headings-font-family: stencilFontFamily(\\\"headings-font\\\");\\n</pre>\\n\\n<h2> <A NAME=\\\"FontWeight\\\"></a>stencilFontWeight Function</h2>\\n\\n<span class=\\\"inline-code\\\">stencilFontWeight</span> accepts (as a string) the key name of a font that you have defined in <span class=\\\"inline-code\\\">config.json</span>. It returns <NOBR>(as an</nobr> integer) the corresponding font-weight value. For a key arbitrarily named <span class=\\\"inline-code\\\">\\\"headings-font\\\"</span> and defined as 700, it would return a value like this to Sass variables:<br>\\n\\n<p></p><pre>\\n$headings-‐font-‐weight: 700;\\n</pre>\\n\\nYour <a href=\\\"/docs/settings-directory\\\">Sass stylesheet</a> may optionally call <span class=\\\"inline-code\\\">stencilFontWeight</span> for each <span class=\\\"inline-code\\\">config.json</span> font key whose weight value you want to provide to Sass variables. You would call the function in the following format:<br>\\n\\n<p></p><pre>\\n$headings-font-weight: stencilFontWeight(\\\"headings-font\\\");\\n</pre>\\n\\n<h2> <A NAME=\\\"Number\\\"></a>stencilNumber Function</h2>\\n\\n<span class=\\\"inline-code\\\">stencilNumber</span> accepts (as a string) a key name that you have defined in <span class=\\\"inline-code\\\">config.json</span> as editable. It also accepts (also as a string) an optional second parameter to define the unit. (This&nbsp;second parameter’s value defaults to <span class=\\\"inline-code\\\">\\\"px\\\"</span>.) It returns the corresponding numeric value, postfixed with the defined unit.<br><br>\\n\\nYou can use this function with arithmetical operators. For example, assume that your <span class=\\\"inline-code\\\">config.json</span> contains a <span class=\\\"inline-code\\\">\\\"font-size\\\"</span> value of <span class=\\\"inline-code\\\">\\\"3\\\"</span>. The statement:  <br>\\n\\n<p></p><pre>stencilNumber(\\\"font-size\\\", \\\"rem\\\") * 3</pre>\\n\\n...would evaluate to <span class=\\\"inline-code\\\">9rem</span>.<br>\\n\\n<h2> <A NAME=\\\"String\\\"></a>stencilString Function</h2>\\n\\n<span class=\\\"inline-code\\\">stencilString</span> accepts (as a string) a key name that you have defined in <span class=\\\"inline-code\\\">config.json</span> 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.<br>\\n\\n<h2> <A NAME=\\\"Compiling\\\"></a>Compiling Custom Sass Files</h2>\\n\\nIf you want to add your own custom Sass files, initiate auto-compilation of those files by including the associated tag in your HTML markup. The default Stencil theme’s Sass file is named:<br>\\n\\n<p></p><pre>.../cornerstone/assets/scss/theme.scss</pre>\\n\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Prior to March 2017, Stencil's default theme installed with this different directory name:\\n<p></p><pre>.../stencil/assets/scss/theme.scss</pre>\",\n  \"title\": \"Default Path Name Updated from \\\"stencil\\\" to \\\"cornerstone\\\"\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"To add a custom Sass file, place it at this path location, using an arbitrary filename prefix as shown:<br>\\n\\n<p></p><pre>&lt;theme-name&gt;/assets/scss/&lt;your-theme-or-file-name&gt;.scss</pre>\\n\\n<p></p>For example, to use the Foundation Sass framework, you might need:<br>\\n\\n<p></p><pre>&lt;theme-name&gt;/assets/scss/main.scss\\n&lt;theme-name&gt;/assets/scss/widgets.scss</pre>\\n\\n<p></p>Next, be sure the following tag is included within your <span class=\\\"inline-code\\\">&lt;theme-name&gt;/templates/layout/base.html</span> file’s <span class=\\\"inline-code\\\">&lt;head&gt;</span> tag, to compile your Sass to the specified object file:<br>\\n\\n<p></p><pre>{{stylesheet '/assets/css/theme.css'}}</pre>\\n\\n<!-- Obsolete predecessor to the above ^ snippet:\\n <p></p><pre>&lt;link href=\\\"{{cdn '/assets/css/theme.css'}}\\\" rel=\\\"stylesheet\\\"&gt;</pre> -->\\n\\n<p></p>While <span class=\\\"inline-code\\\">stencil start</span> is running, it will recompile your custom Sass files to the specified <NOBR><span class=\\\"inline-code\\\">&lt;theme-name&gt;/assets/css/theme.css</span></nobr> 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 <a href=\\\"/docs/styling-theme-pages#SwapBlock\\\">Replacing Content Blocks</a>.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"The Stencil framework is designed to support your incorporation of custom Sass files/frameworks. However,&#160;BigCommerce does not offer technical assistance on substitutions for, or customized versions of, Stencil's default dependencies.\",\n  \"title\": \"Before You Customize\"\n}\n[/block]","excerpt":"","slug":"custom-sass-functions","type":"basic","title":"Custom Sass Functions"}

Custom Sass Functions


[block:html] { "html": "<A NAME=\"CustomSassFn\"></a>Stencil provides several custom <a href=\"http://sass-lang.com/documentation/file.SASS_REFERENCE.html\">Sass</a> functions, which enable your Sass to access options that you have defined in your theme’s <a href=\"/docs/configjson-reference\"><span class=\"inline-code\">config.json</span> file</a> as editable in Theme Editor.<br>\n\n<p></p>This page covers:<br>\n\n<ul>\n <li><a href=\"#Color\">stencilColor Function</a></li>\n <li><a href=\"#FontFamily\">stencilFontFamily Function</a></li>\n <li><a href=\"#FontWeight\">stencilFontWeight Function</a></li>\n <li><a href=\"#Number\">StencilNumber Function</a></li>\n <li><a href=\"#String\">stencilString Function</a></li>\n <li><a href=\"#Compiling\">Compiling Custom Sass Files</a></li>\n</ul>\n\n<h2> <A NAME=\"Color\"></a>stencilColor Function</h2>\n\n<span class=\"inline-code\">stencilColor</span> accepts (as a string) the key name of a color that you have defined in <span class=\"inline-code\">config.json</span> as editable. <NOBR>It returns</nobr> the color’s hexadecimal value." } [/block] 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. [block:html] { "html": "<h2> <A NAME=\"FontFamily\"></a>stencilFontFamily Function</h2>\n\n<span class=\"inline-code\">stencilFontFamily</span> accepts (as a string) the name of a font key that you have defined in <span class=\"inline-code\">config.json</span>. It returns the corresponding font-family value, also as a string. For a key named <span class=\"inline-code\">\"headings-font\"</span> and defined as Google <NOBR>Open Sans,</nobr> <span class=\"inline-code\">stencilFontFamily</span> would return a value like this to Sass variables:<br>\n\n<p></p><pre>\n$headings-‐font-‐family: 'Open Sans';\n</pre>\n\n(The above example's name and definition in <span class=\"inline-code\">config.json</span> are both arbitrary.)<br><br>\n\nYour <a href=\"https://stencil.bigcommerce.com/v1.0/docs/settings-directory\">Sass stylesheet</a> must call <span class=\"inline-code\">stencilFontFamily</span> for each <span class=\"inline-code\">config.json</span> 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 <NOBR><span class=\"inline-code\">\"headings-font\"</span></nobr>):<br>\n\n<p></p><pre>\n$headings-font-family: stencilFontFamily(\"headings-font\");\n</pre>\n\n<h2> <A NAME=\"FontWeight\"></a>stencilFontWeight Function</h2>\n\n<span class=\"inline-code\">stencilFontWeight</span> accepts (as a string) the key name of a font that you have defined in <span class=\"inline-code\">config.json</span>. It returns <NOBR>(as an</nobr> integer) the corresponding font-weight value. For a key arbitrarily named <span class=\"inline-code\">\"headings-font\"</span> and defined as 700, it would return a value like this to Sass variables:<br>\n\n<p></p><pre>\n$headings-‐font-‐weight: 700;\n</pre>\n\nYour <a href=\"/docs/settings-directory\">Sass stylesheet</a> may optionally call <span class=\"inline-code\">stencilFontWeight</span> for each <span class=\"inline-code\">config.json</span> font key whose weight value you want to provide to Sass variables. You would call the function in the following format:<br>\n\n<p></p><pre>\n$headings-font-weight: stencilFontWeight(\"headings-font\");\n</pre>\n\n<h2> <A NAME=\"Number\"></a>stencilNumber Function</h2>\n\n<span class=\"inline-code\">stencilNumber</span> accepts (as a string) a key name that you have defined in <span class=\"inline-code\">config.json</span> as editable. It also accepts (also as a string) an optional second parameter to define the unit. (This&nbsp;second parameter’s value defaults to <span class=\"inline-code\">\"px\"</span>.) It returns the corresponding numeric value, postfixed with the defined unit.<br><br>\n\nYou can use this function with arithmetical operators. For example, assume that your <span class=\"inline-code\">config.json</span> contains a <span class=\"inline-code\">\"font-size\"</span> value of <span class=\"inline-code\">\"3\"</span>. The statement: <br>\n\n<p></p><pre>stencilNumber(\"font-size\", \"rem\") * 3</pre>\n\n...would evaluate to <span class=\"inline-code\">9rem</span>.<br>\n\n<h2> <A NAME=\"String\"></a>stencilString Function</h2>\n\n<span class=\"inline-code\">stencilString</span> accepts (as a string) a key name that you have defined in <span class=\"inline-code\">config.json</span> 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.<br>\n\n<h2> <A NAME=\"Compiling\"></a>Compiling Custom Sass Files</h2>\n\nIf you want to add your own custom Sass files, initiate auto-compilation of those files by including the associated tag in your HTML markup. The default Stencil theme’s Sass file is named:<br>\n\n<p></p><pre>.../cornerstone/assets/scss/theme.scss</pre>\n" } [/block] [block:callout] { "type": "info", "body": "Prior to March 2017, Stencil's default theme installed with this different directory name:\n<p></p><pre>.../stencil/assets/scss/theme.scss</pre>", "title": "Default Path Name Updated from \"stencil\" to \"cornerstone\"" } [/block] [block:html] { "html": "To add a custom Sass file, place it at this path location, using an arbitrary filename prefix as shown:<br>\n\n<p></p><pre>&lt;theme-name&gt;/assets/scss/&lt;your-theme-or-file-name&gt;.scss</pre>\n\n<p></p>For example, to use the Foundation Sass framework, you might need:<br>\n\n<p></p><pre>&lt;theme-name&gt;/assets/scss/main.scss\n&lt;theme-name&gt;/assets/scss/widgets.scss</pre>\n\n<p></p>Next, be sure the following tag is included within your <span class=\"inline-code\">&lt;theme-name&gt;/templates/layout/base.html</span> file’s <span class=\"inline-code\">&lt;head&gt;</span> tag, to compile your Sass to the specified object file:<br>\n\n<p></p><pre>{{stylesheet '/assets/css/theme.css'}}</pre>\n\n<!-- Obsolete predecessor to the above ^ snippet:\n <p></p><pre>&lt;link href=\"{{cdn '/assets/css/theme.css'}}\" rel=\"stylesheet\"&gt;</pre> -->\n\n<p></p>While <span class=\"inline-code\">stencil start</span> is running, it will recompile your custom Sass files to the specified <NOBR><span class=\"inline-code\">&lt;theme-name&gt;/assets/css/theme.css</span></nobr> 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 <a href=\"/docs/styling-theme-pages#SwapBlock\">Replacing Content Blocks</a>." } [/block] [block:callout] { "type": "warning", "body": "The Stencil framework is designed to support your incorporation of custom Sass files/frameworks. However,&#160;BigCommerce does not offer technical assistance on substitutions for, or customized versions of, Stencil's default dependencies.", "title": "Before You Customize" } [/block]