{"_id":"5608e59ea7b2590d0089eae8","user":"55a6caa022cfa321008e01d6","category":{"_id":"5605f309a4574a0d00811366","version":"55a6e72f8cc73e0d00096638","__v":10,"pages":["5608e5448aedf50d0004cf93","5608e54fa7b2590d0089eae5","5608e58331beb60d001b655a","5608e59ea7b2590d0089eae8","5608e5c031beb60d001b655c","5608e5d28aedf50d0004cf95","5608e5f7a7cc2f0d00d9754a","5608e61131beb60d001b655e","5608efbdc5cff70d007d00ee","5669f132c3de130d00441858"],"project":"55a6e72e8cc73e0d00096635","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-09-26T01:21:13.347Z","from_sync":false,"order":4,"slug":"development-quick-start","title":"Development Quick Start"},"project":"55a6e72e8cc73e0d00096635","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"},"parentDoc":null,"__v":25,"updates":["5779be8b9748b80e00ef3d72","5779bf7950ffec0e00ca56d3"],"next":{"pages":[],"description":""},"createdAt":"2015-09-28T07:00:46.087Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":3,"body":"[block:html]\n{\n  \"html\": \"To customize your theme’s appearance at a global level, the values that you define in the <br><span class=\\\"inline-code\\\">&lt;theme-name&gt;/config.json</span> file interact with local resources. Your <span class=\\\"inline-code\\\">config.json</span> definitions set global defaults for templates, <a href=\\\"/docs/using-yaml-front-matter\\\">front-matter</a> attributes, and Handlebars resources throughout your theme. You can also define custom variables in <span class=\\\"inline-code\\\">config.json</span>, named according to your needs.<br><br>\\n\\nThe following steps cover:<br>\\n\\n<ul>\\n  <li><a href=\\\"#NewProductsEx\\\">New Products Example</a></li>\\n <li><a href=\\\"#LocalFM\\\">Changing Page Layout using Local Front Matter</a></li>\\n <li><a href=\\\"#SassRetrieve\\\">Retrieving Specific config.json Values through Sass</a></li>\\n <li><a href=\\\"#AddRemCompon\\\">Adding/Removing Components</a></li>\\n</ul>\\n\\n\\n<h2> <A NAME=\\\"NewProductsEx\\\"></a>New Products Example </h2>\\n\\nTo see how interactions with <span class=\\\"inline-code\\\">config.json</span> values work, first note the default values in <span class=\\\"inline-code\\\">config.json</span> for the <span class=\\\"inline-code\\\">homepage_new_products_count</span> and <span class=\\\"inline-code\\\">product_list_display_mode</span> keys:<br><br>\\n\\n<pre>{\\n\\\"settings\\\": {\\n  \\\"homepage_new_products_count\\\": 12,\\n  \\\"product_list_display_mode\\\": \\\"grid\\\",\\n  }\\n}</pre>\\n\\n\\nNext, use a text editor to open your <span class=\\\"inline-code\\\">&lt;theme-name&gt;templates/pages/home.html</span> file. Highlighted in bold below is a statement that uses the theme-wide settings above to customize an API request to the server.<br><br>\\n\\n(Note the reference to the <span class=\\\"inline-code\\\">homepage_new_products_count</span> key in the file’s <a href=\\\"/docs/using-yaml-front-matter\\\">front matter</a>, between the two \\\"<span class=\\\"inline-code\\\">---</span>\\\" delimiters. If your current theme’s <span class=\\\"inline-code\\\">home.html</span> front matter omits this <span class=\\\"inline-code\\\">products:new:limit</span> definition, paste it in for this demonstration.)<br><br>\\n\\n<pre>\\n---\\nproducts:\\n  new:\\n    limit: {{theme_settings.<b>homepage_new_products_count</b>}}\\n  featured:\\n    limit: {{theme_settings.homepage_featured_products_count}}\\n  top_sellers:\\n    limit: {{theme_settings.homepage_top_products_count}}\\ncarousel: {{theme_settings.homepage_show_carousel}}\\nblog:\\n    recent_posts:\\n        limit: {{theme_settings.homepage_blog_posts_count}}\\n---\\n{{#partial \\\"hero\\\"}}\\n\\n&lt;!-- [...] --&gt;\\n\\n{{/partial}}\\n{{> layout/base}}</pre>\\n\\n\\nIf you load your storefront’s home page (by default, <a href=\\\"http://localhost:3000\\\">http://localhost:3000</a>), you should see a \\\"New Products\\\" section that displays 12 products in a grid.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Related Topics\",\n  \"body\": \"You can also reference `config.json` variables via .Handlebars statements; see:\\n* [Bringing Handlebars Context Values into JavaScript](https://stencil.bigcommerce.com/docs/customizing-javascript#HBintoJS)\\n* [Calling Theme-Wide Variables via Handlebars](/docs/theme-wide-variables-via-handlebars)\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<h2> <A NAME=\\\"LocalFM\\\"></a>Changing Page Layout using Local Front Matter: Number of Featured Products</h2>\\n\\nLook again at your <span class=\\\"inline-code\\\">&lt;theme-name&gt;templates/pages/home.html</span> file’s front matter. As in the <a href=\\\"#NewProductsEx\\\">New Products</a> example, note how the presence and number of featured products delegates to your theme’s <span class=\\\"inline-code\\\">config.json</span> setting:<br><br>\\n\\n<pre>\\n---\\n[...]\\nproducts:\\n  featured:\\n      limit: {{theme_settings.homepage_featured_products_count}}\\n[...]\\n---\\n</pre>\\n\\n\\nNext, try changing the <span class=\\\"inline-code\\\">limit: {{theme_settings.homepage_featured_products_count}}</span> statement to a hard-coded <span class=\\\"inline-code\\\">limit: 2</span>, as indicated below in bold:<br>\\n\\n<pre>\\n---\\nproducts:\\n  // [...]\\n  featured:\\n      <b>limit: 2</b>\\n  // [...]  \\n---\\n\\n&lt;!-- [...] --&gt;\\n\\n{{#partial \\\"page\\\"}}\\n\\n&lt;!-- [...] --&gt;\\n\\n&lt;div class=\\\"main full\\\"&gt;\\n  {{#if products.featured}}\\n      {{> components/products/featured products=products.featured columns=2}}\\n  {{/if}}\\n&lt;/div&gt;\\n{{/partial}}\\n{{> layout/base}}</pre>\\n\\n\\nIf you now reload your storefront’s home page in your browser, you should see the number of displayed <NOBR>\\\"Featured Products\\\"</nobr> change from its default number (as specified in <span class=\\\"inline-code\\\">config.json</span>) to two.<br>\\n\\n<h2> <A NAME=\\\"SassRetrieve\\\"></a>Retrieving Specific config.json Values through Sass</h2>\\n\\nIn <span class=\\\"inline-code\\\">config.json</span>, <a href=\\\"#config-var-meta\\\">global variables</a> bring dynamic values into the framework. Sass imports these global variables’ values to gracefully handle data like theme-wide colors’ hexadecimal values, and to make the data available to Theme Editor. Here is one short snippet from <span class=\\\"inline-code\\\">config.json</span>:<br><br>\\n\\n<pre>\\n{\\n// [...]\\n\\\"color-highlight\\\": \\\"#00abc9\\\",\\n\\\"color-highlightDark\\\": \\\"#f2f2f2\\\",\\n\\\"color-highlightDarker\\\": \\\"#dfdfdf\\\",\\n// [...]\\n}</pre>\\n\\n\\nHere are the corresponding references in the default Stencil theme’s <span class=\\\"inline-code\\\">&lt;theme-name&gt;/assets/scss/settings/global/color/_color.scss</span> file:<br><br>\\n\\n<pre>\\n// [...]\\n$color-highlight:       stencilColor(\\\"color-highlight\\\");\\n$color-highlightDarker: stencilColor(\\\"color-highlightDarker\\\");\\n$color-highlightDark:   stencilColor(\\\"color-highlightDark\\\");\\n// [...]\\n</pre>\\n\\n\\nIn <span class=\\\"inline-code\\\">config.json</span>, try redefining one or more color variables to hex values of your choice. Then re-render your theme’s home page to see the effects.<br>\\n\\n<h2> <A NAME=\\\"AddRemCompon\\\"></a>Adding/Removing Components (Handlebars)</h2>\\n\\nThe storefront properties that Stencil abstracts as <a href=\\\"/docs/developing-with-handlebars\\\">Handlebars resources</a>  are completely portable between HTML files. For an example of how this works, first open any storefront page in a browser. In the page’s footer, note the appearance of product Categories.<br><br>\\n\\nNext, open your <span class=\\\"inline-code\\\">&lt;theme-name&gt;/templates/components/common/footer.html</span> file in a text editor. As indicated below, cut (or copy and comment out) the code section shown below, and keep it on your Clipboard:<br><br>\\n\\n<pre>\\n&lt;footer class=\\\"footer\\\" role=\\\"contentinfo\\\"&gt;\\n  &lt;div class=\\\"container\\\"&gt;\\n      &lt;section class=\\\"footer-info\\\"&gt;\\n          &lt;!-- [...] --&gt;\\n<strike>&lt;article class=\\\"footer-info-col footer-info-col--small\\\"&gt;\\n  &lt;h5 class=\\\"footer-info-heading\\\"&gt;{{lang 'footer.categories'}}&lt;/h5&gt;\\n  &lt;ul class=\\\"footer-info-list\\\"&gt;\\n      {{#each categories}}\\n      &lt;li&gt;\\n          &lt;a href=\\\"{{url}}\\\"&gt;{{name}}&lt;/a&gt;\\n      &lt;/li&gt;\\n      {{/each}}\\n  &lt;/ul&gt;\\n&lt;/article&gt;</strike>\\n</pre>\\n\\n\\nIf you now refresh the storefront page in your browser, the Categories list should disappear from the footer.<br><br>\\n\\nNext, create a new <span class=\\\"inline-code\\\">&lt;theme-name&gt;/templates/components/footer/</span> subdirectory. Paste the code block from the previous cut/copy into a new file named <span class=\\\"inline-code\\\">&lt;theme-name&gt;/templates/components/footer/categories.html</span>, and save it:<br><br>\\n\\n<pre>\\n&lt;article class=\\\"footer-info-col footer-info-col--small\\\"&gt;\\n  &lt;h5 class=\\\"footer-info-heading\\\"&gt;{{lang 'footer.categories'}}&lt;/h5&gt;\\n  &lt;ul class=\\\"footer-info-list\\\"&gt;\\n      {{#each categories}}\\n      &lt;li&gt;\\n          &lt;a href=\\\"{{url}}\\\">{{name}}&lt;/a&gt;\\n      &lt;/li&gt;\\n      {{/each}}\\n  &lt;/ul&gt;\\n&lt;/article&gt;\\n</pre>\\n\\n\\nNext, back in <span class=\\\"inline-code\\\"><theme-name>/templates/components/common/footer.html</span>, add a reference to your new path/file, as indicated below in bold:<br><br>\\n\\n<pre>\\n&lt;footer class=\\\"footer\\\" role=\\\"contentinfo\\\"&gt;\\n  &lt;div class=\\\"container\\\"&gt;\\n      &lt;section class=\\\"footer-info\\\"&gt;\\n          &lt;!-- [...] --&gt;\\n          <b>{{> components/footer/categories}}</b>\\n          &lt;!-- [...] --&gt;\\n      &lt;/section&gt;\\n  &lt;/div&gt;\\n&lt;/footer&gt;\\n</pre>\\n\\n\\nIf you now refresh storefront pages in your browser, the Categories list should reappear in the footer. The component returns even though you have moved its data resources to an arbitrary new location, and referenced them indirectly.\"\n}\n[/block]","excerpt":"How config.json Interacts with Handlebars and Front Matter","slug":"configjsonhandlebarsfront-matter-interactions","type":"basic","title":"config.json–Resource Interactions"}

