{"_id":"5608e61131beb60d001b655e","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","parentDoc":null,"__v":27,"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"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-09-28T07:02:41.934Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":7,"body":"[block:html]\n{\n  \"html\": \"All themes on the Stencil platform must provide at least one theme \\\"variation.\\\" <!-- (the theme’s main variation) You can add as many custom variations as you wish, --> You can add up to four total variations per theme, each with its own variation-specific settings.<br>\\n\\n<p></p>The following steps cover:<br>\\n\\n<ul>\\n  <li><a href=\\\"#CreateVar\\\">Creating and Naming a New Theme Variation</a></li>\\n <li><a href=\\\"#ChangeFont\\\">Changing a Theme Variation’s Font Family</a></li>\\n <li><a href=\\\"#VarPix\\\">Preparing a Variation’s Thumbnails</a></li>\\n <li><a href=\\\"#ChangeVar\\\">Using Stencil CLI to Change Variations</a></li>\\n</ul>\\n\\n\\n<h2> <A NAME=\\\"CreateVar\\\"></a>Creating and Naming a New Theme Variation <br>\\n(Cascading Settings from config.json)</h2>\\n\\nYou define variations in your <span class=\\\"inline-code\\\">&lt;theme-name&gt;/config.json</span> file. From the default Stencil theme’s config.json, here is the Light variation’s definition, followed by the head of the <span class=\\\"inline-code\\\">Bold</span> variation’s definition:<br>\\n\\n<p></p><pre>\\n\\\"variations\\\": [\\n{\\n  \\\"name\\\": \\\"Light\\\",\\n  \\\"id\\\": \\\"light\\\",\\n  \\\"meta\\\": {\\n    \\\"desktop_screenshot\\\": \\\"desktop_screenshot.jpg\\\",\\n    \\\"mobile_screenshot\\\": \\\"mobile_screenshot.png\\\",\\n    \\\"description\\\": \\\"This is the light style of the Stencil Theme\\\",\\n    \\\"demo_url\\\": \\\"https://stencil-light.mybigcommerce.com\\\",\\n    \\\"optimized_for\\\": [\\\"fashion\\\", \\\"image_heavy\\\", \\\"etc\\\"],\\n    \\\"industries\\\": []\\n  },\\n{\\n  \\\"name\\\": \\\"Bold\\\",\\n  \\\"id\\\": \\\"bold\\\",\\n...</pre>\\n\\n\\nTry inserting a new custom variation of your own, below the <span class=\\\"inline-code\\\">\\\"Light\\\"</span> block shown above. Your variation’s definition might look something like this:<br>\\n\\n<p></p><pre>\\\"variations\\\": [\\n...\\n<b>{\\n  \\\"name\\\": \\\"MyCustomVariation\\\",\\n  \\\"id\\\": \\\"my_custom_variation\\\",\\n  \\\"meta\\\": {\\n    \\\"desktop_screenshot\\\": \\\"my_custom_desktop_screenshot.jpg\\\",\\n    \\\"mobile_screenshot\\\": \\\"my_custom_mobile_screenshot.png\\\",\\n    \\\"description\\\": \\\"This is a really cool custom style of the Stencil Theme\\\",\\n    \\\"demo_url\\\": \\\"https://stencil-custom.mybigcommerce.com\\\",\\n    \\\"optimized_for\\\": [\\\"fashion\\\", \\\"image_heavy\\\", \\\"etc\\\"],\\n    \\\"industries\\\": []\\n  },</b>\\n{\\n  \\\"name\\\": \\\"Bold\\\",\\n  \\\"id\\\": \\\"bold\\\",\\n...</pre>\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Configuring Variations\",\n  \"body\": \"Each object within your <span class=\\\"inline-code\\\">config.json</span> file's <span class=\\\"inline-code\\\"><a href=\\\"#config-variations\\\">variations</a></span> collection defines one theme variation. \\nSo you control the number of variations in a theme by editing this file's <span class=\\\"inline-code\\\">variations</span> section. \\nAs you develop your themes, remember to delete entries for any variations you choose not to support.\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<h2> <A NAME=\\\"ChangeFont\\\"></a>Changing a Theme Variation’s Font Family (config.json)</h2>\\n\\nTo learn more about defining variations, see the <span class=\\\"inline-code\\\">config.json</span> <a href=\\\"/docs/configjson-reference\\\">reference</a> for details about each key’s usage and  allowable values. <br><p></p>\\n\\nIn particular, note the option to configure settings and variables that are scoped to each variation. For example, you could insert the <span class=\\\"inline-code\\\">\\\"settings\\\":...”body-font-family”</span> block shown below, to set body text throughout this variation (only) to a specific typeface/family:<br>\\n\\n<p></p><pre>{\\n  \\\"name\\\": \\\"MyCustomVariation\\\",\\n  \\\"id\\\": \\\"my_custom_variation\\\",\\n  \\\"settings\\\": {\\n    ...\\n    <b>\\\"body-font-family\\\": \\\"MyCoolFont, AnotherFont, sans-serif\\\",</b>\\n    ...\\n  }\\n}</pre>\\n\\n<h2> <A NAME=\\\"VarPix\\\"></a>Preparing a Variation's Thumbnails</h2>\\n\\nFor details on preparing screenshots that enable merchants to preview each variation &ndash; and to preview your theme as a whole &ndash; in the BigCommerce control panel and Theme Marketplace, please see <a href=\\\"/docs/preparing-thumbnail-images\\\">Preparing Thumbnail Images</a>.\\n\\n<h2> <A NAME=\\\"ChangeVar\\\"></a>Using Stencil CLI to Change Variations</h2>\\n\\nTo locally test/debug a specific variation of your theme, launch it by invoking the Stencil CLI’s (command-line interface’s) <span class=\\\"inline-code\\\">stencil start -v</span> switch. Depending on how you’ve named your variation in <span class=\\\"inline-code\\\">config.json</span>, you would type something like this on the command line:<br>\\n\\n<p></p><pre>\\nstencil start -v MyCustomVariation\\n</pre>\"\n}\n[/block]","excerpt":"","slug":"managing-theme-variations","type":"basic","title":"Managing Theme Variations"}

Managing Theme Variations


[block:html] { "html": "All themes on the Stencil platform must provide at least one theme \"variation.\" <!-- (the theme’s main variation) You can add as many custom variations as you wish, --> You can add up to four total variations per theme, each with its own variation-specific settings.<br>\n\n<p></p>The following steps cover:<br>\n\n<ul>\n <li><a href=\"#CreateVar\">Creating and Naming a New Theme Variation</a></li>\n <li><a href=\"#ChangeFont\">Changing a Theme Variation’s Font Family</a></li>\n <li><a href=\"#VarPix\">Preparing a Variation’s Thumbnails</a></li>\n <li><a href=\"#ChangeVar\">Using Stencil CLI to Change Variations</a></li>\n</ul>\n\n\n<h2> <A NAME=\"CreateVar\"></a>Creating and Naming a New Theme Variation <br>\n(Cascading Settings from config.json)</h2>\n\nYou define variations in your <span class=\"inline-code\">&lt;theme-name&gt;/config.json</span> file. From the default Stencil theme’s config.json, here is the Light variation’s definition, followed by the head of the <span class=\"inline-code\">Bold</span> variation’s definition:<br>\n\n<p></p><pre>\n\"variations\": [\n{\n \"name\": \"Light\",\n \"id\": \"light\",\n \"meta\": {\n \"desktop_screenshot\": \"desktop_screenshot.jpg\",\n \"mobile_screenshot\": \"mobile_screenshot.png\",\n \"description\": \"This is the light style of the Stencil Theme\",\n \"demo_url\": \"https://stencil-light.mybigcommerce.com\",\n \"optimized_for\": [\"fashion\", \"image_heavy\", \"etc\"],\n \"industries\": []\n },\n{\n \"name\": \"Bold\",\n \"id\": \"bold\",\n...</pre>\n\n\nTry inserting a new custom variation of your own, below the <span class=\"inline-code\">\"Light\"</span> block shown above. Your variation’s definition might look something like this:<br>\n\n<p></p><pre>\"variations\": [\n...\n<b>{\n \"name\": \"MyCustomVariation\",\n \"id\": \"my_custom_variation\",\n \"meta\": {\n \"desktop_screenshot\": \"my_custom_desktop_screenshot.jpg\",\n \"mobile_screenshot\": \"my_custom_mobile_screenshot.png\",\n \"description\": \"This is a really cool custom style of the Stencil Theme\",\n \"demo_url\": \"https://stencil-custom.mybigcommerce.com\",\n \"optimized_for\": [\"fashion\", \"image_heavy\", \"etc\"],\n \"industries\": []\n },</b>\n{\n \"name\": \"Bold\",\n \"id\": \"bold\",\n...</pre>" } [/block] [block:callout] { "type": "info", "title": "Configuring Variations", "body": "Each object within your <span class=\"inline-code\">config.json</span> file's <span class=\"inline-code\"><a href=\"#config-variations\">variations</a></span> collection defines one theme variation. \nSo you control the number of variations in a theme by editing this file's <span class=\"inline-code\">variations</span> section. \nAs you develop your themes, remember to delete entries for any variations you choose not to support." } [/block] [block:html] { "html": "<h2> <A NAME=\"ChangeFont\"></a>Changing a Theme Variation’s Font Family (config.json)</h2>\n\nTo learn more about defining variations, see the <span class=\"inline-code\">config.json</span> <a href=\"/docs/configjson-reference\">reference</a> for details about each key’s usage and allowable values. <br><p></p>\n\nIn particular, note the option to configure settings and variables that are scoped to each variation. For example, you could insert the <span class=\"inline-code\">\"settings\":...”body-font-family”</span> block shown below, to set body text throughout this variation (only) to a specific typeface/family:<br>\n\n<p></p><pre>{\n \"name\": \"MyCustomVariation\",\n \"id\": \"my_custom_variation\",\n \"settings\": {\n ...\n <b>\"body-font-family\": \"MyCoolFont, AnotherFont, sans-serif\",</b>\n ...\n }\n}</pre>\n\n<h2> <A NAME=\"VarPix\"></a>Preparing a Variation's Thumbnails</h2>\n\nFor details on preparing screenshots that enable merchants to preview each variation &ndash; and to preview your theme as a whole &ndash; in the BigCommerce control panel and Theme Marketplace, please see <a href=\"/docs/preparing-thumbnail-images\">Preparing Thumbnail Images</a>.\n\n<h2> <A NAME=\"ChangeVar\"></a>Using Stencil CLI to Change Variations</h2>\n\nTo locally test/debug a specific variation of your theme, launch it by invoking the Stencil CLI’s (command-line interface’s) <span class=\"inline-code\">stencil start -v</span> switch. Depending on how you’ve named your variation in <span class=\"inline-code\">config.json</span>, you would type something like this on the command line:<br>\n\n<p></p><pre>\nstencil start -v MyCustomVariation\n</pre>" } [/block]