config.json–Resource Interactions

How config.json Interacts with Handlebars and Front Matter

[block:html] { "html": "To customize your theme’s appearance at a global level, the values that you define in the <br><span class=\"inline-code\">&lt;theme-name&gt;/config.json</span> file interact with local resources. Your <span class=\"inline-code\">config.json</span> definitions set global defaults for templates, <a href=\"/docs/using-yaml-front-matter\">front-matter</a> attributes, and Handlebars resources throughout your theme. You can also define custom variables in <span class=\"inline-code\">config.json</span>, named according to your needs.<br><br>\n\nThe following steps cover:<br>\n\n<ul>\n <li><a href=\"#NewProductsEx\">New Products Example</a></li>\n <li><a href=\"#LocalFM\">Changing Page Layout using Local Front Matter</a></li>\n <li><a href=\"#SassRetrieve\">Retrieving Specific config.json Values through Sass</a></li>\n <li><a href=\"#AddRemCompon\">Adding/Removing Components</a></li>\n</ul>\n\n\n<h2> <A NAME=\"NewProductsEx\"></a>New Products Example </h2>\n\nTo see how interactions with <span class=\"inline-code\">config.json</span> values work, first note the default values in <span class=\"inline-code\">config.json</span> for the <span class=\"inline-code\">homepage_new_products_count</span> and <span class=\"inline-code\">product_list_display_mode</span> keys:<br><br>\n\n<pre>{\n\"settings\": {\n \"homepage_new_products_count\": 12,\n \"product_list_display_mode\": \"grid\",\n }\n}</pre>\n\n\nNext, use a text editor to open your <span class=\"inline-code\">&lt;theme-name&gt;templates/pages/home.html</span> file. Highlighted in bold below is a statement that uses the theme-wide settings above to customize an API request to the server.<br><br>\n\n(Note the reference to the <span class=\"inline-code\">homepage_new_products_count</span> key in the file’s <a href=\"/docs/using-yaml-front-matter\">front matter</a>, between the two \"<span class=\"inline-code\">---</span>\" delimiters. If your current theme’s <span class=\"inline-code\">home.html</span> front matter omits this <span class=\"inline-code\">products:new:limit</span> definition, paste it in for this demonstration.)<br><br>\n\n<pre>\n---\nproducts:\n new:\n limit: {{theme_settings.<b>homepage_new_products_count</b>}}\n featured:\n limit: {{theme_settings.homepage_featured_products_count}}\n top_sellers:\n limit: {{theme_settings.homepage_top_products_count}}\ncarousel: {{theme_settings.homepage_show_carousel}}\nblog:\n recent_posts:\n limit: {{theme_settings.homepage_blog_posts_count}}\n---\n{{#partial \"hero\"}}\n\n&lt;!-- [...] --&gt;\n\n{{/partial}}\n{{> layout/base}}</pre>\n\n\nIf you load your storefront’s home page (by default, <a href=\"http://localhost:3000\">http://localhost:3000</a>), you should see a \"New Products\" section that displays 12 products in a grid." } [/block] [block:callout] { "type": "info", "title": "Related Topics", "body": "You can also reference `config.json` variables via .Handlebars statements; see:\n* [Bringing Handlebars Context Values into JavaScript](https://stencil.bigcommerce.com/docs/customizing-javascript#HBintoJS)\n* [Calling Theme-Wide Variables via Handlebars](/docs/theme-wide-variables-via-handlebars)" } [/block] [block:html] { "html": "<h2> <A NAME=\"LocalFM\"></a>Changing Page Layout using Local Front Matter: Number of Featured Products</h2>\n\nLook again at your <span class=\"inline-code\">&lt;theme-name&gt;templates/pages/home.html</span> file’s front matter. As in the <a href=\"#NewProductsEx\">New Products</a> example, note how the presence and number of featured products delegates to your theme’s <span class=\"inline-code\">config.json</span> setting:<br><br>\n\n<pre>\n---\n[...]\nproducts:\n featured:\n limit: {{theme_settings.homepage_featured_products_count}}\n[...]\n---\n</pre>\n\n\nNext, try changing the <span class=\"inline-code\">limit: {{theme_settings.homepage_featured_products_count}}</span> statement to a hard-coded <span class=\"inline-code\">limit: 2</span>, as indicated below in bold:<br>\n\n<pre>\n---\nproducts:\n // [...]\n featured:\n <b>limit: 2</b>\n // [...] \n---\n\n&lt;!-- [...] --&gt;\n\n{{#partial \"page\"}}\n\n&lt;!-- [...] --&gt;\n\n&lt;div class=\"main full\"&gt;\n {{#if products.featured}}\n {{> components/products/featured products=products.featured columns=2}}\n {{/if}}\n&lt;/div&gt;\n{{/partial}}\n{{> layout/base}}</pre>\n\n\nIf you now reload your storefront’s home page in your browser, you should see the number of displayed <NOBR>\"Featured Products\"</nobr> change from its default number (as specified in <span class=\"inline-code\">config.json</span>) to two.<br>\n\n<h2> <A NAME=\"SassRetrieve\"></a>Retrieving Specific config.json Values through Sass</h2>\n\nIn <span class=\"inline-code\">config.json</span>, <a href=\"#config-var-meta\">global variables</a> bring dynamic values into the framework. Sass imports these global variables’ values to gracefully handle data like theme-wide colors’ hexadecimal values, and to make the data available to Theme Editor. Here is one short snippet from <span class=\"inline-code\">config.json</span>:<br><br>\n\n<pre>\n{\n// [...]\n\"color-highlight\": \"#00abc9\",\n\"color-highlightDark\": \"#f2f2f2\",\n\"color-highlightDarker\": \"#dfdfdf\",\n// [...]\n}</pre>\n\n\nHere are the corresponding references in the default Stencil theme’s <span class=\"inline-code\">&lt;theme-name&gt;/assets/scss/settings/global/color/_color.scss</span> file:<br><br>\n\n<pre>\n// [...]\n$color-highlight: stencilColor(\"color-highlight\");\n$color-highlightDarker: stencilColor(\"color-highlightDarker\");\n$color-highlightDark: stencilColor(\"color-highlightDark\");\n// [...]\n</pre>\n\n\nIn <span class=\"inline-code\">config.json</span>, try redefining one or more color variables to hex values of your choice. Then re-render your theme’s home page to see the effects.<br>\n\n<h2> <A NAME=\"AddRemCompon\"></a>Adding/Removing Components (Handlebars)</h2>\n\nThe storefront properties that Stencil abstracts as <a href=\"/docs/developing-with-handlebars\">Handlebars resources</a> are completely portable between HTML files. For an example of how this works, first open any storefront page in a browser. In the page’s footer, note the appearance of product Categories.<br><br>\n\nNext, open your <span class=\"inline-code\">&lt;theme-name&gt;/templates/components/common/footer.html</span> file in a text editor. As indicated below, cut (or copy and comment out) the code section shown below, and keep it on your Clipboard:<br><br>\n\n<pre>\n&lt;footer class=\"footer\" role=\"contentinfo\"&gt;\n &lt;div class=\"container\"&gt;\n &lt;section class=\"footer-info\"&gt;\n &lt;!-- [...] --&gt;\n<strike>&lt;article class=\"footer-info-col footer-info-col--small\"&gt;\n &lt;h5 class=\"footer-info-heading\"&gt;{{lang 'footer.categories'}}&lt;/h5&gt;\n &lt;ul class=\"footer-info-list\"&gt;\n {{#each categories}}\n &lt;li&gt;\n &lt;a href=\"{{url}}\"&gt;{{name}}&lt;/a&gt;\n &lt;/li&gt;\n {{/each}}\n &lt;/ul&gt;\n&lt;/article&gt;</strike>\n</pre>\n\n\nIf you now refresh the storefront page in your browser, the Categories list should disappear from the footer.<br><br>\n\nNext, create a new <span class=\"inline-code\">&lt;theme-name&gt;/templates/components/footer/</span> subdirectory. Paste the code block from the previous cut/copy into a new file named <span class=\"inline-code\">&lt;theme-name&gt;/templates/components/footer/categories.html</span>, and save it:<br><br>\n\n<pre>\n&lt;article class=\"footer-info-col footer-info-col--small\"&gt;\n &lt;h5 class=\"footer-info-heading\"&gt;{{lang 'footer.categories'}}&lt;/h5&gt;\n &lt;ul class=\"footer-info-list\"&gt;\n {{#each categories}}\n &lt;li&gt;\n &lt;a href=\"{{url}}\">{{name}}&lt;/a&gt;\n &lt;/li&gt;\n {{/each}}\n &lt;/ul&gt;\n&lt;/article&gt;\n</pre>\n\n\nNext, back in <span class=\"inline-code\"><theme-name>/templates/components/common/footer.html</span>, add a reference to your new path/file, as indicated below in bold:<br><br>\n\n<pre>\n&lt;footer class=\"footer\" role=\"contentinfo\"&gt;\n &lt;div class=\"container\"&gt;\n &lt;section class=\"footer-info\"&gt;\n &lt;!-- [...] --&gt;\n <b>{{> components/footer/categories}}</b>\n &lt;!-- [...] --&gt;\n &lt;/section&gt;\n &lt;/div&gt;\n&lt;/footer&gt;\n</pre>\n\n\nIf you now refresh storefront pages in your browser, the Categories list should reappear in the footer. The component returns even though you have moved its data resources to an arbitrary new location, and referenced them indirectly." } [/block]